Word模板引擎poi-tl（poi template language）使用入门指南
什么是poi-tl
poi-tl（poi template language）是Word模板引擎，使用模板和数据创建很棒的Word文档
poi-tl是一个基于Apache POI的Word模板引擎，也是一个免费开源的Java类库，可以非常方便的集成到项目中，并使用它已经封装好的功能。
为什么选择poi-tl?
| 方案 | 移植性 | 功能性 | 易用性 |
|---|---|---|---|
| Poi-tl | Java跨平台 | Word模板引擎，基于Apache POI，提供更友好的API | 低代码，准备文档模板和数据即可 |
| Apache POI | Java跨平台 | Apache项目，封装了常见的文档操作，也可以操作底层XML结构 | 文档不全，这里有一个教程：Apache POI Word快速入门 |
| 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.deepoovegroupId>
<artifactId>poi-tlartifactId>
<version>1.12.2version>
dependency>
代码示例
源码参见 JUnit XWPFTemplateTest
Word模板参见：template.docx
package com.baomidou.mybatisplus.samples.wrapper;
import java.util.HashMap;
import java.util.Map;
import org.junit.jupiter.api.Test;
import com.deepoove.poi.XWPFTemplate;
import com.deepoove.poi.data.Charts;
import com.deepoove.poi.data.Numberings;
import com.deepoove.poi.data.Pictures;
import com.deepoove.poi.data.RowRenderData;
import com.deepoove.poi.data.Rows;
import com.deepoove.poi.data.TableRenderData;
import com.deepoove.poi.data.Tables;
import com.deepoove.poi.data.Texts;
/**
* @author Sayi
*/
public class XWPFTemplateTest {
@Test
public void testRenderTemplate() throws Exception {
Map<String, Object> datas = new HashMap<String, Object>();
// create table
RowRenderData header = Rows.of("Word处理方案", "是否跨平台", "易用性")
.textColor("FFFFFF")
.bgColor("ff9800")
.center()
.rowHeight(2.5f)
.create();
RowRenderData row0 = Rows.create("Poi-tl", "纯Java组件，跨平台", "简单：模板引擎功能，并对POI进行了一些封装");
RowRenderData row1 = Rows.create("Apache Poi", "纯Java组件，跨平台", "简单，缺少一些功能的封装");
RowRenderData row2 = Rows.create("Freemarker", "XML操作，跨平台", "复杂，需要理解XML结构");
RowRenderData row3 = Rows.create("OpenOffice", "需要安装OpenOffice软件", "复杂，需要了解OpenOffice的API");
TableRenderData table = Tables.create(header, row0, row1, row2, row3);
// text
datas.put("header", "定义文档的header");
datas.put("name", "poi-tl使用示例");
datas.put("word", "word模板引擎");
datas.put("time", "2024-10-16");
datas.put("what", "Java Word模板引擎： Minimal Microsoft word(docx) templating with {{template}} in Java.");
datas.put("author", Texts.of("cloudcoder").color("000000").create());
// hyperlink
datas.put("introduce", Texts.of("Word模板引擎poi-tl（poi template language）使用指南").link("https://cloudcoder.blog.csdn.net/article/details/142970288").create());
// picture
datas.put("portrait", Pictures.ofLocal("src/test/resources/sayi.png").size(60, 60).create());
// table
datas.put("solution_compare", table);
// numbering
datas.put("feature",
Numberings.create("Plug-in grammar, add new grammar by yourself",
"Supports word text, local pictures, web pictures, table, list, header, footer...",
"Templates, not just templates, but also style templates"));
// chart
datas.put("chart",
Charts.ofMultiSeries("易用性", new String[] {"代码量", "维护量"})
.addSeries("poi-tl", new Double[] {10.0, 5.0})
.addSeries("freemark", new Double[] {90.0, 70.0})
.create());
XWPFTemplate.compile("src/test/resources/template.docx")
.render(datas)
.writeToFile("target/out_template.docx");
}
}
参考资料
- poi-tl document
- GitHub 源码