集成 POI-TL 进行 Word 文档处理

https://mp.weixin.qq.com/s/agc8DtKPeaMrcNWuPgBp9w

POI-TL (POI Template Language) 是基于 Apache POI 的 Word 模板引擎，可以通过 模板 + 变量 的方式生成 Word 文档。它支持：

文本替换（支持动态填充数据）
图片插入（支持动态图片填充）
表格数据填充
段落和页眉页脚处理
样例代码：https://gitee.com/lhdxhl/springboot-example.git
相较于直接使用 Apache POI，POI-TL 更加简洁易用，适用于 批量生成 Word 文档 的场景，如：

合同生成
报告自动化
通知模板填充

🧰 2、集成 POI-TL
引入 Maven 依赖，在 pom.xml 添加：

<dependencies>
    <!-- Spring Boot Web 依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- POI-TL 依赖 -->
    <dependency>
        <groupId>com.deepoove</groupId>
        <artifactId>poi-tl</artifactId>
        <version>1.12.0</version>
    </dependency>

    <!-- POI 支持（用于处理 Word） -->
    <dependency>
        <groupId>org.apache.poi</groupId>
        <artifactId>poi-ooxml</artifactId>
        <version>5.2.3</version>
    </dependency>
</dependencies>

📌 POI-TL 依赖 poi-ooxml，因此需要一起引入。

🛠️ 3. 关键功能示例
3.1 基本的 Word 文本替换
1️⃣ 创建 Word 模板

在 src/main/resources/templates/ 目录下创建 template.docx，内容如下：

尊敬的 {{name}}：

您于 {{date}} 在我公司购买了 {{product}}，金额为 {{price}} 元。

感谢您的支持！

签名：{{signature}}
📌 变量格式：{{name}}，{{date}}，{{product}} 等，POI-TL 会自动替换这些占位符。

2️⃣Spring Boot 代码填充模板

创建 WordGeneratorService.java：

package com.lm.poitl.service;

import com.deepoove.poi.XWPFTemplate;
import lombok.var;
import org.springframework.stereotype.Service;

import java.io.FileOutputStream;
import java.io.InputStream;
import java.util.HashMap;
import java.util.Map;

@Service
public class WordGeneratorService {

    public void generateWord() throws Exception {
        // 定义动态数据
        Map<String, Object> data = new HashMap<>();
        data.put("name", "张三");
        data.put("date", "2025年3月12日");
        data.put("product", "MacBook Pro 16寸");
        data.put("price", "19999");
        data.put("signature", "张三公司");

        // 使用类路径加载资源文件
        InputStream templateStream = WordGeneratorService.class.getClassLoader()
                .getResourceAsStream("templates/template.docx");

        if (templateStream == null) {
            throw new IllegalArgumentException("模板文件未找到！");
        }

        XWPFTemplate template = XWPFTemplate.compile(templateStream).render(data);

        // 另存生成的文件
        template.writeToFile("output.docx");
        template.close();
    }
}

📌 核心代码解析

通过 XWPFTemplate.compile(“template.docx”) 加载 Word 模板。
通过 render(data) 进行动态填充。
通过 FileOutputStream 输出生成的 Word 文件。

3.2 通过 Spring Boot 提供下载 API

创建 WordController.java：

package com.example.worddemo.controller;

import com.example.worddemo.service.WordGeneratorService;
import org.springframework.core.io.InputStreamResource;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.io.File;
import java.io.FileInputStream;

@RestController
@RequestMapping("/word")
public class WordController {

    private final WordGeneratorService wordService;

    public WordController(WordGeneratorService wordService) {
        this.wordService = wordService;
    }

    @GetMapping("/download")
    public ResponseEntity<InputStreamResource> downloadWord() throws Exception {
        // 生成 Word 文件
        wordService.generateWord();

        // 读取文件
        File file = new File("output.docx");
        FileInputStream fis = new FileInputStream(file);

        return ResponseEntity.ok()
                .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=output.docx")
                .contentType(MediaType.APPLICATION_OCTET_STREAM)
                .body(new InputStreamResource(fis));
    }
}

📌 测试 API启动 Spring Boot，访问：

http://localhost:8080/word/download
浏览器会自动下载 output.docx。

📚 4. 进阶功能
4.1 动态插入图片
1️⃣ 修改 Word 模板
在 template.docx 中添加：

尊敬的 {{name}}：

请查看您的电子签名：
{{@signature}}
📌 {{@signature}} 表示该字段是 图片。

2️⃣ 代码填充图片

import com.deepoove.poi.data.PictureRenderData;

data.put("signature", new PictureRenderData(100, 50, "src/main/resources/images/signature.png"));

📌 生成的 Word 会插入 签名图片。

4.2 表格填充
1️⃣ 修改模板
在 template.docx 中创建一个 表格：

2️⃣ 代码填充表格

import com.deepoove.poi.data.RowRenderData;
import com.deepoove.poi.data.TextRenderData;

List<RowRenderData> productList = new ArrayList<>();
productList.add(RowRenderData.build(new TextRenderData("MacBook Pro"), new TextRenderData("19999")));
productList.add(RowRenderData.build(new TextRenderData("iPhone 15"), new TextRenderData("8999")));

data.put("products", productList);

📌 效果：表格将填充多个产品数据。

🔚 5. 总结
✅ Spring Boot + POI-TL 生成 Word 文档，主要步骤如下：

定义 Word 模板
使用 POI-TL 进行数据填充
通过 Spring Boot 提供下载 API
支持高级功能：图片、表格、页眉页脚
✅ 适用场景

合同、通知、报告自动生成
数据批量填充
自动化办公