poi-tl是一個基於Apache POI的Word模板引擎，也是一個免費開源的Java類庫。同類型的FreeMarker或Velocity基於文本模板和數據生成新的html頁面或配置文件。而poi tl是一個基於Word模板和數據生成新文檔的Word模板引擎。Word模板具有豐富的樣式。Poi-t... ...
@
目錄一、前言
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 表格數據填充方式如下
- 基礎表格示例
// 一個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>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、生成效果
