@

• 一、前言
  • 1、什么是poi-tl
  • 2、官方資訊
    • 2.1 原始碼倉庫
    • 2.2 中文檔案
    • 2.3 開源協議
  • 3、poi-tl的優勢
    • 3.1 poi-tl和其他模板引擎的對比
    • 3.2 poi-tl Word模板引擎支持的功能
• 二、基本的使用配置
• 1、引入依賴
  • • 1.1 Maven
    • 1.2 Gradle
  • 2、配置
    • 2.1 新建配置
  • 2.2 標簽前后綴替換
    • 2.3 加載模板
    • 2.4 填充資料
    • 2.5 輸出檔案
• 三、各類模板標簽替換和填充
  • 1 文本
    • 1.1 文本的標簽如下
    • 1.2 支持資料型別
    • 1.3 文本資料填充方式如下
  • 2 圖片
    • 2.1 圖片的標簽如下：
    • 2.2 支持資料型別
    • 2.3 圖片資料填充方式如下
  • 3 表格
    • 3.1 表格的標簽如下：
    • 3.2 支持資料型別
    • 3.3 表格資料填充方式如下
  • 4、串列
    • 4.1 串列的標簽如下：
    • 4.2 支持資料型別
    • 4.3 串列資料填充方式如下
• 四、驗證
  • 1、準備模板
  • 2、準備測驗代碼
  • 3、生成效果

一、前言

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 = https://www.cnblogs.com/fhey/archive/2023/07/11/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 = https://www.cnblogs.com/fhey/archive/2023/07/11/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、生成效果

標籤：其他

上一篇：淺析synchronized鎖升級的原理與實作

下一篇：返回列表