docxtpl模板引擎输出Word多表格文档

docxtpl模板引擎介绍

Docxtpl是基于Python的Word文档模板引擎，它结合了Jinja2模板语法和python-docx库的功能。通过使用{% %}和{{ }}标签，可以在Word模板中插入动态内容、循环和条件语句，自动生成定制化的Word文档，非常适合批量生成报告、合同等文档。

模板示例 ： 这里是一个简单的模板示例，展示循环生成多级目录结构 + 指定格式表格的word文档。下面我们将结合Json数据结构详细解析该模板中的使用的语法。

Json数据（片段）

语法介绍

1. 变量替换

• 语法： {{ variable.path }}
• 作用： 这是模板中最核心的功能，用于将数据模型中对应的值插入到指定位置。模板引擎在渲染时，会查找传入的数据对象，并用其属性值替换这些占位符。
• 示例解析：
  • {{module1.一级模块}}： 传入的数据是一个Key为 items 列表的对象，module1 是遍历该列表时的单个项。它会尝试获取 module1 对象的 一级模块 属性值并输出。
  • {{case.用例名称}}： 获取 case 对象的 用例名称 属性值。
  • {{step.操作步骤}}： 获取 step 对象的 操作步骤 属性值。

2. 循环控制 (Loop Control)

• 语法：

  {% for item in list %}
    ...循环体...
  {% endfor %}
  

• 作用： 用于遍历一个数组或列表，并对列表中的每一个元素重复生成一段内容。
• 示例解析：
  • {%- for module1 in items %}： 开始最外层的循环。遍历名为 items 的列表，items这个变量为接口内置，表示整个data参数。每次循环将列表中的当前元素赋值给变量 module1。{%- 中的减号 - 用于标识当前占位符所在的行在实际渲染时会合并到上一行，从而避免生成多余的空行。
  • {%tr for step in case.测试规程 %}： 这是一个特殊的循环，用于在 Word 表格的行中进行循环。tr 用于标识当前占位符所在的行在实际渲染时不会保留，否则表格中会多出一行空白行。
  • {% endfor %}： 结束对应的循环块。每一个 {% for ... %} 都必须有一个对应的 {% endfor %}。

3. 循环内置变量 (Loop Internal Variables)

• 语法： {{ loop.index }}
• 作用： 在 for 循环内部，Jinja2 提供了一个特殊的 loop 对象，用于获取循环的元信息。
• 示例解析：
  • {{loop.index}}： 在 {%tr for step in case.测试规程 %} 循环中，loop.index 会输出当前迭代的序号（从 1 开始）用于生成测试步骤的序号列。

渲染模板

下面是渲染模板的核心代码部分

def generate_docx_from_template(template_file, var_data):
    """
    根据模板和变量数据生成Word文档
    Args:
        template_file: Word模板文件路径
        var_data: 模板变量数据，可以是字典或列表
    Returns:
        None: 直接保存生成的Word文档到当前目录
    """
    # 加载模板
    doc = DocxTemplate(template_file)
    # 准备上下文数据
    context = {"items": var_data}
    # 渲染模板
    doc.render(context)
    doc.save("输出文件.docx")

详细语法规则

python-docxtpl 模板手册