经验首页 前端设计 程序设计 Java相关 移动开发 数据库/运维 软件/图像 大数据/云计算 其他经验
当前位置:技术经验 » Java相关 » Spring Boot » 查看文章
Spring Boot 中使用 Poi-tl 渲染数据并生成 Word 文档
来源:cnblogs  作者:god23bin  时间:2023/9/10 14:06:51  对本文有异议

本文 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 项目作为演示,屏幕前的朋友们可以一起跟着我的步骤来,实践一番!

  1. 首先创建一个 Spring Boot 项目,版本目前我的 Demo 是 2.2.1,你可以更改你的 Spring Boot 版本,那现在我这里已经创建好了。

其中, pom.xml 只有两个依赖项,一个 web 和一个 test :

  1. <dependency>
  2. <groupId>org.springframework.boot</groupId>
  3. <artifactId>spring-boot-starter-web</artifactId>
  4. </dependency>
  5. <!-- Spring Boot Test 依赖 -->
  6. <dependency>
  7. <groupId>org.springframework.boot</groupId>
  8. <artifactId>spring-boot-starter-test</artifactId>
  9. <scope>test</scope>
  10. </dependency>
  1. 接着在 pom.xml 中引入 Poi-tl 的依赖项
  1. <!-- Poi-tl Word 模板引擎-->
  2. <dependency>
  3. <groupId>com.deepoove</groupId>
  4. <artifactId>poi-tl</artifactId>
  5. <version>1.9.1</version>
  6. </dependency>
  1. 准备一个 Word 模板

这一步你可以自己动手做一个 Word 模板,这里我先演示下。就先创建一个名为 Hello World.docx 的 Word 文档,模板内容如下:

找一个你喜欢的位置存放这个模板,我现在把它放到项目的 resource 目录。

{{title}} 这种由两个大括号包住的,目前可以看成占位符,这个模板中有 4 个占位符,后续的数据就渲染到这些地方上。

  1. 获取模板所在的路径,并将数据渲染到模板上

渲染只需一行代码,就是使用 XWPFTemplate 的 API 就可以了,通过 complierender 方法,就可以将数据渲染到模板中,得到渲染好的新文档。

  1. @SpringBootTest
  2. public class PoiTlApplicationTest {
  3. @Test
  4. public void test() {
  5. // 获取 Word 模板所在路径
  6. String filepath = this.getClass().getClassLoader().getResource("hello-world.docx").getPath();
  7. // 通过 XWPFTemplate 编译文件并渲染数据到模板中
  8. XWPFTemplate template = XWPFTemplate.compile(filepath).render(
  9. new HashMap<String, Object>(){{
  10. put("title", "Hello, poi-tl Word模板引擎");
  11. put("text", "Hello World");
  12. put("author", "god23bin");
  13. put("description", "这还不关注 god23bin ?再不关注我可要求你关注了!");
  14. }});
  15. try {
  16. // 将完成数据渲染的文档写出
  17. template.writeAndClose(new FileOutputStream("output.docx"));
  18. } catch (IOException e) {
  19. e.printStackTrace();
  20. }
  21. }
  22. }

执行这个单元测试,就可以看到在项目所在目录下输出了新的文档 output.docx,打开这个文档,我们就可以看到如下图所示的内容:

大功告成,这就是渲染好的新文档了,是不是很简单,一行代码就完成了根据模板进行数据的渲染!

相关概念

模板

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

标签

上面说到 {{title}} 这种理解成占位符,实际上,官方是称之为「标签」。

所有的标签都是以 {{ 开头,以 }} 结尾,标签可以出现在任何位置,包括页眉,页脚,表格内部,文本框等。

表格布局可以设计出很多优秀专业的文档,推荐使用表格布局。

poi-tl 模板遵循 所见即所得 的设计,模板和标签的样式会被完全保留,就如我上面演示的,一级标题和字体颜色的样式就被保留下来了。

数据模型

数据模型,也就是我们需要渲染到模板中的数据,可以是哈希表,也可以是普通的 Java 对象。

  1. 哈希表(key 名是标签名):
  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. Java 对象(属性名是标签名):
  1. public class DataModel {
  2. private String title;
  3. private String text;
  4. private String author;
  5. private String description;
  6. // 省略 getter 和 setter
  7. }
  8. DataModel data = new DataModel();
  9. data.setTitle("Hello, poi-tl Word模板引擎");
  10. data.setText("Hello World");
  11. data.setAuthor("god23bin");
  12. data.setDescription("这还不关注 god23bin ?再不关注我可要求你关注了!");

