# POI-TL 教學 ### 簡介 &nbsp;&nbsp;是一個基於 Apache POI 的開源 Java 函式庫。它簡化了使用範本產生 Word 文件的過程。 poi-tl 庫是一個 Word 範本引擎，可以根據 Word 範本和資料建立新文件。 官方來源：[Poi-tl Documentation ](https://deepoove.com/poi-tl/) --- ### 加入依賴 Poi-TL Maven網址： https://mvnrepository.com/artifact/com.deepoove/poi-tl ``` XML= <dependency> <groupId>com.deepoove</groupId> <artifactId>poi-tl</artifactId> <version>1.12.1</version> </dependency> ``` --- ### 標籤類型介紹 預設情況下，模板引擎為模板標籤定義了許多標識符號，起手式及結尾都是以雙{{}}來包住。 | 說明 | 標籤 | 備註 | | -------- | -------- | -------- | | 照片標籤 | {{@Var}} | 用於插入圖片 | | 表格標籤 | {{#Var}} | 通常搭配表格 | | 文字標籤 | {{Var}} | 最基本、最常用 | | 條件判斷開始標籤 | {{?Var}} | 與 /Var 成對使用 | | 條件判斷結束標籤 | {{/Var}} | 與 ?Var 成對使用 | --- ### 核心概念 三部曲： 1.建立Word範本(.docx)。 2.在Word範本加入標籤。 3.由Java填入資料替換標籤，最後產出文件。 --- ### 文字標籤 範例 在Word範例中輸入 ``` Word= 您好， {{Name}} 歡迎光臨。 ``` 程式碼 ``` Java= public class PoiTlTextDemo { public static void main(String[] args) throws Exception { // 1. 準備資料 Map<String, Object> data = new HashMap<>(); data.put("Name", "測試股份有限公司"); // 2. 載入範本並渲染 XWPFTemplate template = XWPFTemplate .compile("template.docx") .render(data); // 3. 輸出檔案 template.write(new FileOutputStream("output-text.docx")); // 4. 關閉 template.close(); System.out.println("文字標籤 Word 產生完成"); } } ``` ### 圖片標籤 範例 在Word範例中輸入 ``` Word= 我是圖片{{@Image}} ``` 程式碼 ``` Java= public class PoiTlImageDemo { public static void main(String[] args) throws Exception { // 1. 準備圖片資料 PictureRenderData image = Pictures .ofLocal("logo.png") .size(120, 60) .create(); Map<String, Object> data = new HashMap<>(); data.put("Image", image); // 2. 載入範本並渲染 XWPFTemplate template = XWPFTemplate .compile("template.docx") .render(data); // 3. 輸出檔案 template.write(new FileOutputStream("output-image.docx")); // 4. 關閉 template.close(); System.out.println("圖片標籤 Word 產生完成"); } } ``` ### 表格標籤 範例 在Word範例中輸入 ``` Word= 先畫好表格如下 | 方案名稱 | 類型 | 金額 | | -------- | -------- | ---------- | | {{#itemList}}{{name}} | {{type}} | {{amount}}{{/itemList}} | ``` 程式碼 ``` Java= public class PoiTlTableDemo { public static void main(String[] args) throws Exception { // 1. 建立表格資料 TableRenderData table = new TableRenderData(); RowRenderData row1 = Rows.of("方案A", "後繳", "1000").create(); RowRenderData row2 = Rows.of("方案B", "預繳", "2000").create(); table.addRow(row1); table.addRow(row2); Map<String, Object> data = new HashMap<>(); data.put("itemList", table); // 2. 載入範本並渲染 XWPFTemplate template = XWPFTemplate .compile("template.docx") .render(data); // 3. 輸出檔案 template.write(new FileOutputStream("output-table.docx")); // 4. 關閉 template.close(); System.out.println("表格標籤 Word 產生完成"); } } ``` ### 條件判斷標籤 範例 在Word範例中輸入 ``` Word= {{?showNote}} 備註：只有在showNote條件成立時才會顯示這段備註文字。 {{/showNote}} ``` 程式碼 ``` Java= public class PoiTlConditionDemo { public static void main(String[] args) throws Exception { // 1. 準備資料 Map<String, Object> data = new HashMap<>(); // true → 顯示區塊 // false 或 null → 不顯示 data.put("showNote", true); // 2. 載入範本並渲染 XWPFTemplate template = XWPFTemplate .compile("template.docx") .render(data); // 3. 輸出檔案 template.write(new FileOutputStream("output-condition.docx")); // 4. 關閉 template.close(); System.out.println("條件判斷標籤 Word 產生完成"); } } ``` ※進階用法，可以讓條件判斷傳入的值是否有值如果等於null或是空則不顯示。 --- ### 常見錯誤 錯誤訊息 ``` Java= ClassCastException: ArrayList cannot be cast to TableRenderData ``` 原因 ``` Java= 範本使用 {{#Var}} 但程式傳入的是 List 而不是 TableRenderData ``` 錯誤訊息 ``` Java= Mismatched start/end tags ``` 原因 ``` Java= {{?Var}} 與 {{/Var}} 不成對，或被拆成不同 Word Run 解法：不要換行、不插入多餘空白 ``` --- ### 總結 &nbsp;&nbsp;以上就是簡易的POI-TL使用教學文章。 --- > 歡迎隨意引用或拷貝，若有涉及侵權概不負責。