【亲测免费】 poi-tl-ext: 扩展版POI工具包使用指南

2026-01-16 10:20:33作者：董斯意

1. 项目介绍

poi-tl-ext 是一个基于 Apache POI 和 poi-tl 的扩展项目，旨在简化 Word 文档操作中的数据填充过程。它引入了一系列增强特性，包括对表格和列表数据的灵活处理以及图表和目录自动生成的支持。

功能亮点:

数据类型自动化: 直接在Word文档中设定数据类型，简化后台数据组装。
所见即所得: 确保文档输出结果与预览一致。
图表生成: 提供二维柱状图、条形图、折线图、饼图、面积图和环形图等图表生成能力。
目录动态更新: 自动生成并更新文档目录结构。

安装与集成:

Maven依赖配置

对于基于 poi-tl-1.7.2 的环境：

<dependency>
    <groupId>com.github.xiao1wang.poitlextended</groupId>
    <artifactId>poi-tl-ext</artifactId>
    <!-- 使用最新或特定版本 -->
</dependency>

对于其他版本的 poi-tl，特别是 poi-tl 1.11 及以上：

<dependency>
    <groupId>io.github.draco1023</groupId>
    <artifactId>poi-tl-ext</artifactId>
    <!-- 根据实际发布版本调整 -->
    <version>0.4.16</version>
</dependency>

或者针对 poi 版本 5.x：

<dependency>
    <groupId>io.github.draco1023</groupId>
    <artifactId>poi-tl-ext</artifactId>
    <version>0.4.16-poi5</version>
</dependency>

2. 快速启动

为了进行一次简单的演示，我们将使用 Maven 将 poi-tl-ext 添加至项目依赖中，并执行一段代码来创建一个带有样例数据的Word文档。

步骤一: 添加Maven仓库依赖

将上述任意一组 <dependency> 内容加入你的 pom.xml 文件中。

步骤二: 实现示例代码

下面的Java代码片段展示了如何使用 poi-tl-ext 来创建一个简单的Word文档：

import org.docx4j.Docx4J;
import org.docx4j.openpackaging.exceptions.Docx4JException;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;

public class QuickStart {
    
    public static void main(String[] args) throws Docx4JException {
        // 加载你的Word模板文件
        WordprocessingMLPackage template = Docx4J.load(new java.io.File("path/to/your/template.docx"));
        
        // 这里假设你已经有了一个实现自 poi-tl 的 DataRenderPolicy 接口的对象
        // 这个对象负责解析和填充模板中的占位符
        // 例如: MyDataRenderPolicy dataPolicy = new MyDataRenderPolicy();
        
        // 使用poi-tl-ext的策略填充数据
        //template.getDataObjectFactory().setDataRenderPolicy(dataPolicy);
        template.getMainDocumentPart().addCustomXmlData(null); // 示例添加XML数据
        
        // 保存最终的Word文档
        Docx4J.save(template, new java.io.File("output/generatedReport.docx"));
    }
}