docxtpl中代码与模板的&符号丢失/被替换为空白问题求助

问题原因 #

docxtpl基于Jinja2模板引擎，而docx格式本质是XML文件集合。XML中&是特殊字符，用于定义实体引用（如&代表&），不管是Python传入的字符串还是Word模板里的&，都会被XML解析器或Jinja2的自动转义机制处理，导致显示空白或丢失。

解决方案 #

1. 处理Python代码中传入的带&的字符串 #

有两种可行方法：

• 方法一：手动转义&为XML实体&
  修改传入的字符串，把&替换成&，XML解析时会自动还原为&：

  from docxtpl import DocxTemplate
  
  adjective = "results & data-driven"  # 转义&为&
  
  doc = DocxTemplate("Resume_Template.docx")
  context = {'job_title': adjective}
  doc.render(context)
  doc.save("generated_resume.docx")
  

• 方法二：使用Jinja2的safe过滤器关闭自动转义
  在Word模板的变量位置，把{{ job_title }}改成{{ job_title|safe }}，Jinja2就不会转义字符串里的特殊字符，XML解析时能正确识别&。Python代码保持原样即可：

  from docxtpl import DocxTemplate
  
  adjective = "results & data-driven"
  
  doc = DocxTemplate("Resume_Template.docx")
  context = {'job_title': adjective}
  doc.render(context)
  doc.save("generated_resume.docx")
  

2. 处理Word模板中原有的静态&（如“FP&A Manager”） #

• 正常在Word里编辑模板时直接输入&即可，Word会自动将其保存为XML中的&；
• 如果仍出现丢失问题，可手动修改docx文件：将后缀改为zip，解压后找到word/document.xml文件，把里面的&替换成&，重新打包为docx格式。

验证 #

按上述方法修改后，生成的Word文档中，无论是传入的还是模板原有的&都能正常显示。

内容的提问来源于stack exchange，提问作者WQureshi