有了哈希表和或者 Java 对象的数据模型后,将这个数据丢给渲染的 API,就可以完成数据的渲染了。

标签的写法

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

文本标签 {{var}}

简单粗暴,直接 {{标签名}} 就是文本标签了。

图片标签 {{@var}}

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

表格标签 {{#var}}

使用 # 标识这是一个表格标签。

列表标签 {{*var}}

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

其余的标签

剩下的标签还有很多,详细的内容你可以阅读官方文档,这里就不一一介绍了。

下面我将写下我用过的内容。

插件

插件,又称为自定义函数,它允许我们在模板标签位置处执行预先定义好的函数。由于插件机制的存在,我们几乎可以在模板的任何位置执行任意操作。

插件是 poi-tl 的核心,默认的标签和引用标签都是通过插件加载。

默认插件

poi-tl 默认提供了八个策略插件,用来处理文本、图片、列表、表格、文档嵌套、引用图片、引用多系列图表、引用单系列图表等:

  • TextRenderPolicy
  • PictureRenderPolicy
  • NumberingRenderPolicy
  • TableRenderPolicy
  • DocxRenderPolicy
  • MultiSeriesChartTemplateRenderPolicy
  • SingleSeriesChartTemplateRenderPolicy
  • DefaultPictureTemplateRenderPolicy

由于这 8 个插件是经常用到的,所以这些插件被注册为不同的标签类型,也就是我们看到过的 {{var}}、{{@var}}、{{#var}} 等不同类型的标签,从而搭建了 poi-tl 的标签体系。

除了这 8 个通用的策略插件外,还内置了一些额外用途的插件:

DynamicTableRenderPolicy 动态表格插件,允许直接操作表格对象 示例-动态表格
HackLoopTableRenderPolicy 循环表格行,下文会详细介绍 示例-表格行循环
LoopColumnTableRenderPolicy 循环表格列 示例-表格列循环
BookmarkRenderPolicy 书签和锚点 示例-Swagger文档
JSONRenderPolicy 高亮显示JSON代码块 示例-Swagger文档
AbstractChartTemplateRenderPolicy 引用图表插件,允许直接操作图表对象
ParagraphRenderPolicy 渲染一个段落,可以包含不同样式文本,图片等
DocumentRenderPolicy 渲染多个段落和表格
TOCRenderPolicy Beta实验功能:目录,打开文档时需要更新域

使用插件

为了让插件在某个标签处执行,我们需要将插件与标签绑定

当我们有个模板标签为 {{description}},默认是文本标签,如果希望在这个位置做些不一样或者更复杂的事情,我们可以将插件应用到这个模板标签,比如渲染 HTML:

  1. ConfigureBuilder builder = Configure.builder();
  2. builder.bind("description", new HtmlRenderPolicy());

此时,{{description}} 将不再是一个文本标签,而是一个自定义的支持 HTML 渲染的标签。

当然,这里的 HTML 渲染的插件,默认是没有提供的,需要引入以下的依赖项,才能支持 HTML 的渲染。

  1. <!-- 支持渲染 HTML 的插件 -->
  2. <dependency>
  3. <groupId>io.github.draco1023</groupId>
  4. <artifactId>poi-tl-ext</artifactId>
  5. <version>0.3.3</version>
  6. </dependency>

示例:我们对 {{author}} 这个标签绑定上支持 HTML 渲染的插件,这样就能渲染 HTML 的文本了。

  1. @SpringBootTest
  2. public class PoiTlApplicationTest {
  3. @Test
  4. public void test() {
  5. // 获取 Word 模板所在路径
  6. String filepath = this.getClass().getClassLoader().getResource("hello-world.docx").getPath();
  7. // 给标签绑定插件
  8. Configure configure = Configure.builder().bind("author", new HtmlRenderPolicy()).build();
  9. // 通过 XWPFTemplate 编译文件并渲染数据到模板中
  10. XWPFTemplate template = XWPFTemplate.compile(filepath, configure).render(
  11. new HashMap<String, Object>(){{
  12. put("title", "Hello, poi-tl Word模板引擎");
  13. put("text", "Hello World");
  14. put("author", "<h2>god23bin</h2>");
  15. put("description", "这还不关注 god23bin ?再不关注我可要求你关注了!");
  16. }});
  17. try {
  18. // 将完成数据渲染的文档写出
  19. template.writeAndClose(new FileOutputStream("output.docx"));
  20. } catch (IOException e) {
  21. e.printStackTrace();
  22. }
  23. }
  24. }

生成的 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;
  2. import com.deepoove.poi.XWPFTemplate;
  3. import com.deepoove.poi.config.Configure;
  4. import java.io.FileOutputStream;
  5. import java.io.IOException;
  6. import java.util.Map;
  7. public class WordUtil {
  8. /**
  9. * 生成 word 文档
  10. * @param wordTemplatePath word 模板路径
  11. * @param targetWordFilePath 生成目标文档路径
  12. * @param data 待渲染的数据模型-哈希表形式
  13. */
  14. public static void generateWordFile(String wordTemplatePath, String targetWordFilePath, Map<String, Object> data) {
  15. XWPFTemplate template = XWPFTemplate.compile(wordTemplatePath).render(data);
  16. try {
  17. template.writeAndClose(new FileOutputStream(targetWordFilePath));
  18. } catch (IOException e) {
  19. e.printStackTrace();
  20. }
  21. }
  22. /**
  23. * 生成 word 文档
  24. * @param wordTemplatePath word 模板路径
  25. * @param targetWordFilePath 生成目标文档路径
  26. * @param data 待渲染的数据模型-Java对象形式
  27. */
  28. public static void generateWordFile(String wordTemplatePath, String targetWordFilePath, Object data) {
  29. XWPFTemplate template = XWPFTemplate.compile(wordTemplatePath).render(data);
  30. try {
  31. template.writeAndClose(new FileOutputStream(targetWordFilePath));
  32. } catch (IOException e) {
  33. e.printStackTrace();
  34. }
  35. }
  36. /**
  37. * 生成 word 文档
  38. * @param wordTemplatePath word 模板路径
  39. * @param targetWordFilePath 生成目标文档路径
  40. * @param data 待渲染的数据模型-哈希表形式
  41. * @param configure 渲染配置
  42. */
  43. public static void generateWordFile(String wordTemplatePath, String targetWordFilePath, Map<String, Object> data, Configure configure) {
  44. XWPFTemplate template = XWPFTemplate.compile(wordTemplatePath, configure).render(data);
  45. try {
  46. template.writeAndClose(new FileOutputStream(targetWordFilePath));
  47. } catch (IOException e) {
  48. e.printStackTrace();
  49. }
  50. }
  51. /**
  52. * 生成 word 文档
  53. * @param wordTemplatePath word 模板路径
  54. * @param targetWordFilePath 生成目标文档路径
  55. * @param data 待渲染的数据模型-Java对象形式
  56. * @param configure 渲染配置
  57. */
  58. public static void generateWordFile(String wordTemplatePath, String targetWordFilePath, Object data, Configure configure) {
  59. XWPFTemplate template = XWPFTemplate.compile(wordTemplatePath, configure).render(data);
  60. try {
  61. template.writeAndClose(new FileOutputStream(targetWordFilePath));
  62. } catch (IOException e) {
  63. e.printStackTrace();
  64. }
  65. }
  66. }

最后的最后

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

咱们下期再见!

原文链接:https://www.cnblogs.com/god23bin/p/spring-boot-poi-tl.html

 友情链接:直通硅谷  点职佳  北美留学生论坛

本站QQ群:前端 618073944 | Java 606181507 | Python 626812652 | C/C++ 612253063 | 微信 634508462 | 苹果 692586424 | C#/.net 182808419 | PHP 305140648 | 运维 608723728

W3xue 的所有内容仅供测试,对任何法律问题及风险不承担任何责任。通过使用本站内容随之而来的风险与本站无关。
关于我们  |  意见建议  |  捐助我们  |  报错有奖  |  广告合作、友情链接(目前9元/月)请联系QQ:27243702 沸活量
皖ICP备17017327号-2 皖公网安备34020702000426号