ToB企服应用市场:ToB评测及商务社交产业平台

标题: Spring Boot 中使用 Poi-tl 渲染数据并生成 Word 文档 [打印本页]
作者: 来自云龙湖轮廓分明的月亮    时间: 2023-9-10 16:28
标题: Spring Boot 中使用 Poi-tl 渲染数据并生成 Word 文档
本文 Demo 已收录到 demo-for-all-in-java 项目中，欢迎大家 star 支持！后续将持续更新！
前言

产品经理急冲冲地走了过来。「现在需要将按这些数据生成一个 Word 报告文档，你来安排下」
项目中有这么一个需求，需要将用户填写的数据填充到一个 Word 文档中，而这个 Word 文档是人家给定了的。换句话说，让你按照这个文档的内容格式生成新的文档。
什么是 Poi-tl ？

官网：http://deepoove.com/poi-tl/1.9.x/
poi-tl（poi template language）是一种 Word 模板引擎，可以基于 Word 模板和数据生成新的文档，它的底层是通过 Apache POI 来实现的。
Apache POI 不仅封装了易用的文档 API （文本、图片、表格、页眉、页脚、图表等），也可以在底层直接操作文档XML结构。
poi-tl 拥有如下特性（了解瞄一眼就行）：
内容描述文本将标签渲染为文本图片将标签渲染为图片表格将标签渲染为表格列表将标签渲染为列表图表条形图（3D条形图）、柱形图（3D柱形图）、面积图（3D面积图）、折线图（3D折线图）、雷达图、饼图（3D饼图）等图表渲染If Condition判断隐藏或者显示某些文档内容（包括文本、段落、图片、表格、列表、图表等）Foreach Loop循环循环某些文档内容（包括文本、段落、图片、表格、列表、图表等）Loop表格行循环渲染表格的某一行Loop表格列循环渲染表格的某一列Loop有序列表支持有序列表的循环，同时支持多级列表图片替换将原有图片替换成另一张图片书签、锚点、超链接支持设置书签，文档内锚点和超链接功能强大的表达式完全支持SpringEL表达式，可以扩展更多的表达式：OGNL, MVEL…标签定制支持自定义标签前后缀文本框文本框内标签支持样式模板即样式，同时代码也可以设置样式模板嵌套模板包含子模板，子模板再包含子模板合并Word合并Merge，也可以在指定位置进行合并用户自定义函数(插件)在文档任何位置执行函数我们就可以使用这个它来实现这个需求。
如何使用 Poi-tl ？

本篇文章将以 Spring Boot 项目作为演示，屏幕前的朋友们可以一起跟着我的步骤来，实践一番！
其中， pom.xml 只有两个依赖项，一个 web 和一个 test ：
  1. <dependency>
  2.     <groupId>org.springframework.boot</groupId>
  3.     <artifactId>spring-boot-starter-web</artifactId>
  4. </dependency>
  6. <dependency>
  7.     <groupId>org.springframework.boot</groupId>
  8.     <artifactId>spring-boot-starter-test</artifactId>
  9.     <scope>test</scope>
  10. </dependency>
复制代码
  1. <dependency>
  2.     <groupId>com.deepoove</groupId>
  3.     <artifactId>poi-tl</artifactId>
  4.     <version>1.9.1</version>
  5. </dependency>
复制代码
这一步你可以自己动手做一个 Word 模板，这里我先演示下。就先创建一个名为 Hello World.docx 的 Word 文档，模板内容如下：

找一个你喜欢的位置存放这个模板，我现在把它放到项目的 resource 目录。
{{title}} 这种由两个大括号包住的，目前可以看成占位符，这个模板中有 4 个占位符，后续的数据就渲染到这些地方上。
渲染只需一行代码，就是使用 XWPFTemplate 的 API 就可以了，通过 complie 和 render 方法，就可以将数据渲染到模板中，得到渲染好的新文档。
  1. @SpringBootTest
  2. public class PoiTlApplicationTest {
  4.     @Test
  5.     public void test() {
  6.         // 获取 Word 模板所在路径
  7.         String filepath = this.getClass().getClassLoader().getResource("hello-world.docx").getPath();
  8.         // 通过 XWPFTemplate 编译文件并渲染数据到模板中
  9.         XWPFTemplate template = XWPFTemplate.compile(filepath).render(
  10.                 new HashMap<String, Object>(){{
  11.                     put("title", "Hello, poi-tl Word模板引擎");
  12.                     put("text", "Hello World");
  13.                     put("author", "god23bin");
  14.                     put("description", "这还不关注 god23bin ？再不关注我可要求你关注了！");
  15.                 }});
  16.         try {
  17.             // 将完成数据渲染的文档写出
  18.             template.writeAndClose(new FileOutputStream("output.docx"));
  19.         } catch (IOException e) {
  20.             e.printStackTrace();
  21.         }
  22.     }
  23.    
  24. }
