docx

DOCX 创建、编辑和分析

概述

用户可能会要求你创建、编辑或分析 .docx 文件的内容。.docx 文件本质上是一个 ZIP 存档，其中包含 XML 文件和其他资源，你可以读取或编辑这些内容。针对不同的任务，你可以使用不同的工具和工作流。

工作流决策树

阅读／分析内容

使用下文的“文本提取”或“原始 XML 访问”部分

创建新文档

使用“创建新的 Word 文档”工作流

编辑现有文档

• 你自己的文档 + 简单修改 使用“基本 OOXML 编辑”工作流

• 他人的文档 使用**“修订工作流”**（默认推荐）

• 法律、学术、商业或政府文档 使用**“修订工作流”**（必须）

阅读和分析内容

文本提取

如果你只需要读取文档的文本内容，应使用 pandoc 将文档转换为 Markdown。Pandoc 对保留文档结构提供了出色的支持，还能显示跟踪修订：

# Convert document to markdown with tracked changes
pandoc --track-changes=all path-to-file.docx -o output.md
# Options: --track-changes=accept/reject/all

原始 XML 访问

以下情况需要访问原始 XML：批注、复杂格式、文档结构、嵌入式媒体和元数据。对于这些功能，你需要解压文档并读取其原始 XML 内容。

解压文件

python ooxml/scripts/unpack.py <office_file> <output_directory>

关键文件结构

• word/document.xml - 文档主要内容
• word/comments.xml - document.xml 中引用的批注
• word/media/ - 嵌入的图像和媒体文件
• 跟踪修订使用 <w:ins>（插入）和 <w:del>（删除）标签

创建新的 Word 文档

从头创建新的 Word 文档时，请使用 docx-js，它允许你使用 JavaScript/TypeScript 创建 Word 文档。

工作流

1. 必须 - 阅读整个文件：从头到尾完整阅读 docx-js.md（约 500 行）。阅读此文件时，绝不要设置范围限制。 在继续创建文档之前，请阅读完整文件内容，以了解详细语法、关键格式规则和最佳实践。
2. 使用 Document、Paragraph、TextRun 组件创建 JavaScript/TypeScript 文件（可假设已安装所有依赖项；如果没有，请参阅下文的依赖项部分）
3. 使用 Packer.toBuffer() 导出为 .docx

编辑现有 Word 文档

编辑现有 Word 文档时，请使用 Document 库（用于操作 OOXML 的 Python 库）。该库会自动处理基础设施设置，并提供文档操作方法。对于复杂场景，你可以通过该库直接访问底层 DOM。

工作流

1. 必须 - 阅读整个文件：从头到尾完整阅读 ooxml.md（约 600 行）。阅读此文件时，绝不要设置范围限制。 请阅读完整文件内容，了解 Document 库 API 以及直接编辑文档文件的 XML 模式。
2. 解压文档：python ooxml/scripts/unpack.py <office_file> <output_directory>
3. 使用 Document 库创建并运行 Python 脚本（参见 ooxml.md 中的“Document 库”部分）
4. 打包最终文档：python ooxml/scripts/pack.py <input_directory> <office_file>

Document 库既提供常见操作的高级方法，也支持复杂场景下直接访问 DOM。

文档审阅的修订工作流

编辑他人的文档或任何正式／专业文档时，请使用此工作流。它会启用修订（红线标注），以便文档所有者审阅并接受／拒绝每项更改。

核心原则：将更改分成每批 3-10 项。只标记实际更改的文本——只改一个词时，绝不要替换整个句子。保留未更改文本原有的 run RSID。

必须遵循：开始前，请阅读 references/redlining-workflow.md 中的完整工作流，了解完整的分步流程、分批策略、附示例的最小化编辑原则，以及验证步骤。

步骤速览：转换为 Markdown，识别并分组更改，阅读 ooxml.md，解包文档，使用 Document 库分批实施更改，打包结果，并验证所有更改。

将文档转换为图像

要对 Word 文档进行视觉分析，请按以下两个步骤将其转换为图像：

1. 将 DOCX 转换为 PDF：

   soffice --headless --convert-to pdf document.docx
   

2. 将 PDF 页面转换为 JPEG 图像：

   pdftoppm -jpeg -r 150 document.pdf page
   

   这会创建 page-1.jpg、page-2.jpg 等文件。

选项：

• -r 150：将分辨率设为 150 DPI（可根据质量／文件大小的平衡进行调整）
• -jpeg：输出 JPEG 格式（如需 PNG，可使用 -png）
• -f N：要转换的首页（例如，-f 2 表示从第 2 页开始）
• -l N：要转换的末页（例如，-l 5 表示到第 5 页结束）
• page：输出文件的前缀

特定范围示例：

pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # Converts only pages 2-5

代码风格指南

重要：为 DOCX 操作生成代码时：

• 编写简洁的代码
• 避免冗长的变量名和冗余操作
• 避免不必要的打印语句

依赖项

所需依赖项（如未安装，请安装）。先列出 Linux 命令，macOS（Homebrew）命令放在括号中：

• pandoc：sudo apt-get install pandoc（macOS：brew install pandoc）——用于提取文本
• docx：npm install -g docx——用于创建新文档
• LibreOffice：sudo apt-get install libreoffice（macOS：brew install --cask libreoffice）——用于转换 PDF
• Poppler：sudo apt-get install poppler-utils（macOS：brew install poppler）——用于使用 pdftoppm 将 PDF 转换为图像
• defusedxml：pip install defusedxml——用于安全地解析 XML