word-template-engine 0.1.0

A Word template engine similar to docx-template, implemented with python-docx and lxml.

Word模板引擎

一个类似于docx-template的Word模板引擎，使用Python直接解析Word文档的XML结构实现，完全保留所有样式信息。

功能特性

1. 字符串文本替换: {{data.diagnose}} - 替换为对应的数据值（不需要结束标签）

2. 表格行循环: {{#data.mutationSiteZero}} - 在表格头部标记，根据数据循环生成表格行，使用[field_name]作为字段占位符（不需要结束标签）

3. 表格列循环: {{$data.mutationSiteZero}} - 在表格头部标记，根据数据循环生成表格列（不需要结束标签）

4. 条件区块: {{?data.field != null && data.field.size() > 0}}...{{/}} - 根据条件显示或隐藏内容块（需要结束标签 {{/}}）

5. 图片插入: {{@var}} - 插入图片，var格式: {'url': '', 'conf': {'w': '180px', 'h': '180px'}}（不需要结束标签）

6. 列表循环: {{*data.conclusion_C}} - 循环显示列表项（不需要结束标签）

标签说明

有结束标签的标签

• 区块: {{?condition}}...{{/}}
  • 只有区块需要结束标签
  • 支持嵌套
  • 示例：

    {{?data.conclusion_C == ''}}无{{/}}
    {{?data.conclusion_C != ''}}
    {{*data.conclusion_C}}
    {{/}}
    

不需要结束标签的标签

• 文本替换: {{data.field}}
• 表格行循环: {{#data.field}} - 后面直接跟字段如[gene_transcript]
• 表格列循环: {{$data.field}}
• 图片: {{@var}}
• 列表: {{*data.field}}

安装

使用pip安装依赖：

pip install wps_temp_engine

注意: 本引擎直接解析Word文档的XML结构，这样可以完整保留所有样式信息。

使用方法

1. 创建Word模板

在Word文档中使用以下占位符：

文本替换

• {{data.diagnose}}

表格行循环

在表格行的单元格中写入 {{#data.mutationSiteZero}}，其他单元格使用方括号占位符：

• [gene_transcript]
• [value]
• [description]

表格列循环

在表格列的第一个单元格写入 {{$data.mutationSiteZero}}

条件区块

{{?data.mutationSiteZero.size() > 0}}
这部分内容只有在条件为真时才会显示
{{/}}

支持的条件：

• size() > 0

图片

方式1: 使用变量名

{{@data.image_config}}

方式2: 直接写JSON

{{@{'url':'path/to/image.jpg','conf':{'w':'180px','h':'180px'}}}}

支持的尺寸单位: px, cm, in, mm

列表

{{*data.conclusion_C}}

2. 使用Python代码渲染

from word_template_engine import WordTemplateEngine

# 创建引擎实例
engine = WordTemplateEngine('template.docx')

# 准备数据
data = {
    'data': {
        'diagnose': '诊断结果',
        'mutationSiteZero': [
            {'gene_transcript': 'Gene1', 'value': 'Value1', 'description': 'Desc1'},
            {'gene_transcript': 'Gene2', 'value': 'Value2', 'description': 'Desc2'},
        ],
        'conclusion_C': ['结论1', '结论2', '结论3'],
    }
}

# 渲染并保存
engine.render(data, 'output.docx')

详细说明

1. 字符串文本替换

模板中写入: {{data.diagnose}}

数据中提供: {'data': {'diagnose': '测试结果'}}

结果: 替换为 "测试结果"

2. 表格行循环

在表格的某一行的单元格中写入 {{#data.mutationSiteZero}}，该行将成为模板行。

其他单元格使用方括号占位符，如 [gene_transcript]、[value]。

根据 data.mutationSiteZero 数组的长度，会自动生成对应数量的表格行。

注意: 表格行循环不需要结束标签，循环标记后直接跟字段占位符。

3. 表格列循环

在表格某一列的单元格中写入 {{$data.mutationSiteZero}}，该列将成为模板列。

根据数据数组长度，会自动为所有行添加新列。

4. 条件区块

支持条件判断，需要结束标签：

{{?data.conclusion_C == ''}}无{{/}}
{{?data.conclusion_C != ''}}
{{*data.conclusion_C}}
{{/}}

支持的操作符：

• != null / == null
• == '' / != '' （检查空字符串）
• size() > 0
• && (AND)
• || (OR)

支持嵌套区块。

5. 图片插入

两种方式：

方式1: 使用变量名

{{@data.image_config}}

其中 data.image_config 是字典格式的配置。

方式2: 直接写JSON

{{@{'url':'https://example.com/image.jpg','conf':{'w':'180px','h':'180px'}}}}

支持的尺寸单位: px, cm, in, mm

图片可以是HTTP/HTTPS链接或本地文件路径。

6. 列表循环

模板中写入: {{*data.conclusion_C}}

数据中提供: {'data': {'conclusion_C': ['项目1', '项目2', '项目3']}}

结果: 展开为多行文本，每行一个项目

处理顺序

引擎按以下顺序处理模板：

1. 区块 - 先处理条件区块（因为它有结束标签，可能包含其他标签）
2. 列表 - 处理列表循环
3. 文本 - 处理文本占位符
4. 图片 - 处理图片占位符
5. 表格 - 最后处理表格（行循环和列循环）

项目结构

.
├── pyproject.toml           # 项目配置
├── word_template_engine.py  # 主引擎类（XML版本）
├── example.py               # 使用示例
├── README.md                # 详细文档
├── template.docx            # 模板文件
└── utils/                   # 工具模块
    ├── __init__.py
    ├── xml_processor.py     # XML处理工具
    ├── text_processor.py    # 文本处理
    ├── table_processor.py   # 表格处理（保留兼容）
    ├── block_processor.py   # 区块处理
    ├── image_processor.py   # 图片处理
    └── list_processor.py    # 列表处理

技术实现

本引擎直接解析Word文档的XML结构（.docx文件实际上是一个ZIP压缩包，包含XML文件），这样可以：

• 完全保留样式信息：所有格式、字体、颜色、对齐等样式都会保留
• 精确控制：直接操作XML节点，可以精确处理复杂的文档结构
• 高性能：无需通过中间库转换，直接操作XML

主要处理流程：

1. 解压.docx文件（ZIP格式）
2. 解析 word/document.xml 主文档
3. 在XML层面进行占位符替换和循环处理
4. 重新打包为.docx文件

注意事项

1. 模板文件必须是有效的.docx格式
2. 表格行循环标记需要放在表格的单元格中
3. 表格行循环不需要结束标签，直接在标记后使用[field]占位符
4. 只有区块需要结束标签 {{/}}
5. 图片URL可以是HTTP/HTTPS链接或本地文件路径（图片功能在XML版本中暂未完整实现）
6. 条件表达式支持基本的逻辑运算
7. 嵌套的字段访问使用点号，如 data.sub_field.value
8. 支持嵌套的条件区块
9. 所有样式都会完整保留，包括字体、颜色、大小、对齐等，这是使用XML解析的最大优势