poi-tl：基于Apache POI的轻量级Word模板引擎

1. 前言

在现代办公自动化和企业应用开发中，动态生成Microsoft Word文档是一项至关重要的任务。为了实现这一目标，开发者需要寻找一个既能保证文档格式规范又能灵活处理数据填充的解决方案。Apache POI作为Java平台下处理Office文件的标准库，在此基础上构建的poi-tl项目则以其高效、简洁的模板引擎设计脱颖而出，为快速生成高质量、结构化Word文档提供了强大的支持。

官网地址： https://deepoove.com/poi-tl/

2. poi-tl简介

poi-tl（POI Template Lite） 是由baomidou团队精心打造的一款专为Java开发者设计的Word模板引擎，它深度整合了Apache POI的功能，并引入了一套直观易用的模板语言，使得将结构化的数据模型与预定义的Word模板相结合以输出定制化文档变得异常简单。

3. 模板语法详解

在poi-tl中，模板是使用标准DOCX格式创建的Word文档，其中嵌入了特定的标签语法来指示数据插入点以及逻辑控制结构。poi-tl采用的是{{和}}作为标签的起始和结束符号，而不是某些其他模板引擎所使用的${variable}风格。

例如：

尊敬的{{customer.name}}：
您最近购买的商品如下：
{{#foreach $item in $order.items}}
- 商品名称：{{item.name}}
   数量：{{item.quantity}}
{{/foreach}}
感谢您的惠顾！您的订单总额为：{{order.totalAmount}}元。
1
2
3
4
5
6
7

在这段模板示例中，{{customer.name}}用于插入客户姓名，而{{#foreach}}和{{/foreach}}则是循环遍历订单项列表的标签。

4. poi-tl核心功能

变量插入

poi-tl允许通过{{variable}}格式插入任何类型的数据，如字符串、数字或日期等。比如在上述模板片段中，{{customer.name}}表示将要替换为实际客户姓名的地方。

条件语句

poi-tl还支持条件判断语句，以便根据数据模型中的条件值动态决定是否渲染指定内容：

{{#if ${condition}}}
    ... 条件满足时的内容 ...
{{#elseif ${otherCondition}}}
    ... 其他条件满足时的内容 ...
{{else}}
    ... 所有条件都不满足时的内容 ...
{{/if}}
1
2
3
4
5
6
7

循环结构

对于集合型数据，poi-tl提供{{#foreach}}循环标签，可以轻松地遍历并展示数组或列表内的每个元素：

{{#foreach ${item in items}}}
    {{item.property}}
{{/foreach}}
1
2
3

5. 使用poi-tl生成Word文档

以下是一个完整的Java代码示例，展示了如何使用poi-tl结合数据模型生成Word文档：

import com.deepoove.poi.XWPFTemplate;
import java.io.FileOutputStream;
import java.io.IOException;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class PoiTLDemo {

    public static void main(String[] args) throws IOException {
        // 准备数据模型
        Map<String, Object> data = new HashMap<>();
        Customer customer = new Customer("张三");
        List<OrderItem> items = Arrays.asList(
            new OrderItem("商品A", 5),
            new OrderItem("商品B", 3)
        );
        Order order = new Order(items, 100);
        data.put("customer", customer);
        data.put("order", order);

        // 加载模板文件
        XWPFTemplate template = XWPFTemplate.compile("template.docx");

        // 绑定数据到模板并生成最终文档
        template.render(data);

        // 将生成的Word文档保存至磁盘
        FileOutputStream out = new FileOutputStream("output.docx");
        template.write(out);
        out.close();
        template.close();
    }

    static class Customer {
        String name;
        // 构造函数、getter、setter...
    }

    static class OrderItem {
        String name;
        int quantity;
        // 构造函数、getter、setter...
    }

    static class Order {
        List<OrderItem> items;
        double totalAmount;
        // 构造函数、getter、setter...
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

在这个示例中，我们首先准备了一个包含客户信息和订单详情的数据模型，然后加载模板文件，最后调用XWPFTemplate实例的render方法将数据绑定至模板，并将生成的Word文档写入到磁盘。

6. 总结

借助于poi-tl，Java开发者能够轻松地将复杂的数据结构转换成符合业务需求的专业Word文档。其简单的模板语法和强大的API使得该工具成为众多办公自动化场景的理想选择。无论是创建报告、合同还是自定义信函，poi-tl都能确保高效、准确地完成任务，大大提升了开发效率和文档质量。