DOCX 创建、编辑和分析
.docx 文件是 XML 文件的 ZIP 压缩包。根据任务选择合适的方法:
| 任务 | 方法 |
|---|---|
| 创建新文档 | 编写 docx(npm)脚本 — 请参考下面的注意事项 |
| 编辑现有文档 | unzip → 编辑 word/document.xml → zip(docx-js 无法打开现有文件) |
| 读取内容 | pandoc -t markdown file.docx |
下面的脚本路径相对于本技能目录。
使用 docx-js 创建文档 — 注意事项
docx 已预安装 — 不要先运行 npm install;直接编写脚本并使用 require('docx')。仅当 require('docx') 失败时才运行 npm install docx。模型知道 API;以下是常见的陷阱:
- 页面尺寸默认为 A4。 若需美国信纸,请设置
page: { size: { width: 12240, height: 15840 } }(单位 DXA;1440 = 1 英寸)。 - 横向页面: 传入纵向尺寸并同时设置
orientation: PageOrientation.LANDSCAPE— docx-js 内部会自动交换宽/高。 - 表格需要双重宽度设置: 在表格上设置
columnWidths,同时在每个单元格上设置width,两者均使用WidthType.DXA(PERCENTAGE在 Google Docs 中会出错)。列宽之和必须等于表格宽度。 - 表格底纹: 使用
ShadingType.CLEAR,切勿使用SOLID(会导致渲染为黑色)。 - 列表: 切勿直接插入
•;应使用带有LevelFormat.BULLET的numbering配置。 ImageRun需要指定type:(如"png"、"jpg"等)。PageBreak必须放在Paragraph内部。- 切勿使用
\n— 应使用独立的Paragraph元素。 - 目录: 标题必须使用内置的
HeadingLevel.*;自定义标题样式需要设置outlineLevel,否则不会出现在目录中。 - 不要使用表格作为水平线 — 应改用段落底部边框。
- 点前导 / 同一行右对齐: 在
TextRun内部使用PositionalTab(alignment: PositionalTabAlignment.RIGHT、leader: PositionalTabLeader.DOT),不要使用文字上的.或空格填充。
验证输出
写入 .docx 后,渲染并查看它:
python scripts/office/soffice.py --headless --convert-to pdf output.docx
pdftoppm -jpeg -r 100 output.pdf page
ls page-*.jpg # 然后读取这些图片
pdftoppm 会将页码零填充至页码数的宽度(page-01.jpg…page-12.jpg)。
编辑现有文档
旧版 .doc 文件必须先转换:python scripts/office/soffice.py --headless --convert-to docx file.doc。
unzip -q doc.docx -d unpacked/
find unpacked -type l -delete # 删除符号链接条目 — 来自外部的 docx 文件不可信
python scripts/merge_runs.py unpacked/ # 合并碎片化运行,使文本可查找
# 原地编辑 unpacked/word/document.xml — 不要重新格式化或美化打印
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx # XSD 检查;--auto-repair 修复常见问题
# 需要修订跟踪?添加 --author "<您的修订者名称>" 以检查每个编辑都被跟踪
Word 会将文本分散到许多 <w:r> 运行中(修订ID、拼写检查标记等),因此您在文档中看到的短语在 XML 中通常不是连续的字符串。merge_runs.py 会合并 word/document.xml 中相邻且格式相同的运行,而不改变内容或渲染;它也接受直接传入 .docx 文件(python scripts/merge_runs.py doc.docx -o merged.docx)。
跟踪更改: 当进行修订时,使用 --author "<您的修订者名称>"(需要 --original)进行验证——它会报告您更改但未用 <w:ins>/<w:del> 包裹的任何文本(这很容易意外发生,且在“接受”视图中不可见)。将运行包裹在带有 w:id、w:author、w:date 属性的 <w:ins>/<w:del> 中。在 <w:del> 内部,文本元素是 <w:delText>,而不是 <w:t>。一个删除的段落标记(<w:pPr><w:rPr><w:del w:id=".." w:author=".." w:date=".."/></w:rPr></w:pPr>)表示“将此段落合并到下一段”——因此彻底删除一个段落就是这样做,再加上对每个运行包裹 <w:del>。<w:del/> 必须出现在 rPr 的其他子元素之前;它们的顺序由 schema 强制要求。
要生成接受所有跟踪更改的清洁副本:python scripts/accept_changes.py in.docx out.docx。
接受一个删除的段落标记应该将该段落与其下面的段落合并,因此所有运行都被删除的段落会消失。Word 能做到这一点;accept_changes.py 和 pandoc --track-changes=accept 并不总是能做到。两者都以相同的方式失败——它们会删除被删除的文本,但会留下清空的段落,当该段落是自动编号时,会显示为一个多余的空项目符号:
pandoc --track-changes=accept从不合并段落。accept_changes.py(LibreOffice)可以正确合并它们,除非被删除的段落后面跟着一个空白的间隔段落。
任一视图中的空项目符号都是该视图的产物,而不是文档的缺陷。请在 XML 中检查段落删除。
注释
注释需要六个交叉链接的文件。在同时编辑 document.xml 时使用目录模式(节省解压/重新压缩的周期),否则使用 .docx 直接模式:
# 针对已解压的目录(在同时放置标记时首选)
python scripts/comment.py unpacked/ "费用与开支上限过低"
python scripts/comment.py unpacked/ "同意" --parent 0
# 直接针对 .docx 文件
python scripts/comment.py contract.docx "此上限过低" -o annotated.docx
该脚本会写入 comments.xml、commentsExtended.xml、commentsIds.xml、commentsExtensible.xml、关系文件以及内容类型覆盖。注释 ID 会自动分配。然后脚本会打印出要添加到 word/document.xml 中的 <w:commentRangeStart>/<w:commentRangeEnd>/<w:commentReference> 代码片段,以便将注释锚定到特定文本——在放置这些标记之前,注释已存在但不可见。
依赖
docx(npm,已预安装——仅当 require('docx') 失败时才安装)· pandoc · LibreOffice (soffice) · pdftoppm (Poppler)