跳到主要内容

Word模板

Word模板专用于生成和处理Word格式文档，基于Jinja2模板引擎实现动态文档生成。它负责Word文档的模板化渲染、变量替换和复杂内容填充，支持文本、图片、表格、链接等多种元素的动态处理，适用于合同、报告、公文等正式文档的批量生成。

Word模板元素分层结构为Meta（fileTmpls.Meta） → Type（fileTmpls.WordType） → 实例，开发者可通过JitAi的可视化开发工具快捷地创建Word模板实例元素。

当然，开发者也可以创建自己的Type元素，或者在自己的App中改写JitAi官方提供的fileTmpls.WordType元素，以实现自己的封装。

快速开始​

创建实例元素​

目录结构​

推荐目录结构
fileTmpls/
└── testWordTemplate/
    ├── e.json
    ├── testWordTemplate.json
    └── templateFile.docx

e.json文件​

基础配置文件
{
  "title": "测试Word模板",
  "type": "fileTmpls.WordType",
  "frontBundleEntry": "testWordTemplate.json",
  "backendBundleEntry": "."
}

业务配置文件​

testWordTemplate.json
{
  "dataList": [
    {
      "name": "name",
      "title": "姓名",
      "dataType": "Stext"
    },
    {
      "name": "company",
      "title": "公司名称", 
      "dataType": "Stext"
    },
    {
      "name": "date",
      "title": "签署日期",
      "dataType": "Date"
    }
  ],
  "files": {
    "fileName": "合同模板.docx"
  }
}

调用示例​

Word模板渲染示例
# 获取Word模板元素
template = app.getElement("fileTmpls.testWordTemplate")

# 准备渲染数据
context = {
    "name": "张三",
    "company": "某某科技有限公司",
    "date": "2024-01-15"
}

# 渲染生成Word文档
result = template.render(context)

# result是BytesIO对象，可以保存或下载
with open("生成的文档.docx", "wb") as f:
    f.write(result.getvalue())

元素配置​

e.json配置​

配置项类型必填说明
titlestring是模板显示名称
typestring是固定值"fileTmpls.WordType"
frontBundleEntrystring是业务配置文件路径
backendBundleEntrystring是后端入口，通常为"."

业务配置文件配置​

配置项类型必填说明
dataListarray是模板变量定义列表
filesobject是模板文件配置

dataList配置项​

配置项类型必填说明
namestring是变量名称
titlestring是变量显示名称
dataTypestring是数据类型（Stext、Date、Numeric等）

files配置项​

配置项类型必填说明
fileNamestring是Word模板文件名称
urlstring否模板文件URL（兼容旧版本）

方法​

render​

将数据通过Word模板渲染生成最终文档。

参数详解​

参数名类型对应原生类型必填说明
contextJitDictdict是渲染数据字典
elemNameStextstr否元素名称，用于内部处理

返回值​

返回BytesIO对象，包含生成的Word文档二进制数据。

使用示例​

基础渲染示例
template = app.getElement("fileTmpls.contractTemplate")

# 准备上下文数据
context = {
    "customerName": "张三",
    "contractNo": "CT2024001",
    "amount": 100000,
    "signDate": "2024-01-15"
}

# 执行渲染
document = template.render(context)

# 保存文档
with open("合同.docx", "wb") as f:
    f.write(document.getvalue())

handleContext​

处理和转换渲染上下文数据，将前端传入的数据转换为Jinja2模板可识别的格式。

参数详解​

参数名类型对应原生类型必填说明
contextJitDictdict是原始上下文数据
elemNameStextstr是元素全名

返回值​

返回处理后的上下文数据字典。

getTemplateDt​

获取模板中定义的数据类型映射。

返回值​

返回数据类型映射字典，键为变量名，值为对应的数据类型处理类。

属性​

templateFile​

获取模板文件的二进制流对象，支持从本地文件或URL获取。

访问模板文件
template = app.getElement("fileTmpls.myTemplate")
file_stream = template.templateFile

config​

获取模板的完整配置信息，包含dataList、files等配置项。

访问配置信息
template = app.getElement("fileTmpls.myTemplate")
data_list = template.config.get("dataList", [])

dtMap​

获取模板数据类型映射表，用于数据类型转换和验证。

高级特性​

复杂内容支持​

Word模板支持多种复杂内容的动态生成：

复杂内容渲染示例
template = app.getElement("fileTmpls.advancedTemplate")

context = {
    "title": "项目报告",
    "content": "这是一个包含多种元素的文档",
    # 图片URL，模板中使用ToPictureFileTmpls:标记
    "chartImage": "https://example.com/chart.png",
    # 超链接，模板中使用ToLinkFileTmpls:标记  
    "projectLink": "项目地址: https://github.com/project",
    # 二维码数据，模板中使用<image:标记
    "qrcode": {
        "image": "base64编码的图片数据",
        "width": 3,
        "height": 3
    }
}

document = template.render(context)

表格单元格图片处理​

模板支持在表格单元格中动态插入图片，自动适应单元格尺寸：

表格图片配置
{
  "dataList": [
    {
      "name": "productImage",
      "title": "产品图片",
      "dataType": "Stext"
    }
  ]
}
表格图片渲染
context = {
    "productImage": "ToPictureFileTmpls:https://example.com/product.jpg"
}

document = template.render(context)

模板文件制作建议​

  1. 变量标记：在Word模板中使用{{变量名}}标记需要替换的内容
  2. 图片标记：使用ToPictureFileTmpls:图片URL标记图片位置
  3. 链接标记：使用ToLinkFileTmpls:显示文本: URL标记超链接
  4. 保持格式：模板制作时注意保持Word文档的原有格式和样式