一、前言1、什么是poi-tl

poi-tl是一个基于Apache POI的Word模板引擎，也是一个免费开源的Java类库。同类型的FreeMarker或Velocity基于文本模板和数据生成新的html页面或配置文件。而poi tl是一个基于Word模板和数据生成新文档的Word模板引擎。

Word模板具有丰富的样式。Poi-tl将在生成的文档中完美地保留模板中的样式。也可以设置标记的样式。标记的样式将应用于替换的文本，因此您可以专注于模板设计。

poi-tl是一个“无逻辑”模板引擎。没有复杂的控制结构和变量分配，只有标签，有些标签可以用文本、图片、表格等代替，有些标签会隐藏某些文档内容，而另一些标签会循环一系列文档内容。

像变量赋值或条件语句这样的“强大”构造可以很容易地在模板系统中专门修改应用程序的外观。。。然而，以分离为代价，将模板本身变成应用程序逻辑的一部分。

poi-tl支持自定义函数（插件），函数可以在Word模板的任何地方执行，在文档的任何地方做任何事情都是poi-tl的目标。

2、官方信息2.1 源码仓库

GitHub - Sayi/poi-tl: Generate awesome word(docx) with template

2.2 中文文档

Poi-tl Documentation (deepoove.com)

2.3 开源协议

Apache License 2.0

3、poi-tl的优势3.1 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平台

-

复杂，完全不推荐使用

3.2 poi-tl Word模板引擎支持的功能

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，也可以在指定位置进行合并

用户自定义函数(插件)

插件化设计，在文档任何位置执行函数

二、基本的使用配置1、引入依赖1.1 Maven

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

1.2 Gradle

implementation 'com.deepoove:poi-tl:1.12.1'

2、配置2.1 新建配置

ConfigureBuilder builder = Configure.builder();

2.2 标签前后缀替换

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

当然如果你更偏爱freemarker ${} 的方式，也可以添加如下配置修改标签的前后缀配置：

builder.buildGramer("${", "}");

2.3 加载模板

XWPFTemplate template = XWPFTemplate.compile("template.docx", builder.buid());

poi-tl加载使用XWPFTemplate.compile方法来加载模板，支持模板以绝对路径（String），File、InputStream、XWPFDocument四种格式传入。

2.4 填充数据

poi-tl数据类似于哈希或者字典，可以是Map结构（key是标签名称）：

Map<String, Object> data = new HashMap<>();data.put("name", "Sayi");data.put("start_time", "2019-08-04");template.render(dataMap);

2.5 输出文件

poi-tl以流的方式进行输出：

template.write(OutputStream stream);

可以写到任意输出流中，比如文件流：

template.write(new FileOutputStream("output.docx"));

如网络流：

response.setContentType("application/octet-stream");response.setHeader("Content-disposition","attachment;filename=\""+"out_template.docx"+"\"");// HttpServletResponse responseOutputStream out = response.getOutputStream();BufferedOutputStream bos = new BufferedOutputStream(out);template.write(bos);bos.flush();out.flush();PoitlIOUtils.closeQuietlyMulti(template, bos, out);

三、各类模板标签替换和填充1 文本1.1 文本的标签如下

{{var}}

1.2 支持数据类型String ：文本TextRenderData ：有样式的文本HyperlinkTextRenderData ：超链接和锚点文本Object ：调用 toString() 方法转化为文本1.3 文本数据填充方式如下

代码示例

