Python Spire.Doc动态填充Word模板与邮件合并

脚本专家

许多业务文档有固定版式，但每次生成时填充的数据不同，例如发票、合同、报告和证书。相比每次从零创建 Word 文档，更常见的做法是准备 Word 模板，再用 Python 在生成阶段填充实际数据。本文围绕 Spire.Doc for Python，说明占位符替换、邮件合并域填充、书签内容更新，以及根据动态数据创建 Word 表格的代码实现。

一、安装 Spire.Doc for Python
在 Python 中填充和操作 Word 文档，需要一个能以编程方式处理 Word 文件的库。本文使用 Spire.Doc for Python，它支持创建、读取和修改 Word 文档，包括文本、表格、邮件合并域、书签等文档元素。通过 PyPI 使用 pip 安装：

2. pip install spire.doc

复制代码

二、准备 Word 模板
编写代码前，需要先创建 Word 模板，并标记动态填充位置。根据文档结构，可以用占位符、邮件合并域或书签定义更新内容。
占位符模板使用普通文本作为数据标记，例如：
客户名称：{{客户名称}}
公司名称：{{公司名称}}
发票编号：{{发票编号}}
发票日期：{{发票日期}}
总金额：{{总金额}}
生成文档时，程序查找这些标记并替换为实际数据。
邮件合并模板使用 Word 内置合并域，而不是普通文本占位符。可以通过 Microsoft Word 的“邮件 → 插入合并域”插入，模板中会出现类似下面的域：
«客户名称»
«订单编号»
«订单金额»
生成文档时，应用程序为这些域提供对应数据。
书签用于定义 Word 文档中的命名位置，例如合同编号、客户名称、生效日期。与占位符不同，书签不依赖文档中的可见文本，而是通过名称定位具体位置并更新内容。

三、替换 Word 模板中的占位符
占位符替换的核心是：在文档中查找预先定义的标记并替换为实际数据。Spire.Doc 提供 Document.Replace() 方法完成该操作。模板中有多个占位符时，可以用 Python 字典保存占位符与值的对应关系，便于维护。实际项目中，这些数据通常来自数据库或 API 返回结果；下面用字典模拟发票数据。

2. from spire.doc import Document, FileFormat
3. # 加载 Word 模板
4. document = Document()
5. document.LoadFromFile("发票模板.docx")
6. # 业务数据
7. invoice_data = {
8.     "客户名称": "张三",
9.     "公司名称": "ABC科技有限公司",
10.     "发票编号": "INV-2026-001",
11.     "发票日期": "2026年9月24日",
12.     "总金额": "2500元"
13. }
14. # 创建占位符替换映射
15. replacement_data = {
16.     f"{{{{{key}}}}}": value
17.     for key, value in invoice_data.items()
18. }
19. # 替换占位符
20. for placeholder, value in replacement_data.items():
21.     document.Replace(placeholder, value, True, True)
22. # 保存生成的文档
23. document.SaveToFile("发票.docx", FileFormat.Docx)
24. document.Close()

复制代码

注意：Word 模板中的占位符名称必须与 Python 中定义的占位符名称完全一致。如果模板占位符被修改，也需要同步调整代码中的数据映射。

四、填充 Word 模板中的邮件合并域
邮件合并使用 Word 模板中定义的域，不是查找普通文本。Spire.Doc 提供 MailMerge.Execute() 方法，可以根据程序提供的域名称和值填充这些域。常见场景是使用同一个模板，根据不同数据批量生成多个 Word 文档，例如按客户列表批量生成发票。

