---
# System prepended metadata

title: POI-TL 教學

---

# 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使用教學文章。

---
> 歡迎隨意引用或拷貝，若有涉及侵權概不負責。