1 实用案例1.1 表格样式生成本示例用于生成包含富文本样式与单元格背景色的Word表格文档。模板内容渲染代码# python-docx-template/blob/master/tests/comments.pyfrom docxtpl import DocxTemplate, RichText# data: python-docx-template/blob/master/tests/templates/cellbg_tpl.docxtpl DocxTemplate(templates/cellbg_tpl.docx)context {alerts: [{date: 2015-03-10,desc: RichText(Very critical alert, colorFF0000, boldTrue),type: CRITICAL,bg: FF0000,},{date: 2015-03-11,desc: RichText(Just a warning),type: WARNING,bg: FFDD00,}],}tpl.render(context)tpl.save(output/cellbg.docx)1.2 自定义Jinja2过滤器本示例主要介绍通过自定义Jinja2过滤器实现动态数据渲染Jinja2模板中过滤器的核心格式为{{ 变量名|过滤器名(参数1, 参数2, ...) }}其中|竖线是过滤器的分隔符左侧是要处理的变量右侧是过滤器名称括号()内是传给过滤器函数的参数无参数时可省略括号示例{{ base_value_float|my_filterB(2) }} 中base_value_float是变量my_filterB是过滤器名2是传递的参数。模板内容渲染代码# python-docx-template/blob/master/tests/custom_jinja_filters.pyfrom docxtpl import DocxTemplateimport jinja2# 创建jinja2环境对象用于管理模板渲染的配置jinja_env jinja2.Environment()# 自定义过滤器函数def my_filterA(value, my_string_arg):# 将原始值和参数字符串拼接中间加空格return_value value my_string_argreturn return_valuedef my_filterB(value, my_float_arg):# 将原始值和参数数值相加return_value value my_float_argreturn return_value# 将自定义过滤器注册到jinja2环境中使其能在模板中被调用# 注册后在Word模板中可通过{{ 变量名| my_filterA(参数) }}形式使用jinja_env.filters[my_filterA] my_filterAjinja_env.filters[my_filterB] my_filterBcontext {base_value_string: Hello,base_value_float: 1.5}# data: python-docx-template/blob/master/tests/templates/custom_jinja_filters_tpl.docxtpl DocxTemplate(templates/custom_jinja_filters_tpl.docx)tpl.render(context, jinja_env)tpl.save(output/custom_jinja_filters.docx)1.3 文档嵌入以下代码展示了如何渲染子Word文档替换主Word文档中嵌入的各类文件填充数据后保存文档# python-docx-template/blob/master/tests/embedded.pyfrom docxtpl import DocxTemplate# 加载内嵌子模板文件# data: python-docx-template/blob/master/tests/templates/embedded_embedded_docx_tpl.docxembedded_docx_tpl DocxTemplate(templates/embedded_embedded_docx_tpl.docx)# 定义模板渲染的上下文数据context {name: John Doe, # 要填充到模板中的姓名值}embedded_docx_tpl.render(context)# 保存渲染后的子模板到指定路径供后续主模板调用embedded_docx_tpl.save(output/embedded_embedded_docx.docx)# 加载主模板文件tpl DocxTemplate(templates/embedded_main_tpl.docx)# 定义主模板的上下文数据context {name: John Doe,}# 替换主模板中嵌入的Word文档# 参数1模原本嵌入的占位文件路径# 参数2要替换成的目标文件路径tpl.replace_embedded(templates/embedded_dummy.docx, templates/embedded_static_docx.docx)tpl.replace_embedded(templates/embedded_dummy2.docx, output/embedded_embedded_docx.docx)# 说明docx 本质是 zip 压缩包嵌入的文件会存储在word/embeddings/目录下tpl.replace_zipname(word/embeddings/Feuille_Microsoft_Office_Excel3.xlsx,templates/real_Excel.xlsx # 要替换成的实际文件路径)tpl.replace_zipname(word/embeddings/Pr_sentation_Microsoft_Office_PowerPoint4.pptx,templates/real_PowerPoint.pptx)tpl.render(context)tpl.save(output/embedded.docx)1.4 自动转义本示例展示了在自动转义模式下将包含XML特殊字符、Unicode文本和动态键值对的上下文数据渲染到模板中。模板内容渲染代码# python-docx-template/blob/master/tests/escape_auto.pyimport osfrom unicodedata import namefrom docxtpl import DocxTemplateXML_RESERVED # data: python-docx-template/blob/master/tests/templates/escape_tpl_auto.docxtpl DocxTemplate(templates/escape_tpl_auto.docx)context {nested_dict: {name(str(c)): c for c in XML_RESERVED},autoescape: Escaped str ing!,autoescape_unicode: This is an escaped example \u4f60 \u6211,iteritems: lambda x: x.items(),}# autoescapeTrue表示自动转义tpl.render(context, autoescapeTrue)OUTPUT outputif not os.path.exists(OUTPUT):os.makedirs(OUTPUT)tpl.save(OUTPUT /escape_auto.docx)实际上iteritems(nested_dict)就是调用渲染定义的lambda函数把nested_dict传进去拿到它的所有键值对{% for k, v in iteritems(nested_dict) %}{{ k.capitalize() }}: {{ v }}{% endfor %}也可以在Jinja2模板中使用Python表达式直接调用字典的item方法{% for k, v in nested_dict.items() %}{{ k.capitalize() }}: {{ v }}{% endfor %}1.5 图片替换以下示例说明如何替换Word模板文档包含页眉页脚中的图片并演示如何将处理后的文档分别通过常规方式和内存文件对象保存为本地文件# python-docx-template/blob/master/tests/header_footer_image_file_obj.pyfrom docxtpl import DocxTemplateimport io# 定义两个输出文档的路径和文件名DEST_FILE output/header_footer_image_file_obj.docxDEST_FILE2 output/header_footer_image_file_obj2.docx# data: python-docx-template/blob/master/tests/templates/header_footer_image_tpl.docxtpl DocxTemplate(templates/header_footer_image_tpl.docx)context {mycompany: The World Wide company,}# 读取模板中需要被替换的图片文件并转换为内存字节流对象dummy_pic io.BytesIO(open(templates/dummy_pic_for_header.png, rb).read())# 读取新的替换图片文件python.png并转换为内存字节流对象new_image io.BytesIO(open(templates/python.png, rb).read())# 将dummy_pic对应的图片替换为new_image对应的图片tpl.replace_media(dummy_pic, new_image)tpl.render(context)tpl.save(DEST_FILE)tpl DocxTemplate(templates/header_footer_image_tpl.docx)# 将内存中的图片字节流指针重置到起始位置dummy_pic.seek(0)new_image.seek(0)# 再次执行图片替换操作tpl.replace_media(dummy_pic, new_image)# 再次渲染模板变量tpl.render(context)# 创建一个空的内存字节流对象用于临时存储文档内容file_obj io.BytesIO()# 将处理后的文档保存到内存字节流对象中tpl.save(file_obj)# 将内存字节流指针重置到起始位置准备读取内容file_obj.seek(0)# 以二进制写入模式打开第二个输出文件将内存中的文档内容写入文件with open(DEST_FILE2, wb) as f:f.write(file_obj.read())dummy_pic.close()new_image.close()上述代码实现图片替换并非基于文件名而是基于二进制内容的匹配。这是因为replace_media方法根据图片的二进制内容来识别图像而非依赖文件名或在Word中显示的名称。由于Word文档 (.docx) 本质上是一个压缩包其中的图片以二进制形式存储在word/media/目录下且在某些Word版本中图片文件名可能被自动重命名例如改为 image1.png与原始文件名无关。注意??待替换图片尺寸不宜过大且需关闭Word模板的图片压缩功能否则Word会自动压缩模板中的图片改变其二进制数据最终导致图片替换操作失败。1.6 命令行执行以下示例展示了直接在命令行中使用docxtpl模块基于模板文件和作为上下文数据的JSON文件生成docx文档# python-docx-template/blob/master/tests/module_execute.pyimport os# data: python-docx-template/blob/master/tests/templates/module_execute_tpl.docxTEMPLATE_PATH templates/module_execute_tpl.docx# 存储需要填充到模板中的数据JSON_PATH templates/module_execute.jsonOUTPUT_FILENAME output/module_execute.docx# docxtpl命令参数强制覆盖已存在的输出文件OVERWRITE -o# docxtpl命令参数静默模式执行不输出额外日志信息QUIET -q# 删除已存在的输出文件if os.path.exists(OUTPUT_FILENAME):os.unlink(OUTPUT_FILENAME)# 切换工作目录到当前脚本所在的目录os.chdir(os.path.dirname(__file__))# 通过Python模块方式调用docxtpl传入模板、数据、输出路径和参数# 可通过python -m docxtpl -help查看调用帮助cmd python -m docxtpl %s %s %s %s %s % (TEMPLATE_PATH, # 模板文件路径JSON_PATH, # 数据文件路径OUTPUT_FILENAME, # 输出文件路径OVERWRITE, # 覆盖参数QUIET # 静默参数)print(Executing %s ... % cmd)os.system(cmd)if os.path.exists(OUTPUT_FILENAME):print( -- File %s has been generated. % OUTPUT_FILENAME)1.7 多层嵌套以下示例展示了如何通过模板语法实现逐层循环渲染最终生成包含这些嵌套数据的Word文档# python-docx-template/blob/master/tests/nested_for.pyfrom docxtpl import DocxTemplate# data: python-docx-template/blob/master/tests/templates/nested_for_tpl.docxtpl DocxTemplate(templates/nested_for_tpl.docx)context {dishes: [{name: Pizza, ingredients: [bread, tomato, ham]},{name: Hamburger,ingredients: [bread, chopped steak, cheese],},],authors: [{name: Saint-Exupery,books: [{title: Le petit prince},{title: Laviateur},],},{name: Barjavel,books: [{title: Ravage},{title: La nuit des temps},],},],}tpl.render(context)tpl.save(output/nested_for.docx)1.8 地区字体处理若字体显示异常通常是由于字体仅适配了特定文字区域。解决方法是在字体名前加上区域标识和冒号如 eastAsia:微软雅黑从而指定文字的区域渲染方式。如果不清楚区域标识也可解压模板文件后分析document.xml确认字体对应的区域。常见区域标识包括eastAsia用于东亚字符如中文hAnsi用于拉丁字符如英文ascii用于兼容旧版英文以下代码展示了如何设置不同的东亚字体# python-docx-template/blob/master/tests/richtext_eastAsia.pyfrom docxtpl import DocxTemplate, RichText# data: python-docx-template/blob/master/tests/templates/richtext_eastAsia_tpl.docxtpl DocxTemplate(templates/richtext_eastAsia_tpl.docx)# 2. 创建富文本对象分别设置不同的东亚字体# eastAsia: 前缀表示该字体设置仅作用于东亚字符中文、日文、韩文等rt RichText(测试TEST, fonteastAsia:Microsoft YaHei)ch RichText(测试TEST, fonteastAsia:微软雅黑)sun RichText(测试TEST, fonteastAsia:SimSun)context {example: rt,Chinese: ch,simsun: sun,}tpl.render(context)tpl.save(output/richtext_eastAsia.docx)1.9 富文本使用Python-docx-template的核心功能是基于Jinja2语法动态生成Word文档。其RichText类进一步增强了灵活性允许直接以编程方式插入格式丰富的文本而无需为每种样式组合单独设置模板变量。RichText对象可在初始化时直接传入文本通过多次调用add方法可向其追加不同格式的文本片段。最后将该对象整体赋给模板上下文中的变量。在Word模板中只需使用{{ rich_text_var }}引用该变量即可渲染成包含多种格式的连续段落。add方法是构建RichText对象的核心其所有参数均用于控制当前操作所添加文本的格式参数 类型 默认值 说明text str 无 唯一必需参数要追加的文本内容style str None 应用段落样式这会影响整个由RichText对象生成的段落的样式color str None 字体颜色支持十六进制如#FF0000或Word预设颜色名如redhighlight str None 文本背景高亮色取值同color参数size int None 字体大小subscript bool None 设为True时文本显示为下标与superscript互斥superscript bool None 设为True时文本显示为上标与subscript互斥bold bool False 设为True时文本加粗italic bool False 设为True时文本倾斜underline bool False 设为True时文本添加下划线strike bool False 设为True时文本添加删除线font str None 字体名称url_id str None 添加超链接需要传入一个链接ID该ID一般通过文档对象的build_url_id()方法生成rtl bool False 设为True时文本从右向左排列仅对阿拉伯语、希伯来语等有效lang str None 设置文本的语言用于拼写检查和断字重要提示??style段落样式参数比较特殊。它通常只在第一次调用add方法时有效后续调用中再设置style通常会被忽略。以下是一段使用示例代码按顺序介绍RichText.add()方法的各个参数from docxtpl import DocxTemplate, RichTextimport os# 1. 创建模板对象并初始化RichTextdoc DocxTemplate(template.docx)rt RichText()# 2. 添加基础文本必需参数rt.add(这是普通文本)# 3. 设置段落样式影响整个段落rt.add(\n标题文本, styleHeading1)# 4. 设置字体颜色rt.add( 红色文字, color#FF0000)rt.add( 蓝色文字, colorblue)# 5. 设置背景高亮rt.add( 黄底文字, highlightyellow)# 6. 设置字体大小单位磅rt.add( 小号字, size8)rt.add( 大号字, size20)# 7. 上下标设置rt.add( 正常文字)rt.add( 上标, superscriptTrue)rt.add( 下标, subscriptTrue)# 8. 字体样式rt.add( 加粗, boldTrue)rt.add( 倾斜, italicTrue)rt.add( 下划线, underlineTrue)rt.add( 删除线, strikeTrue)# 9. 字体设置rt.add( 宋体, fonteastAsia:SimSun)rt.add( 微软雅黑, fonteastAsia:Microsoft YaHei)# 10. 超链接需要先生成链接IDurl_id doc.build_url_id(https://www.example.com)rt.add( 超链接文本, url_idurl_id)# 11. 文字方向rt.add( 正常方向)rt.add( 从右向左文字, rtlTrue) # 中文设置无效果# 12. 语言设置rt.add( English text, langen-US)rt.add( 中文文本, langzh-CN)context {rich_text_var: rt}doc.render(context)os.makedirs(output,exist_okTrue)doc.save(output/generated_document.docx)在模板中只需简单引用{{ rich_text_var }}1.10 错误管理TemplateError类是Jinja2模板引擎中所有模板相关异常的基类在python-docx-template中专门用于捕获模板渲染过程中出现的各类错误。当使用tpl.render()渲染 Word 模板时以下情况会抛出TemplateError异常模板中引用了未传入的变量如模板写了{{ name }}但render只传了test_variable模板中的Jinja2语法错误如缺少闭合的{% endif %}、变量引用格式错误模板中使用了不存在的过滤器/函数如{{ test_variable | xxx }}xxx不是 Jinja2 内置过滤器。以下代码展示了如何测捕获Word模板渲染时的TemplateError异常并打印详细的错误信息from docxtpl import DocxTemplatefrom jinja2.exceptions import TemplateErrorprint( * 50)print(正在生成测试用的模板错误)print(. * 50)try:tpl DocxTemplate(templates/template_error_tpl.docx)# 如果模板中存在语法错误或变量缺失会触发TemplateError异常tpl.render({test_variable: 测试变量值})# 捕获模板渲染过程中出现的所有TemplateError异常except TemplateError as the_error:# 打印错误的基本描述信息print(f模板渲染错误{str(the_error)})# 检查异常对象是否包含docx_context属性if hasattr(the_error, docx_context):# 打印上下文信息的标题print(错误上下文详情)# 遍历并打印错误上下文的每一行内容for line in the_error.docx_context:print(line)# 确保tpl变量存在时再执行保存操作if tpl in locals():# 将渲染后的文档保存到指定路径tpl.save(output/template_error.docx)print(f文档已保存至output/template_error.docx)print(. * 50)print( 模板错误测试完成 )print( * 50)崩秦教冒