复制代码
执行这个单元测试，就可以看到在项目所在目录下输出了新的文档 output.docx，打开这个文档，我们就可以看到如下图所示的内容：

大功告成，这就是渲染好的新文档了，是不是很简单，一行代码就完成了根据模板进行数据的渲染！
相关概念

模板

模板是 Docx 格式的 Word 文档，我们可以使用 Microsoft office、WPS Office 等软件来制作模板。
标签

上面说到 {{title}} 这种理解成占位符，实际上，官方是称之为「标签」。
所有的标签都是以 {{ 开头，以 }} 结尾，标签可以出现在任何位置，包括页眉，页脚，表格内部，文本框等。
表格布局可以设计出很多优秀专业的文档，推荐使用表格布局。
poi-tl 模板遵循 所见即所得 的设计，模板和标签的样式会被完全保留，就如我上面演示的，一级标题和字体颜色的样式就被保留下来了。
数据模型

数据模型，也就是我们需要渲染到模板中的数据，可以是哈希表，也可以是普通的 Java 对象。
  1. Map<String, Object> data = new HashMap<>();
  2. data.put("title", "Hello, poi-tl Word模板引擎");
  3. data.put("text", "Hello World");
  4. data.put("author", "god23bin");
  5. data.put("description", "这还不关注 god23bin ？再不关注我可要求你关注了！");
复制代码
  1. public class DataModel {
  2.     private String title;
  3.     private String text;
  4.     private String author;
  5.     private String description;
  6.     // 省略 getter 和 setter
  7. }
  9. DataModel data = new DataModel();
  10. data.setTitle("Hello, poi-tl Word模板引擎");
  11. data.setText("Hello World");
  12. data.setAuthor("god23bin");
  13. data.setDescription("这还不关注 god23bin ？再不关注我可要求你关注了！");
复制代码
有了哈希表和或者 Java 对象的数据模型后，将这个数据丢给渲染的 API，就可以完成数据的渲染了。
标签的写法

poi-tl 里只有标签，那么我们需要知道标签的写法是怎样的。在 Word 文档里，可以有：文本、图片、表格、列表等元素，那么对应的，咱们的标签也有这些。
文本标签 {{var}}

简单粗暴，直接 {{标签名}} 就是文本标签了。
图片标签 {{@var}}

