Docxtpl

docxtpl 技能 使用 .docx 文件作为 Jinja2 模板，然后在运行时用 Python 数据填充。 安装 pip install docxtpl # 支持子文档： pip install "docxtpl[subdoc]" 快速开始 从 docxtpl 导入 DocxTemplate doc = DocxTemplate("my_template.docx") context = {"name": "Alice", "department": "Cardiology"} doc.render(context) doc.save("output.docx") 工作流程： 在 Word 中设计一个 .docx 文件，包含 Jinja2 标签（{{ var }，{%p if ... %}}） 使用 DocxTemplate(path) 加载模板 构建一个 Python 上下文字典 调用 doc.render(context) 然后 doc.save(path) 标签参考 标签 作用域 目的 {{ var }} 内联字符串 显示变量 {{r var }} 内联样式 显示 RichText 对象 {%p ... %} 段落 控制整个段落（if/for） {%tr ... %} 表格行 控制表格行 {%tc ... %} 表格列 控制表格列 {%r ... %} 跑 控制样式跑 {%p if cond %} / {%p endif %} 段落 条件段落 {%p for x in list %} / {%p endfor %} 段落 循环段落 {% colspan N %} 表格单元格 水平单元格跨越 {% hm %} 表格单元格 水平合并在循环中 {% vm %} 表格单元格 垂直合并在循环中 {% cellbg color %} 表格单元格 设置单元格背景颜色 { #p comment #} 段落 注释 {%- -%} 文本合并 合并拆分行 { _%, %_ } ，{ _{, }_ } 转义 显示字面 {%, %}，{{, }} 重要：始终在分隔符周围添加空格：{{ var }} 而不是 {{var}}。 CLI 用法 python -m docxtpl template.docx data.json output.docx python -m docxtpl -o template.docx data.json output.docx # 覆盖 关键类 DocxTemplate(path) — 加载 .docx 模板。 方法：.render(context)，.save(path)，.get_undeclared_template_variables(context=None) RichText(text, ...) / R(text) — 带样式的文本，使用 .add() 进行多样式连接 InlineImage(tpl, img_path, width, height) — 动态图像插入（使用 Mm()、Inches() 或 Pt() 作为尺寸） Listing(text) — 转义文本，保留 \n/\a/\f 而不失去样式 RichTextParagraph() / RP() — 段落级别属性（与 {{p var }} 一起使用） Subdoc — tpl.new_subdoc(path) 合并现有的 .docx 文件 媒体替换 对于不支持动态标签的标题/页脚： tpl.replace_pic("dummy.jpg", "real.jpg") # 图片 tpl.replace_media("dummy.mp3", "real.mp3") # 任意媒体 tpl.replace_embedded("dummy.docx", "real.docx") # 嵌入文档 tpl.replace_zipname("path/in/zip.xlsx", "real.xlsx") # 原始 zip 条目 转义 默认情况下，不自动转义。使用以下任一方法： RichText 用于安全内容 {{ var|e }} 在模板中转义 escape("text") 在 Python 上下文中转义 tpl.render(context, autoescape=True) 提示 \n → 新行，\a → 新段落，\t → 制表符，\f → 页断（在字符串和 RichText 中） 如果使用媒体替换，渲染模板多次，请在每次 render() 之前调用 tpl.reset_replacements() 将自定义 jinja_env 传递给 render() 以使用自定义 Jinja2 过滤器 预览 get_undeclared_template_variables() 以警告缺失键 完整 API 参考：references/official-docs.md CLI 脚本 scripts/ 中的便捷脚本（使用 {baseDir}/scripts/ 路径）： # 使用内联 key=value 对渲染 python scripts/docxtpl-render.py template.docx out.docx name="Alice" age="30" # 从 JSON 文件渲染 python scripts/docxtpl-render-json.py template.docx data.json out.docx # 从 JSON 字符串渲染 python scripts/docxtpl-render.py template.docx out.docx --json '{"name":"Bob"}' # 列出缺失模板变量 python scripts/docxtpl-list-vars.py template.docx # 从 CSV 批量渲染（每行一个 .docx 文件，按 id 列命名） python scripts/docxtpl-render-batch.py patients.csv ./reports/ template.docx \ --id-column patient_id --suffix _report --summary