put("name", "Sayi");put("author", new TextRenderData("000000", "Sayi"));put("link", new HyperlinkTextRenderData("website", ";));put("anchor", new HyperlinkTextRenderData("anchortxt", "anchor:appendix1"));

除了new操作符，还提供了更加优雅的工厂 Texts 和链式调用的方式轻松构建文本模型。

链式代码示例

put("author", Texts.of("Sayi").color("000000").create());put("link", Texts.of("website").link(";).create());put("anchor", Texts.of("anchortxt").anchor("appendix1").create());

2 图片2.1 图片的标签如下：

图片标签以@开始：{{@var}}

2.2 支持数据类型String ：图片url或者本地路径，默认使用图片自身尺寸PictureRenderDataByteArrayPictureRenderDataFilePictureRenderDataUrlPictureRenderData2.3 图片数据填充方式如下

// 指定图片路径put("image", "logo.png");// svg图片put("svg", ";);// 设置图片宽高put("image1", Pictures.ofLocal("logo.png").size(120, 120).create());// 图片流put("streamImg", Pictures.ofStream(new FileInputStream("logo.jpeg"), PictureType.JPEG)  .size(100, 120).create());// 网络图片(注意网络耗时对系统可能的性能影响)put("urlImg", Pictures.ofUrl(";)  .size(100, 100).create());// java图片put("buffered", Pictures.ofBufferedImage(bufferImage, PictureType.PNG)  .size(100, 100).create());

3 表格3.1 表格的标签如下：

表格标签以#开始：{{#var}}

3.2 支持数据类型TableRenderData3.3 表格数据填充方式如下基础表格示例

// 一个2行2列的表格put("table0", Tables.of(new String[][] {                new String[] { "00", "01" },                new String[] { "10", "11" }            }).border(BorderStyle.DEFAULT).create());

表格样式示例

// 第0行居中且背景为蓝色的表格RowRenderData row0 = Rows.of("姓名", "学历").textColor("FFFFFF")      .bgColor("4472C4").center().create();RowRenderData row1 = Rows.create("李四", "博士");put("table1", Tables.create(row0, row1));

表格合并示例

// 合并第1行所有单元格的表格RowRenderData row0 = Rows.of("列0", "列1", "列2").center().bgColor("4472C4").create();RowRenderData row1 = Rows.create("没有数据", null, null);MergeCellRule rule = MergeCellRule.builder().map(Grid.of(1, 0), Grid.of(1, 2)).build();put("table3", Tables.of(row0, row1).mergeRule(rule).create());

4、列表4.1 列表的标签如下：

列表标签以*开始：{{*var}}

4.2 支持数据类型List<String>NumberingRenderData4.3 列表数据填充方式如下

put("list", Numberings.create("Plug-in grammar",                    "Supports word text, pictures, table...",                    "Not just templates"));

四、验证1、准备模板

首先我们建立一个word文件，在word文件里填充一下内容。

2、准备测试代码

import com.deepoove.poi.XWPFTemplate;import com.deepoove.poi.config.Configure;import com.deepoove.poi.config.ConfigureBuilder;import com.deepoove.poi.data.*;import dto.Qiankuan;import java.io.FileInputStream;import java.io.IOException;import java.nio.file.Files;import java.nio.file.Paths;import java.time.LocalDate;import java.util.*;public class PoitlTest {    public static void main(String[] args) throws IOException {        ConfigureBuilder builder = Configure.builder();        //获取模板的文件流        FileInputStream fileInputStream = new FileInputStream("D:\\文章\\word生成\\poi-tl\\qiantiao.docx");        HashMap<String, Object> dataMap = new HashMap<>();        //添加文本        LocalDate currentDate = LocalDate.now();        LocalDate endDate = currentDate.plusYears(1L);        dataMap.put("debtor", "陈有楚");        dataMap.put("nowYear", String.valueOf(currentDate.getYear()));        dataMap.put("nowMonth", String.valueOf(currentDate.getMonthValue()));        dataMap.put("nowDay", String.valueOf(currentDate.getDayOfMonth()));        //验证换行的情况        dataMap.put("arrears", "\n一顿老魏，\n贵州大黄牛，\nv我50");        dataMap.put("endYear", String.valueOf(endDate.getYear()));        dataMap.put("endMonth", String.valueOf(endDate.getMonthValue()));        dataMap.put("endDay", String.valueOf(endDate.getDayOfMonth()));        //添加列表        List<String> list = Arrays.asList("阿大", "阿二", "阿三");        Numberings.NumberingBuilder numberingBuilder = Numberings.of(NumberingFormat.DECIMAL);        for (String s : list) {            numberingBuilder.addItem(s);        }        dataMap.put("witness", numberingBuilder.create());        //添加图片，考虑到实际生产环境图片大都都从文件服务获取，所以这里用图片流做例子        PictureRenderData pictureRenderData = Pictures.ofStream(Files.newInputStream(Paths.get("D:\\picture\\其他\\24-05-23-142418.png")), PictureType.JPEG)                .size(300, 220).create();        dataMap.put("image1", pictureRenderData);        List<Qiankuan> qiankuanList = getQiankuanList();        //添加表格        //填充表头，表格的第一行        RowRenderData row0 = Rows.of("拖欠物品", "拖欠次数", "偿还期限").center().bgColor("4472C4").create();        Tables.TableBuilder tableBuilder = Tables.of(row0);        //填充表格内容        for (Qiankuan qiankuan : qiankuanList) {            RowRenderData row = Rows.create(qiankuan.getName(), String.valueOf(qiankuan.getCount()), qiankuan.getQixian());            tableBuilder.addRow(row);        }        //MergeCellRule rule = MergeCellRule.builder().map(MergeCellRule.Grid.of(1, 0), MergeCellRule.Grid.of(1, 2)).build();        //tableBuilder.mergeRule(rule);        dataMap.put("table1", tableBuilder.create());        ChartMultiSeriesRenderData chart = Charts                .ofMultiSeries("ChartTitle", new String[] { "中文", "English" })                .addSeries("countries", new Double[] { 15.0, 6.0 })                .addSeries("speakers", new Double[] { 223.0, 119.0 })                .create();        dataMap.put("barChart", chart);        XWPFTemplate template = XWPFTemplate.compile(fileInputStream, builder.build())                .render(dataMap);        template.writeAndClose(Files.newOutputStream(Paths.get("D:\\test\\qiantiao-poitl.docx")));        System.out.println("success");    }    static List<Qiankuan> getQiankuanList() {        List<Qiankuan> list = new ArrayList<>();        Qiankuan q1 = new Qiankuan();        q1.setName("一顿老魏");        q1.setCount(1);        q1.setQixian("三月内");        list.add(q1);        Qiankuan q2 = new Qiankuan();        q2.setName("一顿大黄牛");        q2.setCount(1);        q2.setQixian("半年内");        list.add(q2);        Qiankuan q3 = new Qiankuan();        q3.setName("特一特");        q3.setCount(3);        q3.setQixian("一周内");        list.add(q3);        Qiankuan q4 = new Qiankuan();        q4.setName("v我50");        q4.setCount(5);        q4.setQixian("一周内");        list.add(q4);        return list;    }}

3、生成效果