poi-tl—一个超级好用开源的Word模板引擎

Posted 2021-07-17 李子捌

1、poi-tl是什么

poi-tl是一个基于Apache POI的Word模板引擎，同时它也是一个免费开源（github地址）的Java类库，给Java程序员带来了word处理上的便捷。

2、官方介绍

在文档的任何地方做任何事情（Do Anything Anywhere）是poi-tl的星辰大海。

​
2.1 poi-tl与其他word模板引擎的对比

方案	移植性	功能性	易用性
Poi-tl	Java跨平台	Word模板引擎	基于Apache POI，更友好的API
Apache POI	Java跨平台	Apache项目，不仅封装了易用的文档API(文本、图片、表格、页眉、页脚、图表等)，也可以在底层直接操作XML结构	文档不全，这里有一个教程：Apache POI Word快速入门
Freemarker	XML跨平台	仅支持文本，很大的局限性	不推荐，需要维护XML结构，代码后期不可维护
OpenOffice	部署OpenOffice，移植性较差	-	需要了解OpenOffice的API
html浏览器导出	依赖浏览器的实现，移植性较差	HTML不能很好的兼容Word的格式	-
Jacob、winlib	Windows平台	-	复杂，完全不推荐使用

​

2.2 poi-tl的编码模式

TDO模式： Template + data-model = output

2.2.1 Template—模板
模板即Docx格式的Word文档
​

2.2.2 Data-model—数据
数据即模板中需要替换的数据结构，类似哈希或者字典，常用Map结构，其中key即需要替换的标签
​

2.2.3 Output—输出
输出即最终文档的流产生，可以是文件流或网络流等
​

​

3、软件要求

• Apache POI 4.1.2
• jdk 1.8+

maven依赖

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

4、标签

4.1 文本

标签
{{var}}

数据模型

1. String：文本
2. TextRenderData：有样式的文本
3. HyperlinkTextRenderData ：超链接和锚点文本
4. Object：调用 toString() 方法转化为文本

测试模板

测试代码

package com.lizba.poi;

import com.deepoove.poi.XWPFTemplate;
import com.deepoove.poi.data.Texts;

import java.io.FileOutputStream;
import java.io.IOException;
import java.util.HashMap;

/**
 * <p>
 *		文本测试
 * </p>
 *
 * @Author: Liziba
 * @Date: 2021/6/24 21:49
 */
public class DocTest {

    public static void main(String[] args) throws IOException {
        String filePath = "D:\\\\poi-tl\\\\textTest.docx";
        String targetPath =  "D:\\\\poi-tl\\\\textTestTarget.docx";
        XWPFTemplate template = XWPFTemplate.compile(filePath).render(
                new HashMap<String, Object>() {
                    {
                        put("name", "测试");
                        put("author", Texts.of("Liziba").color("000000").create());
                        put("link", Texts.of("百度").link("https://baidu.com").create());
                        put("anchor", Texts.of("anchortxt").anchor("appendix1").create());
                    }
                });
        template.writeAndClose(new FileOutputStream(targetPath));
    }

}

测试结果

4.2 图片
​

标签
{{@var}}
​

数据模型

1. String：图片url或者本地路径。默认使用图片自身尺寸
2. PictureRenderData

测试模板

测试代码

package com.lizba.poi;

import com.deepoove.poi.XWPFTemplate;
import com.deepoove.poi.data.PictureType;
import com.deepoove.poi.data.Pictures;
import com.deepoove.poi.data.Texts;

import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.util.HashMap;

/**
 * <p>
 *		图片测试
 * </p>
 *
 * @Author: Liziba
 * @Date: 2021/6/24 21:49
 */
public class PictureTest {

    public static void main(String[] args) throws IOException {
        String filePath = "D:\\\\poi-tl\\\\pictureTest.docx";
        String targetPath =  "D:\\\\poi-tl\\\\pictureTest2.docx";
        String picPath =  "D:\\\\poi-tl\\\\pic.jpg";
        XWPFTemplate template = XWPFTemplate.compile(filePath).render(
                new HashMap<String, Object>() {
                    {
                        // 方法一、图片路径（原大小）
                        put("picture", picPath);
                        // 方法二、指定图片大小
                        put("picture", Pictures.ofLocal(picPath).size(420,350).center().create());
                        // 方法三、图片流
                        put("picture", Pictures.ofStream(new FileInputStream(picPath), PictureType.JPEG)
                                .size(420,350).create());
                        // 针对网络图片、SVG图片、Java图片都有处理
                    }
                });
        template.writeAndClose(new FileOutputStream(targetPath));
    }

}

测试结果

4.3 表格
​

标签
{{#var}}
​

数据模型

1. TableRenderData

测试模板

测试代码

package com.lizba.poi;

import com.deepoove.poi.XWPFTemplate;
import com.deepoove.poi.data.*;

import java.io.FileOutputStream;
import java.io.IOException;
import java.util.HashMap;

/**
 * <p>
 * 		列表测试
 * </p>
 *
 * @Author: Liziba
 * @Date: 2021/6/24 21:49
 */
public class TableTest {

    public static void main(String[] args) throws IOException {
        String filePath = "D:\\\\poi-tl\\\\tableTest.docx";
        String targetPath =  "D:\\\\poi-tl\\\\tableTest2.docx";

        // 表头
        RowRenderData tableHead = Rows.of("姓名", "性别", "地址", "微信公众号").center().bgColor("4472c4").create();
        // 第一行
        RowRenderData row1 = Rows.create("张三", "男", "广东深圳", "liziba_98");
        // 第二行
        RowRenderData row2 = Rows.create("李四", "男", "广东深圳", "liziba_98");
        // 合并第一行和第二行的第二列与第三列
        MergeCellRule rule = MergeCellRule.builder().map(MergeCellRule.Grid.of(1, 1), MergeCellRule.Grid.of(2, 1))
                .map(MergeCellRule.Grid.of(1, 2), MergeCellRule.Grid.of(2, 2)).build();

        XWPFTemplate template = XWPFTemplate.compile(filePath).render(
            new HashMap<String, Object>() {
                {
                    put("table", Tables.of(tableHead, row1, row2).mergeRule(rule).center().create());
                }
            });
        template.writeAndClose(new FileOutputStream(targetPath));
    }

}

​

测试结果

4.4 列表、区块对、嵌套
…省略
​

5、总结

开发过程中，我们为了效率和可用性，都不大会考虑重复造轮子，在有成熟工具的时候选择一个合适的工具是一件事半功倍的事情，以上讲述了poi-tl的部分简单功能，看了上述编码方式也是仁者见仁智者见智吧，作者是非常喜欢通过poi-tl来处理word文档。具体其他特性读者可以去poi-tl的官网学习。

官网地址：http://deepoove.com/poi-tl
github地址：https://github.com/Sayi/poi-tl
​