如何在docxtpl中多次调用render()且不丢失未解析变量？

docxtpl的render()方法默认会一次性解析所有Jinja2语法，未提供的变量或块会被直接移除，导致后续渲染失效。以下是几种可行的解决方法：

方法一：自定义Jinja2未定义变量处理逻辑 #

通过修改Jinja2的undefined行为，让未定义的变量保留原始模板语法，这样多次调用render()时，未填充的变量不会被移除，后续仍可正常解析。

from docxtpl import DocxTemplate
from jinja2 import Undefined

# 自定义Undefined类，保留未定义变量的原始语法
class KeepUndefined(Undefined):
    def __str__(self):
        return self._undefined_name
    def __getattr__(self, name):
        return KeepUndefined(f"{self._undefined_name}.{name}")

# 初始化模板时指定自定义的jinja环境
doc = DocxTemplate("template.docx")
doc.jinja_env.undefined = KeepUndefined

# 第一次渲染部分上下文
doc.render({
    "TABLE": [
        {"a": 1, "b": 4},
        {"c": 3, "d": 7}
    ],
})

# 第二次渲染剩余上下文
doc.render({
    "ANOTHER_TABLE": [
        {"a": 5, "b": 7},
        {"c": 5, "d": 5}
    ],
})

doc.save("_generated.docx")

这种方法的核心是让Jinja2遇到未定义变量时，返回变量名本身而非空字符串，确保未填充的模板语法被完整保留。

方法二：分阶段使用自定义占位符 #

将模板中需要后续填充的内容替换为非Jinja2的自定义占位符（如[[占位符名称]]），分两步完成渲染：先处理Jinja2语法的内容，再通过python-docx的文本替换功能处理自定义占位符。

from docxtpl import DocxTemplate
from docx import Document

# 第一步：渲染Jinja2模板内容
doc = DocxTemplate("template.docx")
doc.render({
    "TABLE": [
        {"a": 1, "b": 4},
        {"c": 3, "d": 7}
    ],
})
temp_file = "temp_rendered.docx"
doc.save(temp_file)

# 第二步：替换自定义占位符
docx_doc = Document(temp_file)

# 替换段落中的占位符
for para in docx_doc.paragraphs:
    if "[[ANOTHER_TABLE]]" in para.text:
        # 此处可根据需求生成表格或替换为对应文本
        para.text = para.text.replace("[[ANOTHER_TABLE]]", "生成的表格内容")

# 替换表格单元格中的占位符
for table in docx_doc.tables:
    for row in table.rows:
        for cell in row.cells:
            if "[[ANOTHER_TABLE]]" in cell.text:
                cell.text = cell.text.replace("[[ANOTHER_TABLE]]", "表格单元格内容")

docx_doc.save("_generated.docx")

这种方法完全隔离了两次渲染的逻辑，避免Jinja2移除未解析内容，适合内存受限的场景，每次仅处理部分数据。

方法三：使用render_context叠加上下文（限新版docxtpl） #

部分新版本的docxtpl提供了render_context()方法，用于分步叠加上下文数据，最后一次性调用render()完成渲染，既避免了一次性加载大量数据到内存，也不会丢失未解析的模板语法。

from docxtpl import DocxTemplate

doc = DocxTemplate("template.docx")

# 分步添加上下文片段
doc.render_context({
    "TABLE": [
        {"a": 1, "b": 4},
        {"c": 3, "d": 7}
    ],
})

doc.render_context({
    "ANOTHER_TABLE": [
        {"a": 5, "b": 7},
        {"c": 5, "d": 5}
    ],
})

# 最后一次性完成渲染
doc.render()
doc.save("_generated.docx")

render_context()仅负责将数据添加到内部上下文字典，不会执行渲染操作，直到调用render()才会统一解析所有模板语法，完美适配分步加载数据的需求。

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