SuperDoc 技能

SuperDoc 是一个现代化的 DOCX 编辑器，提供程序化文档操作和完整的格式控制。

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

快速入门

创建新文档

javascript
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);
});

编辑现有文档

javascript
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);

模板生成（批量）

javascript
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. 1. 导入所需类：Document、Paragraph、TextRun、Packer
2. 使用节和段落构建文档结构
3. 应用格式（粗体、斜体、字体、颜色）
4. 使用 Packer.toBuffer() 或 Packer.toBlob() 导出

文档编辑流程

1. 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/无头环境中：

设置（一次性）：
bash
npm install --global superdoc jsdom

填充浏览器 API：
javascript
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);

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

React 集成

安装：
bash
npm install @superdoc-dev/react

基本用法：
jsx
import { SuperDocEditor } from @superdoc-dev/react;
import { useState } from react;

function App() {
const [doc, setDoc] = useState(null);

return (
document={doc}
onChange={setDoc}
onSave={(buffer) => {
// 处理保存
const blob = new Blob([buffer], {
type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
});
// 下载或上传 blob
}}
/>
);
}

关键属性：

• - document：文档实例或 null
• onChange：文档变化时的回调
• onSave：用户保存时返回 buffer 的回调
• toolbar：自定义工具栏配置（可选）

何时不使用 SuperDoc

• - PDF 编辑：使用 pdf-lib 或类似工具
• 文档分析/摘要：使用文本提取 + LLM
• OCR：使用 tesseract 或云 OCR 服务
• 简单文本提取：使用 mammoth.js（更轻量）
• 旧版 .doc（非 .docx）：使用 LibreOffice 或在线转换器

高级用法

有关详细的 API 参考、高级格式、修订跟踪和自定义渲染：

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

故障排除

localStorage is not defined
→ 添加 localStorage 填充（参见无头使用部分）

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

大文件慢/崩溃
→ 分批处理；对于大于 10MB 的文件考虑使用流式处理

格式未保留
→ 确保修改属性，而不是替换对象