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}风格。

例如:

plaintext 复制代码
尊敬的{{customer.name}}:
您最近购买的商品如下:
{{#foreach $item in $order.items}}
- 商品名称:{{item.name}}
   数量:{{item.quantity}}
{{/foreach}}
感谢您的惠顾!您的订单总额为:{{order.totalAmount}}元。

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

4. poi-tl核心功能

变量插入

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

条件语句

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

plaintext 复制代码
{{#if ${condition}}}
    ... 条件满足时的内容 ...
{{#elseif ${otherCondition}}}
    ... 其他条件满足时的内容 ...
{{else}}
    ... 所有条件都不满足时的内容 ...
{{/if}}

循环结构

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

plaintext 复制代码
{{#foreach ${item in items}}}
    {{item.property}}
{{/foreach}}

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

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

java 复制代码
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...
    }
}

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

6. 总结

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

相关推荐
瓯雅爱分享2 小时前
Java+Vue构建的采购招投标一体化管理系统,集成招标计划、投标审核、在线竞价、中标公示及合同跟踪功能,附完整源码,助力企业实现采购全流程自动化与规范化
java·mysql·vue·软件工程·源代码管理
mit6.8244 小时前
[C# starter-kit] 命令/查询职责分离CQRS | MediatR |
java·数据库·c#
诸神缄默不语4 小时前
Maven用户设置文件(settings.xml)配置指南
xml·java·maven
任子菲阳4 小时前
学Java第三十四天-----抽象类和抽象方法
java·开发语言
学Linux的语莫5 小时前
机器学习数据处理
java·算法·机器学习
找不到、了5 小时前
JVM的即时编译JIT的介绍
java·jvm
西瓜er5 小时前
JAVA:Spring Boot 集成 FFmpeg 实现多媒体处理
java·spring boot·ffmpeg
你总是一副不开心的样子(´ . .̫ .5 小时前
一、十天速通Java面试(第三天)
java·面试·职场和发展·java面试
迎風吹頭髮6 小时前
UNIX下C语言编程与实践63-UNIX 并发 Socket 编程:非阻塞套接字与轮询模型
java·c语言·unix
我是华为OD~HR~栗栗呀6 小时前
23届考研-Java面经(华为OD)
java·c++·python·华为od·华为·面试