# Office Open XML 技术参考 **重要：开始之前请阅读完整文档。** 本文档涵盖： - [技术指南](#技术指南) - 架构合规规则和验证要求 - [文档内容模式](#文档内容模式) - 标题、列表、表格、格式等的 XML 模式 - [Document 库 (Python)](#document-库-python) - 推荐的 OOXML 操作方法，带自动基础设施设置 - [修订追踪（红线批注）](#修订追踪红线批注) - 实现修订追踪的 XML 模式 ## 技术指南 ### 架构合规 - **`` 中的元素顺序**：``、``、``、``、`` - **空白字符**：为包含前导/尾随空格的 `` 元素添加 `xml:space='preserve'` - **Unicode**：在 ASCII 内容中转义字符：`"` 变为 `“` - **字符编码参考**：弯引号 `""` 变为 `“”`，撇号 `'` 变为 `’`，破折号 `—` 变为 `—` - **修订追踪**：在 `` 元素外部使用带有 `w:author="Claude"` 的 `` 和 `` 标签 - **关键**：`` 以 `` 结束，`` 以 `` 结束 - 永远不要混淆 - **RSID 必须是 8 位十六进制**：使用如 `00AB1234` 的值（仅限 0-9、A-F 字符） - **trackRevisions 位置**：在 settings.xml 中 `` 之后添加 `` - **图片**：添加到 `word/media/`，在 `document.xml` 中引用，设置尺寸以防止溢出 ## 文档内容模式 ### 基本结构 ```xml 文本内容 ``` ### 标题和样式 ```xml 文档标题 章节标题 ``` ### 文本格式 ```xml 粗体 斜体 下划线 高亮 ``` ### 列表 ```xml 第一项 新列表第 1 项 项目符号项 ``` ### 表格 ```xml 单元格 1 单元格 2 ``` ### 布局 ```xml 新章节标题 居中文本 等宽文本 这段文本是 Courier New 而这段文本使用默认字体 ``` ## 文件更新 添加内容时，更新以下文件： **`word/_rels/document.xml.rels`：** ```xml ``` **`[Content_Types].xml`：** ```xml ``` ### 图片 **关键**：计算尺寸以防止页面溢出并保持纵横比。 ```xml ``` ### 链接（超链接） **重要**：所有超链接（内部和外部）都需要在 styles.xml 中定义 Hyperlink 样式。没有此样式，链接将看起来像普通文本而不是蓝色下划线可点击链接。 **外部链接：** ```xml 链接文本 ``` **内部链接：** ```xml 链接文本 目标内容 ``` **Hyperlink 样式（styles.xml 中必需）：** ```xml ``` ## Document 库 (Python) 使用 `scripts/document.py` 中的 Document 类处理所有修订追踪和批注。它自动处理基础设施设置（people.xml、RSID、settings.xml、批注文件、关系、内容类型）。仅对库不支持的复杂场景使用直接 XML 操作。 **处理 Unicode 和实体：** - **搜索**：实体表示法和 Unicode 字符都可用 - `contains="“Company"` 和 `contains="\u201cCompany"` 查找相同的文本 - **替换**：使用实体（`“`）或 Unicode（`\u201c`）都可以 - 两者都会根据文件编码（ascii → 实体，utf-8 → Unicode）适当转换 ### 初始化 **找到 docx 技能根目录**（包含 `scripts/` 和 `ooxml/` 的目录）： ```bash # 搜索 document.py 以定位技能根目录 # 注意：/mnt/skills 仅作示例；请检查您的上下文以获取实际位置 find /mnt/skills -name "document.py" -path "*/docx/scripts/*" 2>/dev/null | head -1 # 示例输出：/mnt/skills/docx/scripts/document.py # 技能根目录是：/mnt/skills/docx ``` **运行脚本时设置 PYTHONPATH** 为 docx 技能根目录： ```bash PYTHONPATH=/mnt/skills/docx python your_script.py ``` **在脚本中**，从技能根目录导入： ```python from scripts.document import Document, DocxXMLEditor # 基本初始化（自动创建临时副本并设置基础设施） doc = Document('unpacked') # 自定义作者和首字母缩写 doc = Document('unpacked', author="John Doe", initials="JD") # 启用修订追踪模式 doc = Document('unpacked', track_revisions=True) # 指定自定义 RSID（如果未提供则自动生成） doc = Document('unpacked', rsid="07DC5ECB") ``` ### 创建修订追踪 **关键**：只标记实际更改的文本。将所有未更改的文本保留在 ``/`` 标签外部。标记未更改的文本会使编辑不专业且更难审阅。 **属性处理**：Document 类会自动向新元素注入属性（w:id、w:date、w:rsidR、w:rsidDel、w16du:dateUtc、xml:space）。保留原始文档中未更改的文本时，复制带有现有属性的原始 `` 元素以保持文档完整性。 **方法选择指南**： - **向普通文本添加您自己的更改**：使用带有 ``/`` 标签的 `replace_node()`，或使用 `suggest_deletion()` 删除整个 `` 或 `` 元素 - **部分修改其他作者的修订追踪**：使用 `replace_node()` 将您的更改嵌套在他们的 ``/`` 中 - **完全拒绝其他作者的插入**：对 `` 元素使用 `revert_insertion()`（而不是 `suggest_deletion()`） - **完全拒绝其他作者的删除**：对 `` 元素使用 `revert_deletion()` 以使用修订追踪恢复删除的内容 ```python # 最小编辑 - 更改一个词："The report is monthly" → "The report is quarterly" # 原始：The report is monthly node = doc["word/document.xml"].get_node(tag="w:r", contains="The report is monthly") rpr = tags[0].toxml() if (tags := node.getElementsByTagName("w:rPr")) else "" replacement = f'{rpr}The report is {rpr}monthly{rpr}quarterly' doc["word/document.xml"].replace_node(node, replacement) # 最小编辑 - 更改数字："within 30 days" → "within 45 days" # 原始：within 30 days node = doc["word/document.xml"].get_node(tag="w:r", contains="within 30 days") rpr = tags[0].toxml() if (tags := node.getElementsByTagName("w:rPr")) else "" replacement = f'{rpr}within {rpr}30{rpr}45{rpr} days' doc["word/document.xml"].replace_node(node, replacement) # 完全替换 - 即使替换所有文本也要保留格式 node = doc["word/document.xml"].get_node(tag="w:r", contains="apple") rpr = tags[0].toxml() if (tags := node.getElementsByTagName("w:rPr")) else "" replacement = f'{rpr}apple{rpr}banana orange' doc["word/document.xml"].replace_node(node, replacement) # 插入新内容（无需属性 - 自动注入） node = doc["word/document.xml"].get_node(tag="w:r", contains="existing text") doc["word/document.xml"].insert_after(node, 'new text') # 部分删除其他作者的插入 # 原始：quarterly financial report # 目标：只删除"financial"使其变为"quarterly report" node = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "5"}) # 重要：保留外层 上的 w:author="Jane Smith" 以维护作者身份 replacement = ''' quarterly financial report ''' doc["word/document.xml"].replace_node(node, replacement) # 更改其他作者插入的一部分 # 原始：in silence, safe and sound # 目标：将"safe and sound"改为"soft and unbound" node = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "8"}) replacement = f''' in silence, soft and unbound safe and sound ''' doc["word/document.xml"].replace_node(node, replacement) # 删除整个 run（仅在删除所有内容时使用；部分删除请使用 replace_node） node = doc["word/document.xml"].get_node(tag="w:r", contains="text to delete") doc["word/document.xml"].suggest_deletion(node) # 删除整个段落（就地处理，同时处理普通段落和编号列表段落） para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph to delete") doc["word/document.xml"].suggest_deletion(para) # 添加新编号列表项 target_para = doc["word/document.xml"].get_node(tag="w:p", contains="existing list item") pPr = tags[0].toxml() if (tags := target_para.getElementsByTagName("w:pPr")) else "" new_item = f'{pPr}New item' tracked_para = DocxXMLEditor.suggest_paragraph(new_item) doc["word/document.xml"].insert_after(target_para, tracked_para) # 可选：在内容前添加间距段落以获得更好的视觉分隔 # spacing = DocxXMLEditor.suggest_paragraph('') # doc["word/document.xml"].insert_after(target_para, spacing + tracked_para) ``` ### 添加批注 ```python # 添加跨越两个现有修订追踪的批注 # 注意：w:id 是自动生成的。仅当您从 XML 检查中知道 w:id 时才按 w:id 搜索 start_node = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "1"}) end_node = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "2"}) doc.add_comment(start=start_node, end=end_node, text="此更改的解释") # 在段落上添加批注 para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph text") doc.add_comment(start=para, end=para, text="关于此段落的批注") # 在新创建的修订追踪上添加批注 # 首先创建修订追踪 node = doc["word/document.xml"].get_node(tag="w:r", contains="old") new_nodes = doc["word/document.xml"].replace_node( node, 'oldnew' ) # 然后在新创建的元素上添加批注 # new_nodes[0] 是 ，new_nodes[1] 是 doc.add_comment(start=new_nodes[0], end=new_nodes[1], text="根据要求将 old 改为 new") # 回复现有批注 doc.reply_to_comment(parent_comment_id=0, text="我同意这个更改") ``` ### 拒绝修订追踪 **重要**：使用 `revert_insertion()` 拒绝插入，使用 `revert_deletion()` 使用修订追踪恢复删除。仅对普通未标记内容使用 `suggest_deletion()`。 ```python # 拒绝插入（将其包装在删除中） # 当其他作者插入了您想删除的文本时使用此方法 ins = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "5"}) nodes = doc["word/document.xml"].revert_insertion(ins) # 返回 [ins] # 拒绝删除（创建插入以恢复删除的内容） # 当其他作者删除了您想恢复的文本时使用此方法 del_elem = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "3"}) nodes = doc["word/document.xml"].revert_deletion(del_elem) # 返回 [del_elem, new_ins] # 拒绝段落中的所有插入 para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph text") nodes = doc["word/document.xml"].revert_insertion(para) # 返回 [para] # 拒绝段落中的所有删除 para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph text") nodes = doc["word/document.xml"].revert_deletion(para) # 返回 [para] ``` ### 插入图片 **关键**：Document 类使用位于 `doc.unpacked_path` 的临时副本。始终将图片复制到此临时目录，而不是原始解包文件夹。 ```python from PIL import Image import shutil, os # 首先初始化文档 doc = Document('unpacked') # 复制图片并计算保持纵横比的全宽尺寸 media_dir = os.path.join(doc.unpacked_path, 'word/media') os.makedirs(media_dir, exist_ok=True) shutil.copy('image.png', os.path.join(media_dir, 'image1.png')) img = Image.open(os.path.join(media_dir, 'image1.png')) width_emus = int(6.5 * 914400) # 6.5 英寸可用宽度，914400 EMU/英寸 height_emus = int(width_emus * img.size[1] / img.size[0]) # 添加关系和内容类型 rels_editor = doc['word/_rels/document.xml.rels'] next_rid = rels_editor.get_next_rid() rels_editor.append_to(rels_editor.dom.documentElement, f'') doc['[Content_Types].xml'].append_to(doc['[Content_Types].xml'].dom.documentElement, '') # 插入图片 node = doc["word/document.xml"].get_node(tag="w:p", line_number=100) doc["word/document.xml"].insert_after(node, f''' ''') ``` ### 获取节点 ```python # 按文本内容 node = doc["word/document.xml"].get_node(tag="w:p", contains="specific text") # 按行号范围 para = doc["word/document.xml"].get_node(tag="w:p", line_number=range(100, 150)) # 按属性 node = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "1"}) # 按精确行号（必须是标签打开的行号） para = doc["word/document.xml"].get_node(tag="w:p", line_number=42) # 组合过滤器 node = doc["word/document.xml"].get_node(tag="w:r", line_number=range(40, 60), contains="text") # 当文本多次出现时消歧 - 添加 line_number 范围 node = doc["word/document.xml"].get_node(tag="w:r", contains="Section", line_number=range(2400, 2500)) ``` ### 保存 ```python # 自动验证保存（复制回原始目录） doc.save() # 默认验证，验证失败时抛出错误 # 保存到不同位置 doc.save('modified-unpacked') # 跳过验证（仅用于调试 - 生产中需要这个表明存在 XML 问题） doc.save(validate=False) ``` ### 直接 DOM 操作 对于库未涵盖的复杂场景： ```python # 访问任何 XML 文件 editor = doc["word/document.xml"] editor = doc["word/comments.xml"] # 直接 DOM 访问（defusedxml.minidom.Document） node = doc["word/document.xml"].get_node(tag="w:p", line_number=5) parent = node.parentNode parent.removeChild(node) parent.appendChild(node) # 移动到末尾 # 通用文档操作（不带修订追踪） old_node = doc["word/document.xml"].get_node(tag="w:p", contains="original text") doc["word/document.xml"].replace_node(old_node, "replacement text") # 多次插入 - 使用返回值保持顺序 node = doc["word/document.xml"].get_node(tag="w:r", line_number=100) nodes = doc["word/document.xml"].insert_after(node, "A") nodes = doc["word/document.xml"].insert_after(nodes[-1], "B") nodes = doc["word/document.xml"].insert_after(nodes[-1], "C") # 结果：original_node, A, B, C ``` ## 修订追踪（红线批注） **对所有修订追踪使用上面的 Document 类。** 以下模式仅供构建替换 XML 字符串时参考。 ### 验证规则 验证器检查撤销 Claude 更改后文档文本是否与原始文档匹配。这意味着： - **永远不要修改其他作者 `` 或 `` 标签内的文本** - **始终使用嵌套删除**来删除其他作者的插入 - **每个编辑都必须正确追踪**使用 `` 或 `` 标签 ### 修订追踪模式 **关键规则**： 1. 永远不要修改其他作者修订追踪内的内容。始终使用嵌套删除。 2. **XML 结构**：始终将 `` 和 `` 放在包含完整 `` 元素的段落级别。永远不要嵌套在 `` 元素内部 - 这会创建破坏文档处理的无效 XML。 **文本插入：** ```xml 插入的文本 ``` **文本删除：** ```xml 删除的文本 ``` **删除其他作者的插入（必须使用嵌套结构）：** ```xml monthly weekly ``` **恢复其他作者的删除：** ```xml within 30 days within 30 days ```