@

一、前言

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