Metadata-Version: 2.4
Name: word-template-engine
Version: 0.1.0
Summary: A Word template engine similar to docx-template, implemented with python-docx and lxml.
Project-URL: Homepage, https://github.com/yourname/word-template-engine
Project-URL: Repository, https://github.com/yourname/word-template-engine
Author-email: Your Name <you@example.com>
License: MIT
Requires-Python: >=3.8
Requires-Dist: lxml>=4.9.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# 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安装依赖：

```bash
pip install wps_temp_engine
```

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

## 使用方法

### 1. 创建Word模板

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

#### 文本替换
- `{{data.diagnose}}`

#### 表格行循环
在表格行的单元格中写入 `{{#data.mutationSiteZero}}`，其他单元格使用方括号占位符：
- `[gene_transcript]`
- `[value]`
- `[description]`

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

#### 条件区块
```text
{{?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代码渲染

```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. 条件区块

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

```text
{{?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解析的最大优势
