poi-tl(poi-template-language)

https://github.com/Sayi/poi-tl

Word 模板引擎，基于Apache POI - the Java API for Microsoft Documents。

What is poi-tl

FreeMarker、Velocity基于文本模板和数据生成新的HTML页面、配置文件等，poi-tl是Word模板引擎，基于Microsoft Word模板和数据生成新的文档。

Word模板拥有丰富的样式，poi-tl在生成的文档中会完美保留模板中的样式，还可以为标签设置样式，标签的样式会被应用到替换后的文本上，因此你可以专注于模板设计。

poi-tl是一种 "logic-less" 模板引擎，没有复杂的控制结构和变量赋值，只有标签，一些标签可以被替换为文本、图片、表格等，一些标签会隐藏某些文档内容，而另一些标签则会将一系列文档内容循环渲染。

"Powerful" constructs like variable assignment or conditional statements make it easy to modify the look of an application within the template system exclusively... however, at the cost of separation, turning the templates themselves into part of the application logic.

《Google CTemplate》

poi-tl支持自定义渲染函数(插件)，函数可以在Word模板的任何位置执行，在文档的任何地方做任何事情(Do Anything Anywhere)是poi-tl的星辰大海。

Maven

<dependency>
  <groupId>com.deepoove</groupId>
  <artifactId>poi-tl</artifactId>
  <version>1.8.2</version>
</dependency>

2分钟快速入门

从一个超级简单的例子开始：把{{title}}替换成"poi-tl 模板引擎"。

  1. 新建文档模板template.docx，包含标签{{title}}
  2. TDO模式：Template + data-model = output
//核心API采用了极简设计，只需要一行代码
XWPFTemplate.compile("template.docx").render(new HashMap<String, Object>(){{
        put("title", "poi-tl 模板引擎");
}}).writeToFile("out_template.docx");

打开out_template.docx文档吧，一切如你所愿。

标签

标签由前后两个大括号组成，{{title}}是标签，{{?title}}也是标签，title是这个标签的名称，?标识了标签类型，接下来我们来看看有哪些标签类型。

文本

文本标签是Word模板中最基本的标签类型，{{name}}会被数据模型中key为name的值替换，如果找不到默认会清空标签，可以配置是保留还是抛出异常。

文本标签的样式会应用到替换后的文本上，正如下面的例子所示。

数据:

{
  "name": "Mama",
  "thing": "chocolates"
}

Word模板:

{{name}} always said life was like a box of {{thing}}. {{name}} always said life was like a box of {{thing}}.

输出:

Mama always said life was like a box of chocolates. Mama always said life was like a box of chocolates.

图片

图片标签以@开始，如{{@logo}}会在数据中寻找key为logo的值，然后将标签替换成图片。由于Word文档中图片不是由字符串表示(在文本型模板中，比如HTML网页图片是由字符串<img src="" />表示)，所以图片标签对应的数据有一定的结构要求，这些结构都会有相应的Java类对应。

数据:

{
  "watermelon": {
    "path": "assets/watermelon.png"
  },
  "lemon": {
    "path": "http://xxx/lemon.png"
  },
  "banana": {
    "path": "sob.png",
    "width": 24,
    "height": 24
  }
}

Word模板:

Fruit Logo:
watermelon {{@watermelon}}
lemon {{@lemon}}
banana {{@banana}}

输出:

Fruit Logo:
watermelon 🍉
lemon 🍋
banana 🍌

表格

表格标签以#开始，如{{#table}}，它会被渲染成N行N列的Word表格，N的值取决于table标签的值。

数据:

{
  "song": {
    "rows": [
      {
        "cells": [
          {"cellText": {"text": "Song name"}},
          {"cellText": {"text": "artist"}}
        ]
      }
    ],
    "rows": [
      {
        "cells": [
          {"cellText": {"text": "Memories"}},
          {"cellText": {"text": "Maroon 5"}}
        ],
        "rowStyle":{
          "backgroundColor":"f6f8fa"
        }
      }
    ]
  }
}

Word模板:

{{#song}}

输出:

Song name

Artist

Memories

Maroon 5

列表

列表标签对应Word的符号列表或者编号列表，以*开始，如{{*number}}。

数据:

{
  "feature": {
    "numFmt": {
      "decimal": "%1)"
    },
    "numbers": [
      {
        "text": "Plug-in function, define your own function"
      },
      {
        "text": "Supports text, pictures, table, list, if, foreach..."
      },
      {
        "text": "Templates, not just templates, but also style templates"
      }
    ]
  }
}

Word模板:

{{*feature}}

输出:

1) Plug-in function, define your own function
2) Supports text, pictures, table, list, if, foreach...
3) Templates, not just templates, but also style templates

区块对

区块对由前后两个标签组成，开始标签以?标识，结束标签以/标识，如{{?sections}}作为sections区块的起始标签，{{/sections}}为结束标签，sections是这个区块对的名称。

区块对在处理一系列文档元素的时候非常有用，位于区块对中的文档元素(文本、图片、表格等)可以被渲染零次，一次或N次，这取决于区块对的取值。

False或空集合

如果区块对的值是null、false或者空的集合，位于区块中的所有文档元素将不会显示，类似于if语句的条件为false。

数据:

{
  "announce": false
}

Word模板:

Made it,Ma!{{?announce}}Top of the world!{{/announce}}
Made it,Ma!
{{?announce}}
Top of the world!🎋
{{/announce}}

输出:

Made it,Ma!
Made it,Ma!

非False且不是集合

如果区块对的值不为null、false，且不是集合，位于区块中的所有文档元素会被渲染一次，if语句的条件为true。

数据:

{
  "person": { "name": "Sayi" }
}

Word模板:

{{?person}}
  Hi {{name}}!
{{/person}}

输出:

Hi Sayi!

非空集合

如果区块对的值是一个非空集合，区块中的文档元素会被迭代渲染一次或者N次，这取决于集合的大小，类似于foreach语法。

数据:

{
  "songs": [
    { "name": "Memories" },
    { "name": "Sugar" },
    { "name": "Last Dance(伍佰)" }
  ]
}

Word模板:

{{?songs}}
{{name}}
{{/songs}}

输出:

Memories
Sugar
Last Dance(伍佰)

在循环中可以通过一个特殊的标签{{=#this}}直接引用当前迭代的对象。

数据:

{
  "produces": [
    "application/json",
    "application/xml"
  ]
}

Word模板:

{{?produces}}
{{=#this}}
{{/produces}}

输出:

application/json
application/xml

嵌套

嵌套是在Word模板中引入另一个Word模板，可以理解为import、include或者word文档合并，以+标识，如{{+nested}}。

数据:

{
  "nested": {
    "file": "template/sub.docx",
    "dataModels": [
      {
        "addr": "Hangzhou,China"
      },
      {
        "addr": "Shanghai,China"
      }
    ]
  }
}

给定两个WordWord模板:

main.docx:
Hello, World
{{+nested}}

template/sub.docx:
Address: {{addr}}

输出:

Hello, World
Address: Hangzhou,China
Address: Shanghai,China

详细文档与示例

中文文档Documentation 1.9.0-beta文档

  • 基础(图片、文本、表格、列表)示例：软件说明文档
  • 表格示例：付款通知书
  • 循环和图表示例：野生动物现状
  • 文本框示例：证书奖状
  • Example：个人简历创作
  • Example：Swagger文档