poi-tl 是一个基于 Apache POI 的Word模板引擎，也是一个免费开源的 Java 库，用于简化和加速基于Word模板生成文档的过程,可以非常方便的加入到项目中。
它支持文本、图片、表格和列表等标签替换，提供友好的API。相比其他模板引擎，poi-tl具有更好的样式保留和易用性,使用过程中只需要设置模板、构建好数据，即可以方便地填充数据并输出到文件。这种方式不仅提高了开发效率，还保证了输出文件的一致性和格式美观性。
○ 优势
| 方案 | 移植性 | 功能性 | 易用性 |
|---|---|---|---|
| Poi-tl | Java跨平台 | Word模板引擎，基于Apache POI，提供更友好的API | 低代码，准备文档模板和数据即可 |
| Apache POI | Java跨平台 | Apache项目，封装了常见的文档操作，也可以操作底层XML结构 | 文档不全，可以参考文档地址：https://deepoove.com/poi-tl/apache-poi-guide.html |
| Freemarker | XML跨平台 | 仅支持文本，很大的局限性 | 不推荐，XML结构的代码几乎无法维护 |
| OpenOffice | 部署OpenOffice，移植性较差 | - | 需要了解OpenOffice的API |
| HTML浏览器导出 | 依赖浏览器的实现，移植性较差 | HTML不能很好的兼容Word的格式，样式糟糕 | - |
| Jacob、winlib | Windows平台 | - | 复杂，完全不推荐使用 |
○ 主要功能点
| Word模板引擎功能 | 描述 |
|---|---|
| 文本 | 将标签渲染为文本 |
| 图片 | 将标签渲染为图片 |
| 表格 | 将标签渲染为表格 |
| 列表 | 将标签渲染为列表 |
| 图表 | 条形图（3D条形图）、柱形图（3D柱形图）、面积图（3D面积图）、折线图（3D折线图）、雷达图、饼图（3D饼图）、散点图等图表渲染 |
| If Condition判断 | 根据条件隐藏或者显示某些文档内容（包括文本、段落、图片、表格、列表、图表等） |
| Foreach Loop循环 | 根据集合循环某些文档内容（包括文本、段落、图片、表格、列表、图表等） |
| Loop表格行 | 循环复制渲染表格的某一行 |
| Loop表格列 | 循环复制渲染表格的某一列 |
| Loop有序列表 | 支持有序列表的循环，同时支持多级列表 |
| Highlight代码高亮 | word中代码块高亮展示，支持26种语言和上百种着色样式 |
| Markdown | 将Markdown渲染为word文档 |
| Word批注 | 完整的批注功能，创建批注、修改批注等 |
| Word附件 | Word中插入附件 |
| SDT内容控件 | 内容控件内标签支持 |
| Textbox文本框 | 文本框内标签支持 |
| 图片替换 | 将原有图片替换成另一张图片 |
| 书签、锚点、超链接 | 支持设置书签，文档内锚点和超链接功能 |
| Expression Language | 完全支持SpringEL表达式，可以扩展更多的表达式：OGNL, MVEL… |
| 样式 | 模板即样式，同时代码也可以设置样式 |
| 模板嵌套 | 模板包含子模板，子模板再包含子模板 |
| 合并 | Word合并Merge，也可以在指定位置进行合并 |
| 用户自定义函数(插件) | 插件化设计，在文档任何位置执行函数 |
○ 快速开始
- 引入依赖
<dependency><groupId>com.deepoove</groupId><artifactId>poi-tl</artifactId><version>1.12.2</version>
</dependency>
- 文本输出案例
1.创建一个新的文档 template.docx，其中包含内容 {{title}}
2.TDO 模式：模板 + 数据模型 = 输出
// 核心 API 设计简洁，只需要一行代码
XWPFTemplate.compile("template.docx").render(new HashMap<String, Object>(){{put("title", "poi-tl 模板引擎");
}}).writeToFile("out_template.docx");3. 准备数据
put("name", "刘亦菲");
put("thing", "chocolates");4. 模板内容：
{{name}} 总说生活就像一盒 {{thing}}。5. 输出：
刘亦菲 总说生活就像一盒 chocolates。
- 图片输出案例
图片标签以 @ 开头，例如：
{{@logo}} 会在数据模型中查找键名为 logo 的值，然后用图片替换这个标签。
图片标签的数据可以是简单的 URL 或路径字符串，也可以是一个包含图像宽度和高度的结构。1. 数据：
put("watermelon", "assets/watermelon.png");
put("watermelon", "http://x/lemon.png");
put("lemon", Pictures.ofLocal("sob.jpeg", PictureType.JPEG).size(24, 24).create());2. 模板：
水果 Logo：
watermelon {{@watermelon}}
lemon {{@lemon}}
banana {{@banana}}3. 输出：
水果 Logo：
watermelon 🍉
lemon 🍋
banana 🍌
- 表格输出案例
表格标签以 # 开头，如
{{#table}}，它会渲染成一个具有 N 行和 N 列的 Word 表格。N 的值取决于
table 标签中的数据。1. 代码
put("table", Tables.of(new String[][] {new String[] { "歌曲名称", "艺术家" }}).border(BorderStyle.DEFAULT).create());2. 模板
{{#table}}- 输出：
更多使用，参见官方文档。
仓库地址：
https://gitcode.com/gh_mirrors/po/poi-tl/overview
文档地址：
https://deepoove.com/poi-tl/#_why_poi_tl
也可参考：文章合集，有更多详细使用案例。