输出要求

所有 Word 文档

零错误交付

• 每个文档模型必须以零错误交付（无损坏的 XML、无无效引用）

保留现有模板（更新模板时）

• 修改文件时研究和精确匹配现有格式、样式和约定
• 切勿将标准化格式强加于已有固定模式的文件
• 现有模板约定始终优先于本指南

文档创建与编辑

重要要求

LibreOffice 用于格式转换：您可以假设 LibreOffice 已安装，用于将文档转换为其他格式（如 docx 转换为 pdf）。

读取和分析数据

使用 python-docx 读取

from docx import Document

# 读取文档
doc = Document('document.docx')

# 读取段落
for para in doc.paragraphs:
    print(para.text)

# 读取表格
for table in doc.tables:
    for row in table.rows:
        for cell in row.cells:
            print(cell.text)

文档工作流程

创建新文档

from docx import Document
from docx.shared import Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH

doc = Document()

# 添加标题
doc.add_heading('文档标题', 0)

# 添加段落
para = doc.add_paragraph()
para.add_run('这是粗体').bold = True
para.add_run(' 和普通文本')

# 添加格式化的段落
para = doc.add_paragraph()
run = para.add_run('带颜色的大号文本')
run.font.size = Pt(24)
run.font.color.rgb = RGBColor(0, 0, 255)

# 添加项目符号列表
doc.add_heading('项目符号列表', level=1)
doc.add_paragraph('第一项', style='List Bullet')
doc.add_paragraph('第二项', style='List Bullet')

# 添加编号列表
doc.add_heading('编号列表', level=1)
doc.add_paragraph('第一项', style='List Number')
doc.add_paragraph('第二项', style='List Number')

# 添加表格
doc.add_heading('表格', level=1)
table = doc.add_table(rows=3, cols=3)
table.style = 'Light Grid Accent 1'
# 表头
hdr_cells = table.rows[0].cells
hdr_cells[0].text = '名称'
hdr_cells[1].text = '数量'
hdr_cells[2].text = '价格'
# 数据行
row_cells = table.rows[1].cells
row_cells[0].text = '产品 A'
row_cells[1].text = '10'
row_cells[2].text = '$100'

doc.save('output.docx')

编辑现有文档

from docx import Document

# 加载现有文档
doc = Document('existing.docx')

# 查找和替换文本
for para in doc.paragraphs:
    if '要替换的文本' in para.text:
        para.text = para.text.replace('要替换的文本', '新文本')

# 修改表格
for table in doc.tables:
    for row in table.rows:
        for cell in row.cells:
            if '旧文本' in cell.text:
                cell.text = cell.text.replace('旧文本', '新文本')

doc.save('modified.docx')

使用文档对象模型添加批注和修订

from docx import Document

doc = Document('document.docx')

# 找到要添加批注的段落
target_para = doc.paragraphs[0]

# 在段落开头添加批注
comment = target_para.add_comment(
    text='这是一个批注',
    author='示例作者',
    initials='EA'
)

处理 OOXML 结构

有关 OOXML 操作的完整文档，请参阅 ooxml.md。

表单处理

表单域

Word 文档可以包含可填写的表单域，包括：

• 内容控件：现代、结构化的表单控件（文本、日期、下拉列表等）
• 旧版表单域：传统书签样式的字段（FORMCHECKBOX、formtext、formdropdown）

有关表单处理的完整文档，请参阅 forms.md。

内容控件

内容控件是嵌入在文档中的结构化元素，用于创建模板化文档。

from docx.oxml.ns import qn
from lxml import etree

def add_content_control(doc, tag_name, placeholder_text):
    """在文档末尾添加纯文本内容控件"""
    para = doc.add_paragraph()
    sdt = para._p  # 获取段落元素的 XML

    # 创建内容控件元素
    content_control = """
    <w:sdt xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
        <w:sdtPr>
            <w:tag w:val="{tag}"/>
            <w:id w:val="123456"/>
            <w:placeholder>
                <w:docPart w:val="DefaultPlaceholder_1081868574"/>
            </w:placeholder>
            <w:showingPlcHdr/>
            <w:text/>
        </w:sdtPr>
        <w:sdtContent>
            <w:r>
                <w:t>{placeholder}</w:t>
            </w:r>
        </w:sdtContent>
    </w:sdt>
    """.format(tag=tag_name, placeholder=placeholder_text)

    sdt_elm = etree.fromstring(content_control)
    para._p.append(sdt_elm)
    return para

处理表单数据

# 读取表单数据
def get_form_field_values(doc):
    """提取文档中的所有表单域值"""
    values = {}

    for para in doc.paragraphs:
        # 检查段落是否包含内容控件
        for run in para.runs:
            if 'w:sdt' in str(run._r):
                # 内容控件逻辑
                pass

    return values

OOXML 操作

有关 Word 文档的 OOXML 操作的完整文档，请参阅以下资源：

• ooxml.md：OOXML 结构的详细指南
• ooxml/scripts/unpack.py：解包 DOCX 文件
• ooxml/scripts/pack.py：打包 DOCX 文件
• ooxml/scripts/validate.py：验证 DOCX 文件

解包 DOCX 文件

DOCX 文件本质上是 ZIP 归档。解包后可访问内部 XML 文件：

python docx/ooxml/scripts/unpack.py document.docx output_dir/

打包 DOCX 文件

将解包的目录重新打包为 DOCX：

python docx/ooxml/scripts/pack.py output_dir/ document.docx

验证 DOCX 文件

验证 DOCX 文件是否符合 Office 规范：

python docx/ooxml/scripts/validate.py document.docx

最佳实践

库选择

• python-docx：文档创建、编辑和格式化的最佳选择
• 直接 OOXML 操作：高级操作，如批注、修订、邮件合并等

使用 python-docx

• 文档元素按添加顺序排列
• 使用样式而非手动设置格式以保持一致性
• 保存后检查文档是否损坏

使用 python-docx 注意事项

• add_heading()

  会添加段落，因此不要在同一位置添加空段落
• 表格单元格可以包含多个段落
• 图像需要使用

  add_picture()

  添加

直接 OOXML 操作

• 始终使用命名空间前缀（w:, r:, mc: 等）
• 在修改 XML 之前备份原始文件
• 修改后验证文档是否有效

邮件合并

from docx import Document

doc = Document('template.docx')

# 替换占位符
for para in doc.paragraphs:
    for run in para.runs:
        if '{{name}}' in run.text:
            run.text = run.text.replace('{{name}}', '张三')