docxtpl 是一个功能强大的 Python 库，可以方便地在 Word 文档中生成和填充动态数据。它基于 docx 库，通过模板的方法让用户能够轻松地创建带有占位符的文档，然后用实际数据进行填充，适用于生成合同、报告、发票等多种格式的文档。
安装
在开始之前，需要先安装 docxtpl 库。你可以使用 pip 来进行安装：
pip install docxtpl
基本使用方法
首先，我们需要创建一个 Word 文档模板。在模板文件中，可以使用 Jinja2 语法来定义占位符，比如 {{ name }} 或者 {{ items[0] }} 等。下面是一个简单的模板示例，假设我们将其命名为 template.docx：
尊敬的 {{ name }}：
感谢您在我们公司购买的以下商品：
{% for item in items %}
- {{ item.name }}: {{ item.price }}
{% endfor %}
祝好！
在这个模板中，我们定义了一个接收客户名字的占位符 {{ name }}，以及一个循环来列出多个商品。
接下来，我们将编写 Python 代码来加载模板并填充数据。
示例代码
from docxtpl import DocxTemplate, InlineImage
from docx import Document
from docx.shared import Inches
# 加载模板
template_path = 'template.docx'
doc = DocxTemplate(template_path)
# 定义数据
context = {
'name': '张三',
'items': [
{'name': '商品A', 'price': '100元'},
{'name': '商品B', 'price': '200元'},
{'name': '商品C', 'price': '300元'},
],
}
# 渲染文档
doc.render(context)
# 保存生成的文档
output_path = 'generated_doc.docx'
doc.save(output_path)
print(f"文档已生成：{output_path}")
代码解析
- 我们首先导入了
DocxTemplate类，它负责加载和生成 Word 文档。 - 加载我们的
template.docx模板文件。 - 定义了一个字典
context，其中包含我们要填充到模板中的数据。 - 使用
doc.render(context)方法渲染文档，其中context是需要填充到模板的上下文。 - 最后，调用
doc.save(output_path)方法保存生成的文档。
进阶用法
docxtpl 还支持许多高级特性，比如：
- 图像：可以将图片插入到文档中。
- 条件语句：可以在模板中进行条件判断。
- 循环：可以通过循环遍历列表，来生成多个项。
例如，如果我们要在文档中添加一张图片，可以这样做：
首先，将图片文件放在与 Python 脚本可以访问的路径下，然后在 context 中增加一个键：
from docxtpl import DocxTemplate, InlineImage
from docx.shared import Inches
# 加载模板
template_path = 'template.docx'
doc = DocxTemplate(template_path)
# 定义数据，其中包含图像
context = {
'name': '张三',
'items': [{'name': '商品A', 'price': '100元'}],
'picture': InlineImage(doc, 'path/to/image.png', width=Inches(1)) # 调整图片大小
}
# 渲染和保存文档
doc.render(context)
doc.save('generated_doc_with_image.docx')
在模板中，使用 {{ picture }} 来显示图片。
总结
docxtpl 为生成和填充 Word 文档提供了极大的便利，通过简单的模板和数据渲染，可以快速生成定制化的文档，这是它的最大优势。无论是用于日常工作还是项目开发，掌握 docxtpl 都能极大提高工作效率。
