用途:以编程方式填写 DOCX 模板表单,要求填写后的文档与在原始模板中手工输入难以区分,适用于标准化表单、申请表、问卷与调查、基于模板的文档处理等场景。
主要能力:强调“保留优先于重建”。正确做法是加载模板,通过 XML API 在锚点处插入内容,从而保留原有元素、元数据与结构;可选择性就地填写表格单元格,按锚点(如以“Answer:”结尾的段落)插入内容,并支持多锚点插入(从后往前插入以保持索引)。
必要用法:先检查模板结构,运行 python scripts/inspect_template.py template.docx,查看表格、潜在锚点、页眉页脚与元素数量;再用 python-docx 就地修改单元格,例如 template.tables[0].rows[0].cells[1].text = "Jane Smith";插入内容时用 XML API 在锚点元素后插入段落,而非 add_paragraph() 追加到末尾;多锚点按逆序插入;最后 template.save('completed.docx')。
限制与反模式:不要用 pandoc --reference-doc(只复制样式定义,不保留结构,表格、徽标、页眉页脚会丢失);不要在末尾追加内容;不要重建表格。验证清单包括:表格数量不变、页眉页脚与徽标完好、样式一致、内容插入正确锚点、评分表保持空白(如应如此)。更多模式见 references/patterns.md。