SpringBoot集成Poi-tl实现动态Word文档生成的详细步骤_Java

前言

在项目开发过程中，遇到了一个需求：将用户输入的数据填充到给定格式的 word 文档中。简单来说，就是要根据预定义的模板生成一个新的 word 文档，并自动填充数据。

什么是 poi-tl？

官网：http://deepoove.com/poi-tl/

poi-tl（poi template language）是一个强大的 word 模板引擎，能够根据 word 模板和数据动态生成新的文档。底层是基于 apache poi 实现的。

apache poi 提供了简便的 api 来操作各种 word 文档元素（如文本、图片、表格、页眉、页脚、图表等），并允许直接操作文档的 xml 结构。

poi-tl 的功能特点：

功能	描述
文本渲染	渲染模板中的文本标签
图片渲染	渲染模板中的图片标签
表格渲染	渲染模板中的表格标签
列表渲染	渲染模板中的列表标签
图表渲染	渲染不同类型的图表，包括柱状图、折线图等
条件渲染	根据条件显示或隐藏内容
循环渲染	对文本、图片、表格等内容进行循环渲染
表格行/列循环	对表格的行或列进行循环渲染
图片替换	替换文档中的指定图片
超链接、书签、锚点	支持文档内的超链接、书签、锚点等功能
强大的表达式支持	完全支持 springel 表达式，并可扩展至 ognl、mvel 等表达式
自定义标签支持	支持自定义标签前后缀
文本框支持	支持文本框中的标签
样式自定义	自定义模板样式，同时代码中也可动态设置样式
模板嵌套	支持嵌套模板功能
word 合并	支持 word 中的合并操作
自定义函数（插件）	允许在模板中使用自定义函数

通过这些特性，我们可以轻松地实现模板渲染，生成符合特定格式要求的文档。

如何使用 poi-tl？

本文以 spring boot 项目为例，展示如何集成 poi-tl 进行模板渲染。小伙伴们可以按照步骤一起实践！

1. 创建 spring boot 项目

首先，创建一个 spring boot 项目，版本为 2.2.1（可以根据需要调整版本）。在 pom.xml 文件中引入以下依赖：

<dependency>
    <groupid>org.springframework.boot</groupid>
    <artifactid>spring-boot-starter-web</artifactid>
</dependency>

<dependency>
    <groupid>org.springframework.boot</groupid>
    <artifactid>spring-boot-starter-test</artifactid>
    <scope>test</scope>
</dependency>

2. 添加 poi-tl 依赖

接下来，向 pom.xml 中添加 poi-tl 的依赖：

<dependency>
    <groupid>com.deepoove</groupid>
    <artifactid>poi-tl</artifactid>
    <version>1.9.1</version>
</dependency>

3. 准备 word 模板

我们需要准备一个 word 模板。可以手动创建一个 word 文件，这里我们以 hello world.docx 为例，模板内容如下：

模板示例

我们将模板存放在 resources 目录下，并定义几个占位符，例如：{{title}}、{{text}}、{{author}} 等。

4. 渲染模板并生成新文档

我们可以通过 xwpftemplate 来渲染模板，将数据填充到模板中并生成新的文档。示例代码如下：

@springboottest
public class poitlapplicationtest {
    @test
    public void test() {
        // 获取 word 模板路径
        string filepath = this.getclass().getclassloader().getresource("hello-world.docx").getpath();

        // 渲染数据
        xwpftemplate template = xwpftemplate.compile(filepath).render(
            new hashmap<string, object>() {{
                put("title", "hello, poi-tl word模板引擎");
                put("text", "hello world");
            }}
        );

        // 输出新文档
        try {
            template.writeandclose(new fileoutputstream("output.docx"));
        } catch (ioexception e) {
            e.printstacktrace();
        }
    }
}

执行上述单元测试后，新的文档 output.docx 将会生成，并且内容将如预期渲染。

标签写法

poi-tl 支持多种标签类型，常见的标签包括文本、图片、表格、列表等：

文本标签：{{var}}
图片标签：{{@var}}
表格标签：{{#var}}
列表标签：{{*var}}

插件

poi-tl 支持插件机制，插件允许我们在模板中执行自定义的逻辑。例如，我们可以将 html 渲染插件绑定到某个标签上，使其支持 html 内容渲染。

configure configure = configure.builder().bind("description", new htmlrenderpolicy()).build();

表格行循环

如果需要在 word 文档中渲染多行表格数据，可以使用 hacklooptablerenderpolicy 插件来循环渲染表格的行。

@test
public void rowlooptest() {
    acwordmodel data = getfromdb();  // 假设从数据库获取数据
    string filepath = this.getclass().getclassloader().getresource("table-row-loop.docx").getpath();
    configure configure = configure.builder()
        .bind("articles", new hacklooptablerenderpolicy())
        .bind("columns", new hacklooptablerenderpolicy())
        .build();
    xwpftemplate template = xwpftemplate.compile(filepath, configure).render(data);
    try {
        template.writeandclose(new fileoutputstream("ac-word.docx"));
    } catch (ioexception e) {
        e.printstacktrace();
    }
}

封装工具类

为了方便调用，我们可以封装一个工具类来处理 word 渲染：

public class wordutil {
    public static void generatewordfile(string templatepath, string targetpath, map<string, object> data) {
        xwpftemplate template = xwpftemplate.compile(templatepath).render(data);
        try {
            template.writeandclose(new fileoutputstream(targetpath));
        } catch (ioexception e) {
            e.printstacktrace();
        }
    }
}