2. from spire.doc import Document, FileFormat
3. # Word 模板
4. template_file = "客户发票模板.docx"
5. # 数据源
6. customers = [
7.     {
8.         "客户名称": "李四",
9.         "订单编号": "ORD-001",
10.         "订单金额": "800元"
11.     },
12.     {
13.         "客户名称": "王五",
14.         "订单编号": "ORD-002",
15.         "订单金额": "1200元"
16.     }
17. ]
18. # 批量生成文档
19. for customer in customers:
20.     document = Document()
21.     # 加载模板
22.     document.LoadFromFile(template_file)
23.     # 获取合并域的名称和值
24.     field_names = list(customer.keys())
25.     field_values = list(customer.values())
26.     # 执行邮件合并
27.     document.MailMerge.Execute(field_names, field_values)
28.     # 保存文档
29.     output_file = f"{customer['订单编号']}.docx"
30.     document.SaveToFile(output_file, FileFormat.Docx)
31.     document.Close()

复制代码

传递给 Execute() 方法的域名称必须与 Word 模板中创建的邮件合并域保持一致。在批量生成场景中，数据可以来自数据库、Excel 文件、CSV 文件或其他结构化数据源。

五、替换 Word 模板中的书签内容
书签用于定位 Word 文档中的指定位置。它不依赖文本匹配，而是通过书签名称直接定位内容区域并替换。Spire.Doc 提供 BookmarksNavigator 类处理书签：通过 MoveToBookmark() 定位书签后，可以用 ReplaceBookmarkContent() 替换书签内容。下面示例替换合同模板中的多个书签。

2. from spire.doc import Document, FileFormat, BookmarksNavigator
3. # 加载 Word 模板
4. document = Document()
5. document.LoadFromFile("合同模板.docx")
6. # 合同数据
7. contract_data = {
8.     "合同编号": "HT-2026-001",
9.     "客户名称": "ABC科技有限公司",
10.     "生效日期": "2026年9月24日"
11. }
12. # 创建书签导航器
13. bookmarkNavigator = BookmarksNavigator(document)
14. # 替换书签内容
15. for bookmark_name, value in contract_data.items():
16.     bookmarkNavigator.MoveToBookmark(bookmark_name)
17.     bookmarkNavigator.ReplaceBookmarkContent(value, False)
18. # 保存生成的文档
19. document.SaveToFile("合同.docx", FileFormat.Docx)
20. document.Close()

复制代码

Python 中使用的书签名称必须与 Word 模板中创建的书签名称保持一致。书签适用于已有固定格式的 Word 模板，例如合同、审批文件等场景，因为它不会改变原有文档结构。

六、根据动态数据创建 Word 表格
许多 Word 文档包含数据量不固定的表格。例如销售报告中的产品数量可能每个月不同。如果提前在 Word 中创建固定数量的行，会限制文档生成的灵活性。这种情况下，可以根据数据源动态创建表格结构。下面示例根据销售数据生成报表表格。

2. from spire.doc import Document, FileFormat
3. # 创建 Word 文档
4. document = Document()
5. # 添加节
6. section = document.AddSection()
7. # 创建表格
8. table = section.AddTable(True)
9. # 报表数据
10. sales_data = [
11.     ["产品名称", "数量", "销售额"],
12.     ["笔记本电脑", "12", "24000元"],
13.     ["显示器", "8", "8000元"],
14.     ["键盘", "15", "1500元"]
15. ]
16. # 创建表格结构
17. table.ResetCells(len(sales_data), len(sales_data[0]))
18. # 填充表格内容
19. for row_index, row_data in enumerate(sales_data):
20.     for column_index, value in enumerate(row_data):
21.         table.Rows[row_index].Cells[column_index].Paragraphs[0].Text = value
22. # 保存文档
23. document.SaveToFile("销售报告.docx", FileFormat.Docx)
24. document.Close()

复制代码

动态创建表格可以让生成的文档根据数据量自动调整，无需手动修改 Word 模板。这种方式适用于发票、报告、报表等记录数量不固定的文档生成场景。

总结
使用 Python 动态填充 Word 模板，可以更方便地生成自定义文档，同时保持原有文档版式和格式。本文覆盖了替换占位符、填充邮件合并域、更新书签内容，以及根据动态数据创建 Word 表格。通过这些方法，可以把不同来源的数据生成结构化 Word 文档，并让模板设计与文档生成逻辑相互分离。