如何使用python-docx-template模板化Word文档生成？

python-docx库的核心功能是程序化创建全新的Word文档，但在基于已有模板替换其部分内容时，其操作会非常繁琐。用户需要先解析文档结构、定位具体位置、手动替换内容，并维护原有格式与布局，导致开发效率较低。相关使用方法可参考：基于python-docx库的Word文档自动处理全解。 python-docx-template正是为解决这一痛点而设计的。它借鉴Jinja2模板引擎的思路，允许在Word文档中直接插入类似{{variable}}的占位符，随后仅用几行代码即可完成数据填充，无需关心底层文档结构，完美适配基于模板修改文档的场景。 python-docx-template基于python-docx实现文档读写功能，并借助jinja2提供灵活的模板标签支持，其设计思路如下： 用Word制作模板 在Microsoft Word中自由设计文档格式，如插入图片、设置页眉页脚、调整表格样式，充分利用Word强大的排版功能。 插入模板变量 在需要动态内容的位置，直接输入Jinja2风格的标签，例如{{company_name}}或{%for item in list%}。 保存为模板文件 将文档保存为普通的.docx文件，该文件即成为可复用的模板。 用Python批量生成 加载模板并传入字典或对象，python-docx-template会自动替换标签，生成最终文档。 python-docx-template的官方代码仓库地址为：python-docx-template，详细文档可参阅：python-docx-template doc。本文使用的python-docx-template版本为0.20.2，安装命令如下： pip install docxtpl 其中，docxtpl是python-docx-template库的正式分发名称，二者指代同一工具。 目录1 使用说明1.1 核心概念1.1.1 标签说明1.1.2 常见元素1.2 复杂元素1.2.1 富文本1.2.2 富文本段落1.2.3 浮动对象1.2.4 子文档1.3 补充操作1.3.1 转义操作1.3.2 获取未定义变量1.3.3 Jinja自定义过滤器1.3.4 Microsoft Word 2016特殊行为说明2 参考 1 使用说明 1.1 核心概念 1.1.1 标签说明 python-docx-template允许在Word文档中使用Jinja2标签和过滤器。但为确保其在Word中正常运作，需遵循若干限制。 常规Jinja2标签仅能在同一段落内且同一文本运行中使用，若需控制段落、表格行或包含样式的完整文本运行，则必须使用后续章节介绍的复杂元素标签语法。 举例而言，若创建一个所有字符样式相同的段落，Word内部只会生成一个文本运行对象。但若在该段落中将部分文字设置为加粗，Word会将原有文本运行拆分为三个独立部分，分别对应普通样式、加粗样式及恢复后的普通样式。 标签 若要对段落、表格行、表格列以及文本段进行管理，需使用以下专用语法： 段落标签：{%p jinja2_tag %} 表格行标签：{%tr jinja2_tag %} 表格列标签：{%tc jinja2_tag %} 文本段标签：{%r jinja2_tag %} 这些以{% %}包裹的内容是Jinja2模板语法标签，引擎会识别并执行其中的逻辑。一个完整的模板标签基本结构如下： {% 指令关键字 参数/条件 %} // 起始标签 内容 // 被标签控制的文本 {% 结束关键字 %} // 结束标签 通过此类标签，python-docx-template可自动将标准Jinja2标签，即去除前缀p、tr、tc、r后的内容，精确嵌入到文档XML源码的相应位置。 假设模板内容如下： {%p if display_paragraph %} 一段或多段文本内容 {%p endif %} 无论display_paragraph变量取值如何，首尾两个包含{%p ... %}标签的段落，都不会出现在最终生成的docx文档中。