poi-tl:让 Java 生成 Word 文档变得如此简单

二进制驿站——每周精选优质开源项目，帮你少踩坑、多提效

后端生成 Word 文档是常见的工程需求：合同、报告、证书、通知单……

你可能试过这些方案：

• • 用 Apache POI 硬编码创建表格、段落，代码冗长，改样式像改 bug
• • 用 FreeMarker 模板，但只支持纯文本，表格图片根本没法搞
• • 用 OpenOffice 或 Jacob，依赖厚重，跨平台等于做梦

今天介绍一个开源方案：poi-tl。它用 Word 模板 + 数据的模式，让你告别重复代码，专注业务本身。

poi-tl 是什么

poi-tl是基于 Apache POI 的 Word 模板引擎，使用模板和数据创建 Word 文档。

核心理念：“在文档的任何地方做任何事情”。

你可以把它理解为：Word 模板 + 数据模型 = 输出文档。模板由你用 WPS/Office 随意设计，标签占位；数据由 Java 代码传入，渲染后自动填充。

核心特性

• • 文本、图片、表格、列表：基础标签全覆盖
• • 条件判断：根据条件隐藏或显示内容
• • 循环渲染：根据集合循环渲染段落、表格、列表
• • 图表渲染：支持条形图、柱形图、饼图、折线图等
• • 代码高亮：支持 26 种语言和多种主题
• • Markdown 转 Word：一条配置搞定
• • 批注、附件、书签：完整的 Word 功能支持
• • 插件机制：高度可扩展，自定义标签行为

方案对比

快速上手

引入依赖

Maven：

<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}}

第二步：写 Java 代码

XWPFTemplate template = XWPFTemplate.compile("template.docx").render(    new HashMap<String, Object>() {{        put("title", "Hi, poi-tl Word模板引擎");    }});template.writeAndClose(new FileOutputStream("output.docx"));

第三步：打开 output.docx，标签已被渲染。

标签体系

poi-tl 的标签以 {{ 开头、}} 结尾，不同前缀代表不同类型：

代码示例：带图片和表格

// 图片数据put("logo", Pictures.ofLocal("logo.png").size(120, 120).create());// 表格数据RowRenderData row0 = Rows.of("姓名", "学历").textColor("FFFFFF")        .bgColor("4472C4").center().create();RowRenderData row1 = Rows.create("李四", "博士");put("table", Tables.create(row0, row1));

代码示例：循环区块

// 数据put("songs", Arrays.asList(    new HashMap() {{ put("name", "Memories"); }},    new HashMap() {{ put("name", "Sugar"); }},    new HashMap() {{ put("name", "Last Dance"); }}));

模板写法：

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

输出：

MemoriesSugarLast Dance

典型使用场景

• • 合同/协议：模板设计好，动态填充双方信息
• • 通知单/对账单：表格 + 循环，数据驱动生成
• • 证书/奖状：批量生成，替换姓名和日期
• • 报告文档：图表 + 图片，代码即文档
• • API 文档：结合 Swagger 数据模型自动生成

插件生态

poi-tl 提供丰富的插件扩展：

• • LoopRowTableRenderPolicy：循环表格行
• • LoopColumnTableRenderPolicy：循环表格列
• • DynamicTableRenderPolicy：动态表格
• • CommentRenderPolicy：批注功能
• • AttachmentRenderPolicy：插入附件
• • HighlightRenderPolicy：代码高亮
• • MarkdownRenderPolicy：Markdown 转 Word

注意事项

• • 模板必须是 .docx 格式（Office 2007+）
• • 标签可以出现在页眉、页脚、表格内部、文本框等任意位置
• • 循环区块中可使用内置变量：_index、_is_first、_is_last 等
• • 渲染前检查数据模型类型，错误配置会导致标签被清空

最后说两句

• • poi-tl 的价值在于模板与代码分离：设计师用 WPS 做模板，工程师只写数据绑定
• • 插件机制让它几乎可以在文档任意位置做任意操作
• • 如果你的业务涉及批量生成 Word，poi-tl 是目前 Java 生态里最优雅的方案之一

官网与开源地址

• • 官网文档：https://deepoove.com/poi-tl/
• • GitHub 仓库：https://github.com/Sayi/poi-tl