Poi-tl 簡介

Poi-tl 是基于 Apache POI 的 Java 開源文檔處理庫，專注于高效操作 Word 文檔（.docx 格式）。它通過模板引擎機制簡化復雜文檔生成流程，相比原生 POI 具備更簡潔的 API、更強的靈活性和更優的性能表現，廣泛應用于報表生成、合同模板填充、文檔批量處理等企業級場景。

Maven 依賴配置

<dependency><groupId>com.deepoove</groupId><artifactId>poi-tl</artifactId><version>1.12.0</version>
</dependency>

Poi-tl 實現原理與步驟

1. 模板標簽規范

在 Word 模板中需使用特定格式的占位符標識圖片插入位置，標準格式為：{{@標簽名稱}}。
示例標簽格式：

{{@Head}}  <!-- 審核人簽名位置 -->
{{@Approver}}  <!-- 批準人簽名位置 -->

2.完整實現代碼

import com.deepoove.poi.XWPFTemplate;
import com.deepoove.poi.data.PictureType;
import com.deepoove.poi.data.Pictures;import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.util.HashMap;
import java.util.Map;/*** Word文檔圖片插入工具類* 功能：通過Poi-tl在Word模板指定位置插入圖片*/
public class WordImageInserter {/*** 主方法：執行Word圖片插入操作*/public static void main(String[] args) {Path templatePath = Path.of("D:\\template.docx");        // 源文檔模板路徑Path outputPath= Path.of("D:\\template_temp.docx"); // 新文件路徑Path inspectorImagePath = Path.of("D:\\signatures\\inspector.png"); // 審核人簽名圖片Path approverImagePath = Path.of("D:\\signatures\\approver.png");   // 批準人簽名圖片try {// 綁定模板占位符與圖片渲染對象Map<String, Object> dataModel = new HashMap<>();dataModel.put("Head", createPicture(inspectorImagePath, 100, 50));     // 替換{{@Head}}標簽dataModel.put("Approver", createPicture(approverImagePath, 100, 50)); // 替換{{@Approver}}標簽// 執行文檔渲染與圖片插入try (InputStream templateStream = Files.newInputStream(templatePath);OutputStream tempOutputStream = Files.newOutputStream(tempOutputPath)) {// 編譯模板并渲染數據XWPFTemplate template = XWPFTemplate.compile(templateStream).render(dataModel);// 輸出到臨時文件（避免直接修改原文件導致損壞）template.write(tempOutputStream);template.close();}// 原子性替換原文件（保證操作完整性）Files.move(tempOutputPath, templatePath, StandardCopyOption.REPLACE_EXISTING);System.out.println("圖片插入操作完成，文檔已更新");} catch (IOException e) {System.err.println("文檔處理異常：" + e.getMessage());e.printStackTrace();}}/*** 構建圖片渲染對象（支持尺寸自定義）* @param imagePath 圖片文件路徑* @param width 圖片寬度（像素）* @param height 圖片高度（像素）* @return 圖片渲染對象（可直接用于模板渲染）* @throws IOException 圖片讀取失敗時拋出*/private static Object createPicture(Path imagePath, int width, int height) throws IOException {// 使用NIO流加載圖片，自動識別圖片類型（此處顯式指定為PNG）return Pictures.ofStream(Files.newInputStream(imagePath), PictureType.PNG).size(width, height)  // 自定義圖片尺寸.create();           // 生成圖片渲染實體}
}

3.效果展示