DOCX 创建、编辑与分析 是做什么的?
概述
.docx 文件是一个包含 XML 文件的 ZIP 压缩包。
快速参考
| 任务 | 方法 |
|---|---|
| 读取/分析内容 | markitdown 或解包以获取原始 XML |
| 创建新文档 | 使用 docx-js - 见下方“创建新文档” |
| 编辑已有文档 | 解包 → 编辑 XML → 重新打包 - 见下方“编辑已有文档” |
读取内容
# 文本提取
markitdown document.docx > output.md
# 原始 XML 访问
python scripts/office/unpack.py document.docx unpacked/
接受修订
生成一个已接受所有修订的干净文档:
python scripts/accept_changes.py input.docx output.docx
创建新文档
使用 JavaScript 生成 .docx 文件,然后进行验证。安装:npm install -g docx
设置
const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
InternalHyperlink, Bookmark, FootnoteReferenceRun, PositionalTab,
PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader,
TabStopType, TabStopPosition, Column, SectionType,
TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
VerticalAlign, PageNumber, PageBreak } = require('docx');
const doc = new Document({ sections: [{ children: [/* 内容 */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));
验证
创建文件后,进行验证。如果验证失败,解包,修复 XML,并重新打包。
python scripts/office/validate.py doc.docx
页面尺寸
// 关键:docx-js 默认使用 A4,而非 US Letter
// 始终显式设置页面尺寸以获得一致的结果
sections: [{
properties: {
page: {
size: {
width: 12240, // 8.5 英寸(DXA 单位)
height: 15840 // 11 英寸(DXA 单位)
},
margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 英寸边距
}
},
children: [/* 内容 */]
}]
常见页面尺寸(DXA 单位,1440 DXA = 1 英寸):
| 纸张 | 宽度 | 高度 | 内容宽度(1 英寸边距) |
|---|---|---|---|
| US Letter | 12,240 | 15,840 | 9,360 |
| A4(默认) | 11,906 | 16,838 | 9,026 |
横向: docx-js 内部会交换宽度/高度,因此传入纵向尺寸,让它处理交换:
size: {
width: 12240, // 将短边作为宽度传入
height: 15840, // 将长边作为高度传入
orientation: PageOrientation.LANDSCAPE // docx-js 会在 XML 中交换它们
},
// 内容宽度 = 15840 - 左边距 - 右边距(使用长边)
样式(覆盖内置标题)
使用 Arial 作为默认字体(普遍支持)。保持标题为黑色以确保可读性。
const doc = new Document({
styles: {
default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt 默认
paragraphStyles: [
// 重要:使用精确的 ID 来覆盖内置样式
{ id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
run: { size: 32, bold: true, font: "Arial" },
paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // TOC 需要 outlineLevel
{ id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
run: { size: 28, bold: true, font: "Arial" },
paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
]
},
sections: [{
children: [
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("标题")] }),
]
}]
});
列表(绝不使用 Unicode 项目符号)
// ❌ 错误 - 切勿手动插入项目符号字符
new Paragraph({ children: [new TextRun("• 项目")] }) // 错误
new Paragraph({ children: [new TextRun("\u2022 项目")] }) // 错误
// ✅ 正确 - 使用带有 LevelFormat.BULLET 的 numbering config
const doc = new Document({
numbering: {
config: [
{ reference: "bullets",
levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
{ reference: "numbers",
levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
]
},
sections: [{
children: [
new Paragraph({ numbering: { reference: "bullets", level: 0 },
children: [new TextRun("项目符号项")] }),
new Paragraph({ numbering: { reference: "numbers", level: 0 },
children: [new TextRun("编号项")] }),
]
}]
});
// ⚠️ 每个 reference 创建独立的编号
// 相同的 reference = 继续(1,2,3 然后 4,5,6)
// 不同的 reference = 重新开始(1,2,3 然后 1,2,3)
表格
关键:表格需要双重宽度 - 同时设置表格上的 columnWidths 和每个单元格的 width。如果不设置两者,表格在某些平台上将渲染不正确。
// 关键:始终设置表格宽度以确保一致渲染
// 关键:使用 ShadingType.CLEAR(而非 SOLID)以防止黑色背景
const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
const borders = { top: border, bottom: border, left: border, right: border };
new Table({
width: { size: 9360, type: WidthType.DXA }, // 始终使用 DXA(百分比在 Google Docs 中会出错)
columnWidths: [4680, 4680], // 必须与表格宽度之和相等(DXA:1440 = 1 英寸)
rows: [
new TableRow({
children: [
new TableCell({
borders,
width: { size: 4680, type: WidthType.DXA }, // 也在每个单元格上设置
shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR 而非 SOLID
margins: { top: 80, bottom: 80, left: 120, right: 120 }, // 单元格内边距(内部,不加到宽度中)
children: [new Paragraph({ children: [new TextRun("单元格")] })]
})
]
})
]
})
表格宽度计算:
始终使用 WidthType.DXA — WidthType.PERCENTAGE 在 Google Docs 中会出错。
// 表格宽度 = columnWidths 之和 = 内容宽度
// US Letter 带 1 英寸边距:12240 - 2880 = 9360 DXA
width: { size: 9360, type: WidthType.DXA },
columnWidths: [7000, 2360] // 必须与表格宽度之和相等
宽度规则:
- 始终使用
WidthType.DXA— 绝不使用WidthType.PERCENTAGE(与 Google Docs 不兼容) - 表格宽度必须等于
columnWidths之和 - 单元格
width必须与相应的columnWidth匹配 - 单元格
margins是内部内边距;它们会减少内容区域,不会增加单元格宽度 - 对于全宽表格:使用内容宽度(页面宽度减去左右边距)
图片
// 关键:type 参数是必需的
new Paragraph({
children: [new ImageRun({
type: "png", // 必需:png、jpg、jpeg、gif、bmp、svg
data: fs.readFileSync("image.png"),
transformation: { width: 200, height: 150 },
altText: { title: "标题", description: "描述", name: "名称" } // 三者皆必需
})]
})
分页符
// 关键:PageBreak 必须在 Paragraph 内部
new Paragraph({ children: [new PageBreak()] })
// 或者使用 pageBreakBefore
new Paragraph({ pageBreakBefore: true, children: [new TextRun("新页面")] })
超链接
// 外部链接
new Paragraph({
children: [new ExternalHyperlink({
children: [new TextRun({ text: "点击此处", style: "Hyperlink" })],
link: "https://example.com",
})]
})
// 内部链接(书签 + 引用)
// 1. 在目标位置创建书签
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [
new Bookmark({ id: "chapter1", children: [new TextRun("第 1 章")] }),
]})
// 2. 链接到它
new Paragraph({ children: [new InternalHyperlink({
children: [new TextRun({ text: "查看第 1 章", style: "Hyperlink" })],
anchor: "chapter1",
})]})
脚注
const doc = new Document({
footnotes: {
1: { children: [new Paragraph("来源:2024 年度报告")] },
2: { children: [new Paragraph("方法论请参见附录")] },
},
sections: [{
children: [new Paragraph({
children: [
new TextRun("收入增长了 15%"),
new FootnoteReferenceRun(1),
new TextRun(" 使用调整后的指标"),
new FootnoteReferenceRun(2),
],
})]
}]
});
制表位
// 在同一行右对齐文本(例如,标题对侧的日期)
new Paragraph({
children: [
new TextRun("公司名称"),
new TextRun("\t2025 年 1 月"),
],
tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})
// 点前导符(例如,目录样式)
new Paragraph({
children: [
new TextRun("引言"),
new TextRun({ children: [
new PositionalTab({
alignment: PositionalTabAlignment.RIGHT,
relativeTo: PositionalTabRelativeTo.MARGIN,
leader: PositionalTabLeader.DOT,
}),
"3",
]}),
],
})
多列布局
// 等宽列
sections: [{
properties: {
column: {
count: 2, // 列数
space: 720, // 列间距(DXA,720 = 0.5 英寸)
equalWidth: true,
separate: true, // 列间垂直线
},
},
children: [/* 内容自然地在列间流动 */]
}]
// 自定义宽度列(equalWidth 必须为 false)
sections: [{
properties: {
column: {
equalWidth: false,
children: [
new Column({ width: 5400, space: 720 }),
new Column({ width: 3240 }),
],
},
},
children: [/* 内容 */]
}]
使用 type: SectionType.NEXT_COLUMN 的新节强制执行分栏符。
目录
// 关键:标题必须仅使用 HeadingLevel - 不使用自定义样式
new TableOfContents("目录", { hyperlink: true, headingStyleRange: "1-3" })
页眉/页脚
sections: [{
properties: {
page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 英寸
},
headers: {
default: new Header({ children: [new Paragraph({ children: [new TextRun("页眉")] })] })
},
footers: {
default: new Footer({ children: [new Paragraph({
children: [new TextRun("第 "), new TextRun({ children: [PageNumber.CURRENT] }), new TextRun(" 页")]
})] })
},
children: [/* 内容 */]
}]
docx-js 关键规则
- 显式设置页面尺寸 - docx-js 默认使用 A4;对于美国文档,使用 US Letter(12240 x 15840 DXA)
- 横向:传入纵向尺寸 - docx-js 内部会交换宽度/高度;将短边作为
width,长边作为height,并设置orientation: PageOrientation.LANDSCAPE - 绝不使用
\n- 使用单独的 Paragraph 元素 - 绝不使用 unicode 项目符号 - 使用带有 numbering config 的
LevelFormat.BULLET - PageBreak 必须在 Paragraph 内部 - 独立使用会创建无效 XML
- ImageRun 需要
type- 始终指定 png/jpg 等 - 始终使用 DXA 设置表格
width- 绝不使用WidthType.PERCENTAGE(在 Google Docs 中会出错) - 表格需要双重宽度 -
columnWidths数组和单元格width,两者必须匹配 - 表格宽度 = columnWidths 之和 - 对于 DXA,确保它们精确相加
- 始终添加单元格边距 - 使用
margins: { top: 80, bottom: 80, left: 120, right: 120 }以获得可读的内边距 - 使用
ShadingType.CLEAR- 表格底纹绝不使用 SOLID - 绝不使用表格作为分隔线/规则 - 单元格有最小高度,会渲染为空框(包括在页眉/页脚中);改为在 Paragraph 上使用
border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } }。对于双列页脚,使用制表位(参见制表位部分),而不是表格 - TOC 仅需要 HeadingLevel - 标题段落上不使用自定义样式
- 覆盖内置样式 - 使用精确的 ID:"Heading1"、"Heading2" 等。
- 包含
outlineLevel- TOC 需要(H1 为 0,H2 为 1,以此类推)
编辑已有文档
按顺序执行所有 3 个步骤。
步骤 1:解包
python scripts/office/unpack.py document.docx unpacked/
提取 XML,美观打印,合并相邻的 runs,并将智能引号转换为 XML 实体(“ 等),以便它们在编辑后得以保留。使用 --merge-runs false 跳过 run 合并。
步骤 2:编辑 XML
编辑 unpacked/word/ 中的文件。模式参见下方的 XML 参考。
除非用户明确要求使用不同的名称,否则将“Claude”作为修订和批注的作者。
直接使用编辑工具进行字符串替换。不要编写 Python 脚本。 脚本会引入不必要的复杂性。编辑工具会精确显示要替换的内容。
关键:为新内容使用智能引号。 添加带有撇号或引号的文本时,请使用 XML 实体生成智能引号:
<!-- 为专业排版使用这些实体 -->
<w:t>这是’一个引用:“你好”</w:t>
| 实体 | 字符 |
|---|---|
‘ | '(左单引号) |
’ | '(右单引号/撇号) |
“ | “(左双引号) |
” | ”(右双引号) |
添加批注: 使用 comment.py 处理跨多个 XML 文件的样板文件(文本必须是预先转义的 XML):
python scripts/comment.py unpacked/ 0 "包含 & 和 ’ 的批注文本"
python scripts/comment.py unpacked/ 1 "回复文本" --parent 0 # 回复批注 0
python scripts/comment.py unpacked/ 0 "文本" --author "自定义作者" # 自定义作者名称
然后在 document.xml 中添加标记(参见 XML 参考中的批注)。
步骤 3:打包
python scripts/office/pack.py unpacked/ output.docx --original document.docx
使用自动修复进行验证,压缩 XML,并创建最终的 .docx 文件。
XML 参考
(待翻译的 XML 参考部分,保持原有结构和代码块)
...(原文已截断)