{{@标签名}} 就是图片标签，@ 标识了这个标签的类型是图片，其他的也是同理，不同的符号标识不同类型的标签。
表格标签 {{#var}}

使用 # 标识这是一个表格标签。
列表标签 {{*var}}

使用 * 标识这是一个列表标签。
其余的标签

剩下的标签还有很多，详细的内容你可以阅读官方文档，这里就不一一介绍了。
下面我将写下我用过的内容。
插件

插件，又称为自定义函数，它允许我们在模板标签位置处执行预先定义好的函数。由于插件机制的存在，我们几乎可以在模板的任何位置执行任意操作。
插件是 poi-tl 的核心，默认的标签和引用标签都是通过插件加载。
默认插件

poi-tl 默认提供了八个策略插件，用来处理文本、图片、列表、表格、文档嵌套、引用图片、引用多系列图表、引用单系列图表等：
由于这 8 个插件是经常用到的，所以这些插件被注册为不同的标签类型，也就是我们看到过的 {{var}}、{{@var}}、{{#var}} 等不同类型的标签，从而搭建了 poi-tl 的标签体系。
除了这 8 个通用的策略插件外，还内置了一些额外用途的插件：
DynamicTableRenderPolicy动态表格插件，允许直接操作表格对象示例-动态表格HackLoopTableRenderPolicy循环表格行，下文会详细介绍示例-表格行循环LoopColumnTableRenderPolicy循环表格列示例-表格列循环BookmarkRenderPolicy书签和锚点示例-Swagger文档JSONRenderPolicy高亮显示JSON代码块示例-Swagger文档AbstractChartTemplateRenderPolicy引用图表插件，允许直接操作图表对象ParagraphRenderPolicy渲染一个段落，可以包含不同样式文本，图片等DocumentRenderPolicy渲染多个段落和表格TOCRenderPolicyBeta实验功能：目录，打开文档时需要更新域使用插件

为了让插件在某个标签处执行，我们需要将插件与标签绑定。
当我们有个模板标签为 {{description}}，默认是文本标签，如果希望在这个位置做些不一样或者更复杂的事情，我们可以将插件应用到这个模板标签，比如渲染 HTML：
  1. ConfigureBuilder builder = Configure.builder();
  2. builder.bind("description", new HtmlRenderPolicy());
复制代码
此时，{{description}} 将不再是一个文本标签，而是一个自定义的支持 HTML 渲染的标签。
当然，这里的 HTML 渲染的插件，默认是没有提供的，需要引入以下的依赖项，才能支持 HTML 的渲染。
  1. <dependency>
  2.     <groupId>io.github.draco1023</groupId>
  3.     <artifactId>poi-tl-ext</artifactId>
  4.     <version>0.3.3</version>
  5. </dependency>
复制代码
示例：我们对 {{author}} 这个标签绑定上支持 HTML 渲染的插件，这样就能渲染 HTML 的文本了。
  1. @SpringBootTest
  2. public class PoiTlApplicationTest {
  4.     @Test
  5.     public void test() {
  6.         // 获取 Word 模板所在路径
  7.         String filepath = this.getClass().getClassLoader().getResource("hello-world.docx").getPath();
  8.         // 给标签绑定插件
  9.         Configure configure = Configure.builder().bind("author", new HtmlRenderPolicy()).build();
  10.         // 通过 XWPFTemplate 编译文件并渲染数据到模板中
  11.         XWPFTemplate template = XWPFTemplate.compile(filepath, configure).render(
  12.                 new HashMap<String, Object>(){{
  13.                     put("title", "Hello, poi-tl Word模板引擎");
  14.                     put("text", "Hello World");
  15.                     put("author", "<h2>god23bin</h2>");
  16.                     put("description", "这还不关注 god23bin ？再不关注我可要求你关注了！");
  17.                 }});
  18.         try {
  19.             // 将完成数据渲染的文档写出
  20.             template.writeAndClose(new FileOutputStream("output.docx"));
  21.         } catch (IOException e) {
  22.             e.printStackTrace();
  23.         }
  24.     }
  25.    
  26. }
复制代码
生成的 Word 文档如下图所示，可以看到 {{author}} 这个标签的 HTML 文本已经渲染成功了！（蓝框框）

表格行循环

当有类似如下需求的时候，在表格里展示多行同类型的数据，那么就需要用到表格的行循环了。

这里也是涉及到插件的，具体就是使用 HackLoopTableRenderPolicy 这个插件策略，这个策略能够根据集合数据进行循环渲染，这样就渲染数据到表格的行上了，集合有多少个元素，那么就有多少行。
我们来看下这个表格行循环的模板是怎样写的，是这样的：

可以看到 {{articles}} 和 {{columns}} 是标准的文本标签，我们这里将这两个标签置于循环行的上一行，循环行里设置要循环的标签和内容，注意这里的标签是使用 [] 的，以此来区分标准的标签语法。
同时 {{articles}} 和 {{columns}} 标签对应的数据就是文章和专栏的集合。
我们写一个该模板的数据模型，以 Java 对象来写，同时模拟数据从数据库中读取。
数据模型：AcWordModel
  1. public class AcWordModel {
  2.     /**
  3.      * 文章明细数据模型-表格行循环
  4.      */
  5.     private List<Article> articles;
  6.     /**
  7.      * 专栏明细数据模型
  8.      */
  9.     private List<SpecialColumn> columns;
  10.     // 省略 getter 和 setter
  11. }
复制代码
其中的 Article 和 SpecialColumn 模型如下：
  1. public class Article {
  2.     private String title;
  3.     private String tags;
  4.     private Integer reading;
  5.     private Integer likes;
  6.     // 省略 getter 和 setter
  7. }
复制代码
  1. public class SpecialColumn {
  2.     private String name;
  3.     private Integer subscription;
  4.     private Integer nums;
  5.     // 省略 getter 和 setter
  6. }
复制代码
进行测试，获取数据和模板，让标签和表格行循环的插件进行绑定
  1.     @Test
  2.     public void rowLoopTest() {
  3.         // 获取数据，这里假装是从数据库中查询得到的
  4.         AcWordModel data = getFromDB();
  5.         // 获取 Word 模板所在路径
  6.         String filepath = this.getClass().getClassLoader().getResource("table-row-loop.docx").getPath();
  7.         // 给标签绑定插件，这里就绑定表格行循环的插件
  8.         Configure configure = Configure.builder()
  9.                 .bind("articles", new HackLoopTableRenderPolicy())
  10.                 .bind("columns", new HackLoopTableRenderPolicy())
  11.                 .build();
  12.         // 通过 XWPFTemplate 编译文件并渲染数据到模板中
  13.         XWPFTemplate template = XWPFTemplate.compile(filepath, configure).render(data);
  14.         try {
  15.             // 将完成数据渲染的文档写出
  16.             template.writeAndClose(new FileOutputStream("ac-word.docx"));
  17.         } catch (IOException e) {
  18.             e.printStackTrace();
  19.         }
  20.     }
复制代码
这样，就能实现表格的行循环了！
封装 Word 渲染生成新文档的工具

我们可以再封装下这个 API，写一个工具类，如下：
  1. package cn.god23bin.demo.util;
  3. import com.deepoove.poi.XWPFTemplate;
  4. import com.deepoove.poi.config.Configure;
  6. import java.io.FileOutputStream;
  7. import java.io.IOException;
  8. import java.util.Map;
  10. public class WordUtil {
  12.     /**
  13.      * 生成 word 文档
  14.      * @param wordTemplatePath    word 模板路径
  15.      * @param targetWordFilePath  生成目标文档路径
  16.      * @param data                待渲染的数据模型-哈希表形式
  17.      */
  18.     public static void generateWordFile(String wordTemplatePath, String targetWordFilePath, Map<String, Object> data) {
  19.         XWPFTemplate template = XWPFTemplate.compile(wordTemplatePath).render(data);
  20.         try {
  21.             template.writeAndClose(new FileOutputStream(targetWordFilePath));
  22.         } catch (IOException e) {
  23.             e.printStackTrace();
  24.         }
  25.     }
  27.     /**
  28.      * 生成 word 文档
  29.      * @param wordTemplatePath    word 模板路径
  30.      * @param targetWordFilePath  生成目标文档路径
  31.      * @param data                待渲染的数据模型-Java对象形式
  32.      */
  33.     public static void generateWordFile(String wordTemplatePath, String targetWordFilePath, Object data) {
  34.         XWPFTemplate template = XWPFTemplate.compile(wordTemplatePath).render(data);
  35.         try {
  36.             template.writeAndClose(new FileOutputStream(targetWordFilePath));
  37.         } catch (IOException e) {
  38.             e.printStackTrace();
  39.         }
  40.     }
  42.     /**
  43.      * 生成 word 文档
  44.      * @param wordTemplatePath    word 模板路径
  45.      * @param targetWordFilePath  生成目标文档路径
  46.      * @param data                待渲染的数据模型-哈希表形式
  47.      * @param configure           渲染配置
  48.      */
  49.     public static void generateWordFile(String wordTemplatePath, String targetWordFilePath, Map<String, Object> data, Configure configure) {
  50.         XWPFTemplate template = XWPFTemplate.compile(wordTemplatePath, configure).render(data);
  51.         try {
  52.             template.writeAndClose(new FileOutputStream(targetWordFilePath));
  53.         } catch (IOException e) {
  54.             e.printStackTrace();
  55.         }
  56.     }
  58.     /**
  59.      * 生成 word 文档
  60.      * @param wordTemplatePath    word 模板路径
  61.      * @param targetWordFilePath  生成目标文档路径
  62.      * @param data                待渲染的数据模型-Java对象形式
  63.      * @param configure           渲染配置
  64.      */
  65.     public static void generateWordFile(String wordTemplatePath, String targetWordFilePath, Object data, Configure configure) {
  66.         XWPFTemplate template = XWPFTemplate.compile(wordTemplatePath, configure).render(data);
  67.         try {
  68.             template.writeAndClose(new FileOutputStream(targetWordFilePath));
  69.         } catch (IOException e) {
  70.             e.printStackTrace();
  71.         }
  72.     }
  73. }
复制代码
最后的最后

希望各位屏幕前的靓仔靓女们给个三连！你轻轻地点了个赞，那将在我的心里世界增添一颗明亮而耀眼的星！
咱们下期再见！

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！



欢迎光临 ToB企服应用市场:ToB评测及商务社交产业平台 (https://dis.qidao123.com/) Powered by Discuz! X3.4