基于POI-TL实现动态Word模板数据填充（含图表）：从需求到落地的完整开发实践

基于POI-TL实现动态Word模板数据填充（含图表）：从需求到落地的完整开发实践

在企业级报告生成场景中，“在线编辑模板+动态数据填充”是高频需求——既要支持业务人员通过可视化工具自定义Word模板结构，又要确保后端能精准将数据库数据（含文字、图表）填充到模板中。本文将详细记录我基于POI-TL实现“OnlyOffice在线编辑模板+动态文字/图表填充”的全流程，包括需求拆解、核心技术实现、难点突破及最终落地方案。

一、项目需求与整体流程

1. 核心需求

业务侧需要一套“模板自定义+报告自动生成”系统，核心诉求分为两部分：

• 前端模板编辑（基于OnlyOffice）：支持业务人员在OnlyOffice中插入“文字指标”和“图表指标”，生成自定义模板。
• 后端数据填充（基于POI-TL）：加载前端编辑好的Word模板，自动查询指标数据，填充“文字占位符”和“图表占位符”，最终生成完整报告并存储到MinIO。

2. 指标定义与占位符规范

为了实现“前端插入指标-后端精准匹配”，我们约定了严格的占位符规则：

3. 整体流程概览

整个系统的数据流如下：

1. 模板编辑：业务人员通过OnlyOffice编辑模板，插入文字/图表占位符，前端将“已插入的文字指标ID”以逗号分隔字符串（indicatorsIdStr）记录，模板文件保存到MinIO。
2. 模板加载：后端接收“生成报告”请求，从MinIO下载Word模板，转换为文件流。
3. 数据查询：
   • 解析indicatorsIdStr，查询所有文字指标数据，存入结果Map。
   • 遍历模板中的图表，匹配对应的图表指标ID，查询数组型数据。
4. 数据填充：通过POI-TL将文字数据、图表数据填充到模板中。
5. 报告存储：填充完成的Word文件流上传到MinIO，返回访问链接。

二、技术栈选型

选择合适的技术栈是实现需求的基础，本项目核心技术选型如下：

• 前端模板编辑：OnlyOffice（开源在线Office编辑工具，支持自定义插件扩展指标树）；
• 后端模板处理：POI-TL 1.12.2（基于Apache POI的Word模板引擎，支持文字、图表、表格等复杂填充）；
• 文件存储：MinIO（轻量对象存储服务，兼容S3协议，便于模板和报告的上传/下载）；
• 开发语言：Java 17 + Spring Boot 2.7.16

为什么选POI-TL？
相比原生Apache POI的“硬编码操作XML”，POI-TL支持“模板+数据”的分离模式，通过“占位符”即可实现填充，无需关心Word底层的XML结构；同时其原生支持图表填充，无需额外引入复杂插件，非常适合本需求。

三、核心实现步骤

1. 前置准备：引入依赖

在pom.xml中引入POI-TL及MinIO相关依赖（注意POI-TL需与Apache POI版本兼容）：

<!-- POI-TL 核心依赖 -->
<dependency>
	<groupId>com.deepoove</groupId>
	<artifactId>poi-tl</artifactId>
	<version>1.12.2</version>
	<exclusions>
		<exclusion>
			<artifactId>batik-bridge</artifactId>
			<groupId>org.apache.xmlgraphics</groupId>
		</exclusion>
		<exclusion>
			<artifactId>poi-ooxml</artifactId>
			<groupId>org.apache.poi</groupId>
		</exclusion>
	</exclusions>
</dependency>

<!-- POI 核心依赖 -->
<dependency>
	<groupId>org.apache.poi</groupId>
	<artifactId>poi-ooxml</artifactId>
	<version>5.2.4</version>
</dependency>
<dependency>
	<groupId>org.apache.poi</groupId>
	<artifactId>poi</artifactId>
	<version>5.2.4</version>
</dependency>
<dependency>
	<groupId>org.apache.poi</groupId>
	<artifactId>poi-ooxml-lite</artifactId>
	<version>5.2.4</version>
</dependency>
<!-- 处理图表和Excel数据 -->
<dependency>
	<groupId>org.apache.poi</groupId>
	<artifactId>poi-ooxml-full</artifactId>
	<version>5.2.4</version>
</dependency>

2. 步骤1：加载Word模板（从MinIO到文件流）

首先通过MinIO客户端下载模板文件，转换为InputStream，供POI-TL使用。 本地开发时建议放在本地读取，方便修改模板测试多个图表
注意：POI-TL处理的是.docx格式，需确保模板为docx而非doc。

/**
 * 从MinIO下载模板文件，返回输入流
 */
public InputStream downloadTemplateFromMinIO(String templatePath) throws Exception {
   
   
    // 1. 初始化MinIO客户端
    MinioClient minioClient = MinioClient.builder()
            .endpoint(minioConfig.getEndpoint())
            .credentials(minioConfig.getAccessKey(), minioConfig<