OpenSource - Apache POI 的 Word 模板引擎 poi-tl

文章目录


概述

该项目是基于 Apache POI 的 Word 模板引擎,可以动态生成 Word 文档。它提供了友好的 API,支持文本、图片、表格、条件渲染、图表等多种内容的渲染,适用于批量生成合同、报告、通知、证书等场景


地址

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

https://deepoove.com/poi-tl/


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,也可以在指定位置进行合并
用户自定义函数(插件) 插件化设计,在文档任何位置执行函数

Getting Started

前提

JDK1.8+

Apache POI5.2.2+

Maven

xml 复制代码
<dependency>
  <groupId>com.deepoove</groupId>
  <artifactId>poi-tl</artifactId>
  <version>1.12.2</version>
</dependency>

Gradle

复制代码
implementation 'com.deepoove:poi-tl:1.12.2'

2分钟入门

新建Word文档template.docx,包含标签 {{title}}

xml 复制代码
template.docx
{{title}}

代码示例

java 复制代码
XWPFTemplate template = XWPFTemplate.compile("template.docx").render(
  new HashMap<String, Object>(){{
    put("title", "Hi, poi-tl Word模板引擎");
}});   // 
template.writeAndClose(new FileOutputStream("output.docx")); 
  • compile 编译模板
  • render 渲染数据
  • write 输出到流
  • TDO模式:Template + data-model = output
java 复制代码
output.docx
Hi, poi-tl Word模板引擎

Template:模板

模板是Docx格式的Word文档,你可以使用Microsoft office、WPS Office、Pages等任何你喜欢的软件制作模板,也可以使用Apache POI代码来生成模板。

所有的标签都是以{{开头,以}}结尾,标签可以出现在任何位置,包括页眉,页脚,表格内部,文本框等,表格布局可以设计出很多优秀专业的文档,推荐使用表格布局。

poi-tl模板遵循"所见即所得"的设计,模板和标签的样式会被完全保留。

Data-model:数据

数据类似于哈希或者字典,可以是Map结构(key是标签名称):

java 复制代码
Map<String, Object> data = new HashMap<>();
data.put("name", "Sayi");
data.put("start_time", "2019-08-04");

可以是对象(属性名是标签名称):

java 复制代码
public class Data {
  private String name;
  private String startTime;
  private Author author;
}

数据可以是树结构,每级之间用点来分隔开,比如{{author.name}}标签对应的数据是author对象的name属性值。

FreeMarker、Velocity文本模板中可以通过三个标签设置图片路径、宽和高:<img src="{``{path}}" width="{``{width}}" height="{``{height}}">, 但是Word模板不是由简单的文本表示,所以在渲染图片、表格等元素时提供了数据模型,它们都实现了接口 RenderData ,比如图片数据模型 PictureRenderData 包含图片路径、宽、高三个属性。


Output:输出

以流的方式进行输出:

java 复制代码
template.write(OutputStream stream);

比如文件流:

java 复制代码
template.write(new FileOutputStream("output.docx"));

比如网络流:

java 复制代码
response.setContentType("application/octet-stream");
response.setHeader("Content-disposition","attachment;filename=\""+"out_template.docx"+"\"");

// HttpServletResponse response
OutputStream out = response.getOutputStream();
BufferedOutputStream bos = new BufferedOutputStream(out);
template.write(bos);
bos.flush();
out.flush();

最后不要忘记关闭这些流。

java 复制代码
PoitlIOUtils.closeQuietlyMulti(template, bos, out);
相关推荐
草梅友仁4 小时前
草梅 Auth 1.1.0 发布与最新动态 | 2025 年第 30 周草梅周报
开源·github·ai编程
自由鬼9 小时前
Apache HTTP Server 2.4.49 的目录遍历漏洞CVE-2021-41773
网络协议·http·apache
lang201509289 小时前
Apache Ignite 索引(Indexes)定义和使用
apache·ignite
百川9 小时前
Apache文件解析漏洞
web安全·apache
Xi_Xu12 小时前
Xget:下一代开源资源获取加速引擎,让你的文件下载、储存库克隆和镜像拉取快如闪电
开源·github
不摸鱼13 小时前
创业找不到方向?不妨从行业卧底开始 | 不摸鱼的独立开发者日报(第66期)
人工智能·开源·资讯
未来智慧谷13 小时前
阿里开源Qwen3-Coder,编程大模型进入高效时代
开源·qwen3-coder
DisonTangor13 小时前
商汤InternLM发布最先进的开源多模态推理模型——Intern-S1
人工智能·深度学习·开源·aigc
胖胖胖胖胖虎17 小时前
Apache Ranger 权限管理
apache
DisonTangor17 小时前
Mistral AI开源 Magistral-Small-2507
人工智能·语言模型·开源·aigc