许多业务文档具有固定的版式结构，但每次生成时填充的内容并不相同。例如，发票、合同、报告和证书通常保持相同的格式，而客户信息、日期、金额以及数据明细等内容需要根据实际情况动态更新。
相比于每次从零创建 Word 文档，开发者通常会先准备一个 Word 模板，然后在生成文档时填充实际数据。
本文将介绍如何使用 Python 动态填充 Word 模板，包括：
- 替换占位符；
- 填充邮件合并域；
- 更新书签内容；
- 根据动态数据创建 Word 表格。
安装所需的 Python 库
为了在 Python 中填充和操作 Word 文档，需要一个能够以编程方式处理 Word 文件的库。本文使用 Spire.Doc for Python，它支持创建、读取和修改 Word 文档，包括文本、表格、邮件合并域、书签以及其他文档元素的处理。
在开始之前，可以通过 PyPI 使用 pip 安装该库：
pip install spire.doc
准备 Word 模板
在编写代码之前，需要先创建一个 Word 模板，并标记需要动态填充的位置。根据文档结构的不同，可以使用占位符、邮件合并域或者书签来定义需要更新的内容。
占位符模板
占位符模板使用普通文本作为数据标记。例如：
客户名称：{{客户名称}}
公司名称：{{公司名称}}
发票编号：{{发票编号}}
发票日期：{{发票日期}}
总金额：{{总金额}}
在生成文档时，Python 程序会查找这些标记，并将其替换为实际数据。
邮件合并模板
邮件合并（Mail Merge）使用 Word 内置的合并域，而不是普通文本占位符。可以通过 Microsoft Word 插入合并域：
邮件 → 插入合并域
模板中会包含类似下面的域：
«客户名称»
«订单编号»
«订单金额»
应用程序会在生成文档时为这些域提供对应的数据。
书签模板
书签用于定义 Word 文档中的命名位置。
例如，可以在模板中创建以下书签：
合同编号
客户名称
生效日期
与占位符不同，书签不依赖文档中的可见文本，而是通过名称定位文档中的具体位置，并对其内容进行更新。
使用 Python 替换 Word 模板中的占位符
占位符替换的核心方式是：在 Word 文档中查找预先定义的标记，并将其替换为实际数据。
Spire.Doc 提供 Document.Replace() 方法用于完成这一操作。当模板中包含多个占位符时，可以使用 Python 字典保存占位符和值的对应关系，使代码更容易维护。
在实际项目中，这些数据通常来自数据库或者 API 返回结果。下面示例使用 Python 字典模拟发票数据。
from spire.doc import Document, FileFormat
# 加载 Word 模板
document = Document()
document.LoadFromFile("发票模板.docx")
# 业务数据
invoice_data = {
"客户名称": "张三",
"公司名称": "ABC科技有限公司",
"发票编号": "INV-2026-001",
"发票日期": "2026年9月24日",
"总金额": "2500元"
}
# 创建占位符替换映射
replacement_data = {
f"{{{{{key}}}}}": value
for key, value in invoice_data.items()
}
# 替换占位符
for placeholder, value in replacement_data.items():
document.Replace(placeholder, value, True, True)
# 保存生成的文档
document.SaveToFile("发票.docx", FileFormat.Docx)
document.Close()
需要注意的是，Word 模板中的占位符名称必须与 Python 中定义的占位符名称完全一致。如果模板中的占位符被修改，也需要同步调整代码中的数据映射。
使用 Python 填充 Word 模板中的邮件合并域
邮件合并使用 Word 模板中定义的域，而不是查找普通文本。
Spire.Doc 提供 MailMerge.Execute() 方法，可以根据程序提供的域名称和值填充这些域。
一个常见应用场景是：使用同一个模板，根据不同数据批量生成多个 Word 文档。例如，根据客户列表批量生成发票。
from spire.doc import Document, FileFormat
# Word 模板
template_file = "客户发票模板.docx"
# 数据源
customers = [
{
"客户名称": "李四",
"订单编号": "ORD-001",
"订单金额": "800元"
},
{
"客户名称": "王五",
"订单编号": "ORD-002",
"订单金额": "1200元"
}
]
# 批量生成文档
for customer in customers:
document = Document()
# 加载模板
document.LoadFromFile(template_file)
# 获取合并域的名称和值
field_names = list(customer.keys())
field_values = list(customer.values())
# 执行邮件合并
document.MailMerge.Execute(field_names, field_values)
# 保存文档
output_file = f"{customer['订单编号']}.docx"
document.SaveToFile(output_file, FileFormat.Docx)
document.Close()
传递给 Execute() 方法的域名称必须与 Word 模板中创建的邮件合并域保持一致。在批量生成场景中，数据可以来自数据库、Excel 文件、CSV 文件或者其他结构化数据源。
使用 Python 替换 Word 模板中的书签内容
书签用于定位 Word 文档中的指定位置。它不依赖文本匹配，而是通过书签名称直接定位内容区域并进行替换。
Spire.Doc 提供 BookmarksNavigator 类处理书签。通过 MoveToBookmark() 定位书签后，可以使用 ReplaceBookmarkContent() 替换书签内容。
下面示例展示如何替换合同模板中的多个书签。
from spire.doc import Document, FileFormat, BookmarksNavigator
# 加载 Word 模板
document = Document()
document.LoadFromFile("合同模板.docx")
# 合同数据
contract_data = {
"合同编号": "HT-2026-001",
"客户名称": "ABC科技有限公司",
"生效日期": "2026年9月24日"
}
# 创建书签导航器
bookmarkNavigator = BookmarksNavigator(document)
# 替换书签内容
for bookmark_name, value in contract_data.items():
bookmarkNavigator.MoveToBookmark(bookmark_name)
bookmarkNavigator.ReplaceBookmarkContent(value, False)
# 保存生成的文档
document.SaveToFile("合同.docx", FileFormat.Docx)
document.Close()
Python 中使用的书签名称必须与 Word 模板中创建的书签名称保持一致。
书签适用于已有固定格式的 Word 模板，例如合同、审批文件等场景，因为它不会改变原有文档结构。
使用 Python 根据动态数据创建 Word 表格
许多 Word 文档包含数据量不固定的表格。例如，销售报告中的产品数量可能每个月不同。如果提前在 Word 中创建固定数量的行，会限制文档生成的灵活性。
这种情况下，可以根据数据源动态创建表格结构。
下面示例根据销售数据生成一个报表表格。
from spire.doc import Document, FileFormat
# 创建 Word 文档
document = Document()
# 添加节
section = document.AddSection()
# 创建表格
table = section.AddTable(True)
# 报表数据
sales_data = [
["产品名称", "数量", "销售额"],
["笔记本电脑", "12", "24000元"],
["显示器", "8", "8000元"],
["键盘", "15", "1500元"]
]
# 创建表格结构
table.ResetCells(len(sales_data), len(sales_data[0]))
# 填充表格内容
for row_index, row_data in enumerate(sales_data):
for column_index, value in enumerate(row_data):
table.Rows[row_index].Cells[column_index].Paragraphs[0].Text = value
# 保存文档
document.SaveToFile("销售报告.docx", FileFormat.Docx)
document.Close()
动态创建表格可以让生成的文档根据数据量自动调整，而无需手动修改 Word 模板。
这种方式适用于发票、报告、报表等记录数量不固定的文档生成场景。
总结
使用 Python 动态填充 Word 模板，可以更方便地生成自定义文档，同时保持原有文档的版式和格式。
本文介绍了如何替换 Word 模板中的占位符、填充邮件合并域、更新书签内容，以及根据动态数据创建 Word 表格。通过这些方法，可以将不同来源的数据生成结构化 Word 文档，同时保持模板设计与文档生成逻辑相互分离。
