docxtpl 库介绍
概述
docxtpl 是一个基于 Python 的库，用于在 Word 文档（.docx 格式）中执行模板渲染。它结合了 python-docx 的强大功能和 Jinja2 模板引擎的灵活性，使得动态生成 Word 文档变得简单高效。
主要特性
1. 基于 Jinja2 模板语法
支持变量替换、循环、条件判断等
使用熟悉的
{{ variable }}、{% for %}、{% if %}语法
2. 丰富的标签支持
# 变量替换
{{ name }}
# 循环
{% for item in items %}
{{ item.name }}
{% endfor %}
# 条件判断
{% if condition %}
{{ value }}
{% endif %}3. 灵活的上下文管理
支持字典、对象等多种数据源
可以嵌套复杂的数据结构
4. 保持文档格式
保留原文档的所有格式、样式和布局
支持图片、表格等复杂元素的插入
安装方法
pip install docxtpl
实际应用场景
1. 报告生成
周报、月报
项目进度报告
数据分析报告
2. 合同文档
自动填充客户信息
条款选择和处理
3. 证书制作
批量生成证书
自动填充获奖信息
4. 邮件合并
个性化信函
批量邀请函
优点
简单易用：基于熟悉的 Jinja2 语法
功能强大：支持复杂的文档结构
格式保持：完美保留原文档样式
灵活扩展：支持自定义过滤器和标签
性能优秀：处理大型文档效率高
注意事项
模板设计：在 Word 中设计模板时要注意格式规范
标签位置：确保标签在正确的段落和位置
特殊字符：注意处理特殊字符和转义
图片路径：确保图片路径正确且可访问
总结
docxtpl 是一个功能强大且易于使用的 Word 文档模板处理库，特别适合需要批量生成标准化 Word 文档的场景。通过结合 Jinja2 模板引擎的灵活性和 Word 文档的丰富格式支持，它大大简化了动态文档生成的复杂度。
docxtpl 库基本用法代码示例
from docxtpl import DocxTemplate, InlineImage, RichText
from docxtpl import DocxTemplate
# ==================== 1. 简单变量替换 ====================
def simple_variable_demo():
"""基础变量替换示例"""
doc = DocxTemplate("simple_template.docx")
context = {
'name': '张三',
'age': 28,
'company': '科技有限公司',
'position': '高级工程师',
'date': '2024-01-15'
}
doc.render(context)
doc.save("output_simple.docx")
print("简单变量替换完成!")
# ==================== 2. 循环和条件判断 ====================
def loop_and_condition_demo():
"""循环和条件判断示例"""
doc = DocxTemplate("loop_template.docx")
context = {
'projects': [
{
'name': '电商平台开发',
'leader': '李四',
'status': 'completed',
'members': ['张三', '王五', '赵六']
},
{
'name': '移动App设计',
'leader': '王五',
'status': 'in_progress',
'members': ['陈七', '孙八']
},
{
'name': '数据分析系统',
'leader': '赵六',
'status': 'planning',
'members': ['张三', '李四']
}
],
'department': '技术部'
}
doc.render(context)
doc.save("output_loop.docx")
print("循环和条件判断完成!")
# ==================== 3. 表格处理 ====================
def table_demo():
"""表格数据处理示例"""
doc = DocxTemplate("table_template.docx")
context = {
'users': [
{'name': '张三', 'email': 'zhangsan@email.com', 'phone': '13800138001', 'department': '技术部'},
{'name': '李四', 'email': 'lisi@email.com', 'phone': '13800138002', 'department': '市场部'},
{'name': '王五', 'email': 'wangwu@email.com', 'phone': '13800138003', 'department': '人事部'},
{'name': '赵六', 'email': 'zhaoliu@email.com', 'phone': '13800138004', 'department': '财务部'}
],
'total_count': 4
}
doc.render(context)
doc.save("output_table.docx")
print("表格处理完成!")
# ==================== 4. 富文本和图片 ====================
def rich_text_and_image_demo():
"""富文本和图片插入示例"""
doc = DocxTemplate("rich_template.docx")
# 创建富文本
rich_text = RichText()
rich_text.add('这是普通文本,')
rich_text.add('这是加粗文本', bold=True)
rich_text.add(',这是红色文本', color='FF0000')
rich_text.add(',这是带下划线的文本', underline=True)
context = {
'title': '带格式的文档',
'content': rich_text,
'author': '文档生成系统',
# 'logo': InlineImage(doc, 'logo.png', width=100, height=50) # 图片插入
}
doc.render(context)
doc.save("output_rich.docx")
print("富文本处理完成!")
# ==================== 5. 复杂嵌套结构 ====================
def complex_structure_demo():
"""复杂嵌套数据结构示例"""
doc = DocxTemplate("complex_template.docx")
context = {
'company': {
'name': '某某科技有限公司',
'address': '北京市海淀区某某路123号',
'contact': {
'phone': '010-12345678',
'email': 'contact@company.com',
'website': 'www.company.com'
}
},
'employees': [
{
'personal_info': {'name': '张三', 'age': 30},
'work_info': {'position': '经理', 'salary': 15000, 'level': 'P7'},
'skills': ['Python', 'Java', '项目管理']
},
{
'personal_info': {'name': '李四', 'age': 25},
'work_info': {'position': '工程师', 'salary': 12000, 'level': 'P5'},
'skills': ['JavaScript', 'Vue', 'React']
}
]
}
doc.render(context)
doc.save("output_complex.docx")
print("复杂结构处理完成!")
# ==================== 主函数 ====================
if __name__ == "__main__":
# 执行所有示例
simple_variable_demo()
loop_and_condition_demo()
table_demo()
rich_text_and_image_demo()
complex_structure_demo()
print("所有示例执行完成!")对应的模板文件内容示例
simple_template.docx 内容：
个人基本信息
姓名:{{ name }}
年龄:{{ age }}
公司:{{ company }}
职位:{{ position }}
日期:{{ date }}loop_template.docx 内容：
{{ department }}项目报告
{% for project in projects %}
项目名称:{{ project.name }}
负责人:{{ project.leader }}
项目成员:{{ project.members | join('、') }}
{% if project.status == 'completed' %}
状态:✅ 已完成
{% elif project.status == 'in_progress' %}
状态:🔄 进行中
{% else %}
状态:📅 规划中
{% endif %}
{% endfor %}table_template.docx 内容：
员工信息表
{% for user in users %}
{{ user.name }} | {{ user.email }} | {{ user.phone }} | {{ user.department }}
{% endfor %}
总计:{{ total_count }} 人rich_template.docx 内容：
{{ title }}
正文内容:{{ content }}
生成者:{{ author }}complex_template.docx 内容：
公司信息:
名称:{{ company.name }}
地址:{{ company.address }}
电话:{{ company.contact.phone }}
邮箱:{{ company.contact.email }}
员工列表:
{% for employee in employees %}
姓名:{{ employee.personal_info.name }}
年龄:{{ employee.personal_info.age }}
职位:{{ employee.work_info.position }}
薪资:{{ employee.work_info.salary }}
级别:{{ employee.work_info.level }}
技能:{{ employee.skills | join('、') }}
{% endfor %}这个代码示例展示了 docxtpl 的主要功能，包括变量替换、循环、条件判断、表格处理、富文本和复杂数据结构的使用。