SuperDoc 技能

SuperDoc 是一款现代化的 DOCX 编辑器，支持以编程方式操作文档，并提供完整的格式控制能力。

已安装版本：v1.17.0，位于 /usr/local/lib/node_modules/superdoc

快速开始

创建新文档

const { Document, Paragraph, TextRun } = require('superdoc');

const doc = new Document({
  sections: [{
    children: [
      new Paragraph({
        children: [
          new TextRun({ text: "Hello World", bold: true })
        ]
      })
    ]
  }]
});

// 保存为文件
const fs = require('fs');
const Packer = require('superdoc').Packer;
Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync('output.docx', buffer);
});

编辑已有文档

const { Document } = require('superdoc');
const fs = require('fs');

// 加载已有 DOCX 文件
const buffer = fs.readFileSync('input.docx');
const doc = await Document.load(buffer);

// 查找并替换文本
doc.sections[0].children.forEach(para => {
  para.children.forEach(run => {
    if (run.text) {
      run.text = run.text.replace(/Company A/g, 'Company B');
    }
  });
});

// 保存修改后的文档
const output = await Packer.toBuffer(doc);
fs.writeFileSync('output.docx', output);

模板生成（批量）

const { Document, Paragraph, TextRun } = require('superdoc');
const fs = require('fs');

// 加载模板
const template = fs.readFileSync('template.docx');

// 生成个性化文档
const clients = require('./clients.json');
for (const client of clients) {
  const doc = await Document.load(template);
  
  // 替换占位符
  doc.sections[0].children.forEach(para => {
    para.children.forEach(run => {
      if (run.text) {
        run.text = run.text
          .replace('{{NAME}}', client.name)
          .replace('{{EMAIL}}', client.email);
      }
    });
  });
  
  const output = await Packer.toBuffer(doc);
  fs.writeFileSync(`output/${client.id}.docx`, output);
}

常见工作流

文档创建流程

1. 导入所需类：Document、Paragraph、TextRun、Packer
2. 构建文档结构：包括 section 和 paragraph
3. 应用格式设置（加粗、斜体、字体、颜色等）
4. 使用 Packer.toBuffer() 或 Packer.toBlob() 导出

文档编辑流程

1. 加载已有 DOCX：调用 Document.load(buffer)
2. 遍历文档结构：doc.sections[i].children（获取段落）
3. 修改内容：更新 run.text 或格式属性
4. 保存：调用 Packer.toBuffer(doc)

错误处理

常见问题：

• 文件未找到：在调用 fs.readFileSync() 前检查路径是否正确
• DOCX 文件无效：将 Document.load() 包裹在 try-catch 中处理异常
• 内存超限：对于大批量处理，请分块执行（单次最多处理 100 份文档）

无头 Node.js 使用方式

SuperDoc 默认依赖浏览器 API。在 CLI 或无头环境中需额外配置：

初始化设置（一次性）：

npm install --global superdoc jsdom

模拟浏览器 API：

const { JSDOM } = require('jsdom');
const dom = new JSDOM('');
global.window = dom.window;
global.document = window.document;
global.localStorage = {
  getItem: () => null,
  setItem: () => {},
  removeItem: () => {}
};

// 此时可安全引入 SuperDoc
const { Document } = require('superdoc');

替代方案：使用 browser 工具
如需复杂渲染或依赖 UI 的功能，可使用 OpenClaw 的 browser 工具，在真实浏览器环境中运行 SuperDoc。

React 集成

安装：

npm install @superdoc-dev/react

基础用法：

import { SuperDocEditor } from '@superdoc-dev/react';
import { useState } from 'react';

function App() {
  const [doc, setDoc] = useState(null);
  
  return (
     {
        // 处理保存逻辑
        const blob = new Blob([buffer], { 
          type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' 
        });
        // 下载或上传该 Blob
      }}
    />
  );
}

关键 Props：

• document：Document 实例或 null
• onChange：文档内容变更时的回调函数
• onSave：用户触发保存时，传入 buffer 的回调函数
• toolbar：自定义工具栏配置（可选）

不建议使用 SuperDoc 的场景

• PDF 编辑：请使用 pdf-lib 等专用库
• 文档分析/摘要生成：建议结合文本提取 + LLM 实现
• OCR（光学字符识别）：请使用 tesseract 或云 OCR 服务
• 简单文本提取：推荐使用 mammoth.js（更轻量）
• 旧版 .doc 格式（非 .docx）：建议使用 LibreOffice 或在线转换工具

高级用法

如需查阅完整 API 参考、高级格式控制、修订跟踪（tracked changes）及自定义渲染等功能：

• 参见 references/superdoc-reference.md
• 代码仓库地址：https://github.com/superdoc-dev/superdoc

故障排查

“localStorage is not defined”
→ 添加 localStorage 模拟实现（详见“无头 Node.js 使用方式”章节）

“Cannot read property 'children' of undefined”
→ 文档结构可能为空；请检查 doc.sections.length > 0

大文件处理缓慢或崩溃
→ 建议分批处理；对大于 10MB 的文件考虑使用流式（streaming）方式

格式未被保留
→ 请确保仅修改对象属性，而非直接替换整个对象