如何用python-docx-template填充复杂表格？遇cols属性未定义错误求助

错误根源 #

你遇到的UndefinedError是因为python-docx-template对带合并单元格的复杂表格的循环渲染逻辑有特定要求：默认情况下，模板引擎会期望每个循环数据项包含一个cols属性（或键），用来映射表格的列数据。而你传入的是普通字典，没有这个cols键，因此触发了未定义错误。拆分表格能正常渲染，是因为简单表格的循环逻辑不需要依赖cols，可以直接按字段映射。

解决方案 #

方案1：调整上下文数据结构，添加cols键 #

给每个数据字典添加cols键，值为按表格列顺序排列的字段值列表，确保和模板中表格列的顺序完全对应。

代码示例

from docxtpl import DocxTemplate

doc = DocxTemplate("实验室结果模板.docx")

# 原始实验数据字典列表
original_data = [
    {"regulation": "欧盟决议123/2020", "test_value": 96.8, "pass_status": "合格"},
    {"regulation": "国内法令456-2021", "test_value": 95.3, "pass_status": "合格"},
    {"regulation": "行业标准789-2022", "test_value": 94.1, "pass_status": "合格"}
]

# 调整数据结构，添加cols键（按表格列顺序取值）
context = {
    "test_data": [
        {"cols": [item["regulation"], item["test_value"], item["pass_status"]]}
        for item in original_data
    ]
}

# 渲染并保存
doc.render(context)
doc.save("填充后的实验室报告.docx")

如果需要保留原字典的字段（方便其他地方使用），可以用字典解包的方式同时保留原字段和cols：

context = {
    "test_data": [
        {**item, "cols": [item["regulation"], item["test_value"], item["pass_status"]]}
        for item in original_data
    ]
}

方案2：修改模板循环语法，直接绑定字段 #

不需要修改数据结构，而是在docx模板中直接指定每个单元格的字段取值，避免依赖默认的cols循环逻辑。

模板操作步骤

1. 在Word模板中，选中需要循环的数据行（不要包含表头）。
2. 在该行的开头添加Jinja2循环起始标签：{% for item in test_data %}
3. 在该行的结尾添加循环结束标签：{% endfor %}
4. 给每个单元格分别绑定对应的字段：
   • 第一个单元格（法规列）：{{ item.regulation }}
   • 第二个单元格（实验值列）：{{ item.test_value }}
   • 第三个单元格（状态列）：{{ item.pass_status }}

这种方式完全绕过了cols的要求，直接将字典字段映射到表格单元格，适合复杂表格的精准控制。

注意事项 #

• 复杂表格的合并单元格必须提前在模板中设置好样式，循环只应用于数据行，不要包含合并的表头部分。
• 使用方案1时，cols列表的顺序必须和表格列的顺序严格一致，否则会出现数据错位。
• 如果表格有多层嵌套的合并，建议先测试单条数据的渲染效果，再批量填充。

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