、前言

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和其他模板引擎的對比

下面表格是官方文檔中提供的與其他模板引擎的對比

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

二、基本的使用配置

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 response
OutputStream 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", "http://deepoove.com"));
put("anchor", new HyperlinkTextRenderData("anchortxt", "anchor:appendix1"));

除了new操作符，還提供了更加優雅的工廠 Texts 和鏈式調用的方式輕松構建文本模型。

鏈式代碼示例

put("author", Texts.of("Sayi").color("000000").create());
put("link", Texts.of("website").link("http://deepoove.com").create());
put("anchor", Texts.of("anchortxt").anchor("appendix1").create());

2 圖片

2.1 圖片的標簽如下：

圖片標簽以@開始：{{@var}}

2.2 支持數據類型

• String ：圖片url或者本地路徑，默認使用圖片自身尺寸
• PictureRenderData
• ByteArrayPictureRenderData
• FilePictureRenderData
• UrlPictureRenderData

2.3 圖片數據填充方式如下

// 指定圖片路徑
put("image", "logo.png");
// svg圖片
put("svg", "https://img.shields.io/badge/jdk-1.6%2B-orange.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("http://deepoove.com/images/icecream.png")
  .size(100, 100).create());

// java圖片
put("buffered", Pictures.ofBufferedImage(bufferImage, PictureType.PNG)
  .size(100, 100).create());

3 表格

3.1 表格的標簽如下：

表格標簽以#開始：{{#var}}

3.2 支持數據類型

• TableRenderData

3.3 表格數據填充方式如下

1. 基礎表格示例

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

2. 表格樣式示例

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

3. 表格合并示例

// 合并第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>
• NumberingRenderData

4.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、生成效果

什么是poi-tl

FreeMarker或Velocity基于文本模板和數據生成新的html頁面或配置文件。poi-tl是一個基于Word模板和數據生成新文檔的Word模板引擎。

Word模板樣式豐富。Poi-tl將在生成的文檔中完美地保留模板中的樣式。您還可以設置標簽的樣式。標簽的樣式將應用于替換的文本，因此您可以專注于模板設計。

poi-tl是一個“無邏輯”的模板引擎。沒有復雜的控制結構和變量賦值，只有標簽，有些標簽可以用文字、圖片、表格等代替。，一些標簽會隱藏某些文檔內容，而另一些標簽會循環一系列文檔內容。

poi-tl支持自定義函數(插件)，函數可以在Word模板的任何地方執行，在文檔的任何地方做任何事情是poi-tl的目標。

2 Tags

2.1 文本

文本標簽{{var}}

2.2 圖片

圖片標簽以@開始：{{@var}}

2.3 表格

表格標簽以#開始：{{#var}}

2.4 列表

列表標簽以*開始：{{*var}}

2.5 區塊對

區塊對由前后兩個標簽組成，開始標簽以?標識，結束標簽以/標識：{{?sections}}{{/sections}}

2.6 動態表格

注意，{{}}是官方指定的格式，也可以自定義。

[ ] 是可替換的屬性 可以是多個。