Java poi-tl 使用 word 模板 生成 word

文章目录

• • [poi-tl 简绍](#poi-tl 简绍)
  • [poi-tl 官网](#poi-tl 官网)
  • 横向对比
  • 引入要求
  • 使用
  • Template：模板
  • Data-model：数据
  • Output：输出
  • [标签 数据样式](#标签 数据样式)
  • • 文本
    • • 数据模型：
      • [推荐使用工厂 Texts 构建文本模型。](#推荐使用工厂 Texts 构建文本模型。)
      • TextRenderData的结构体
    • 图片
    • • 数据模型：
      • [推荐使用工厂 Pictures 构建图片模型。](#推荐使用工厂 Pictures 构建图片模型。)
      • FilePictureRenderData的结构体
    • 表格
    • • TableRenderData的结构体

poi-tl 简绍

poi-tl（poi template language）是Word模板引擎，使用模板和数据创建很棒的Word文档。

在文档的任何地方做任何事情（Do Anything Anywhere）是poi-tl的星辰大海。

poi-tl 官网

https://deepoove.com/poi-tl/

横向对比

| | 方案 | 移植性 | 功能性 | 易用性 | |--------------|--------------------|----------------------------------|----------------------------------------------------------------| | Poi-tl | Java跨平台 | Word模板引擎，基于Apache POI，提供更友好的API | 低代码，准备文档模板和数据即可 | | Apache POI | Java跨平台 | Apache项目，封装了常见的文档操作，也可以操作底层XML结构 | 文档不全，这里有一个教程：https://deepoove.com/poi-tl/apache-poi-guide.html | | Freemarker | XML跨平台 | 仅支持文本，很大的局限性 | 不推荐，XML结构的代码几乎无法维护 | | OpenOffice | 部署OpenOffice，移植性较差 | - | 需要了解OpenOffice的API | | HTML浏览器导出 | 依赖浏览器的实现，移植性较差 | HTML不能很好的兼容Word的格式，样式糟糕 | - | | Jacob、winlib | Windows平台 | - | 复杂，完全不推荐使用 | |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

引入要求

JDK1.8+

Apache POI5.2.2+

所需仓库maven jar包

<dependency>
  <groupId>com.deepoove</groupId>
  <artifactId>poi-tl</artifactId>
  <version>1.12.2</version>
</dependency>

使用

新建Word文档template.docx，包含标签 {{title}}

1. 代码使用实例

   XWPFTemplate template = XWPFTemplate.compile("template.docx").render(
   new HashMap<String, Object>(){{
   put("title", "Hi, poi-tl Word模板引擎");
   }});
   template.writeAndClose(new FileOutputStream("output.docx"));

• compile 编译模板
• render 渲染数据
• write 输出到流

2. 输出
   output.docx
   Hi, poi-tl Word模板引擎

Template：模板

模板是Docx格式的Word文档，你可以使用Microsoft office、WPS Office、Pages等任何你喜欢的软件制作模板，也可以使用Apache POI代码来生成模板。

所有的标签都是以{{开头，以}}结尾，标签可以出现在任何位置，包括页眉，页脚，表格内部，文本框等，表格布局可以设计出很多优秀专业的文档，推荐使用表格布局。

poi-tl模板遵循"所见即所得"的设计，模板和标签的样式会被完全保留。

Data-model：数据

数据类似于哈希或者字典，可以是Map结构（key是标签名称）：

Map<String, Object> data = new HashMap<>();
data.put("name", "Sayi");
data.put("start_time", "2019-08-04");

可以是对象（属性名是标签名称）：

public class Data {
  private String name;
  private String startTime;
  private Author author;
}

数据可以是树结构，每级之间用点来分隔开，比如{{author.name}}标签对应的数据是author对象的name属性值。

FreeMarker、Velocity文本模板中可以通过三个标签设置图片路径、宽和高：， 但是Word模板不是由简单的文本表示，所以在渲染图片、表格等元素时提供了数据模型，它们都实现了接口 RenderData ，比如图片数据模型 PictureRenderData 包含图片路径、宽、高三个属性。

---

Output：输出

以流的方式进行输出：

template.write(OutputStream stream);

比如文件流：

template.write(new FileOutputStream("output.docx"));

比如网络流：

response.setContentType("application/octet-stream");
response.setHeader("Content-disposition","attachment;filename=\""+"out_template.docx"+"\"");

// HttpServletResponse response
OutputStream out = response.getOutputStream();
BufferedOutputStream bos = new BufferedOutputStream(out);
template.write(bos);
bos.flush();
out.flush();

最后不要忘记关闭这些流。

PoitlIOUtils.closeQuietlyMulti(template, bos, out);

标签 数据样式

poi-tl是一种无逻辑「logic-less」的模板引擎，没有复杂的控制结构和变量赋值，只有标签。标签由前后两个大括号组成，{{title}}是标签，{{?title}}也是标签，title是这个标签的名称，问号标识了标签类型，接下来我们来看看有哪些默认标签类型（用户可以创建新的标签类型，这属于更高级的话题）。

文本

{{var}}

数据模型：

• String ：文本
• TextRenderData ：有样式的文本
• HyperlinkTextRenderData ：超链接和锚点文本
• Object ：调用 toString() 方法转化为文本

推荐使用工厂 Texts 构建文本模型。

put("name", "Sayi");
put("author", Texts.of("Sayi").color("000000").create());
put("link", Texts.of("website").link("http://deepoove.com").create());
put("anchor", Texts.of("anchortxt").anchor("appendix1").create());

所见即所得，标签的样式会应用到替换后的文本上，也可以通过代码设定文本的样式。

TextRenderData的结构体

{
  "text": "Sayi",
  "style": {
    "strike": false, 
    "bold": true, 
    "italic": false, 
    "color": "00FF00", 
    "underLine": false, 
    "fontFamily": "微软雅黑", 
    "fontSize": 12, 
    "highlightColor": "green", 
    "vertAlign": "superscript", 
    "characterSpacing" : 20 
  }
}
## 以下属性与上面数据对应可以调整对应参数
#删除线
#粗体
#斜体
#颜色
#下划线
#字体
#字号
#背景高亮色
#上标或者下标
#间距

图片

图片标签以@开始：{{@var}}

数据模型：

• String ：图片url或者本地路径，默认使用图片自身尺寸
• ByteArrayPictureRenderData
• FilePictureRenderData
• UrlPictureRenderData

推荐使用工厂 Pictures 构建图片模型。

// 指定图片路径
put("image", "logo.png");
// svg图片
put("svg", "https://img.shields.io/badge/jdk-1.6%2B-orange.svg");

// 图片文件
put("image1", Pictures.ofLocal("logo.png").size(120, 120).create());

// 图片流
put("streamImg", Pictures.ofStream(new FileInputStream("logo.jpeg"), PictureType.JPEG)
  .size(100, 120).create());

// 网络图片(注意网络耗时对系统可能的性能影响)
put("urlImg", Pictures.ofUrl("http://deepoove.com/images/icecream.png")
  .size(100, 100).create());

// java图片，我们可以利用Java生成图表插入到word文档中
put("buffered", Pictures.ofBufferedImage(bufferImage, PictureType.PNG)
  .size(100, 100).create());

FilePictureRenderData的结构体

{
  "pictureType" : "PNG", 
  "path": "logo.png", 
  "pictureStyle": {
    "width": 100, 
    "height": 100 
  },
  "altMeta": "图片不存在" 
}

#图片类型
#图片路径
#宽度，单位是像素
#高度，单位是像素
#当无法获取图片时展示的文字

表格

表格标签以#开始：{{#var}}

数据模型：

• TableRenderData

推荐使用工厂 Tables 、 Rows 和 Cells 构建表格模型。

• Example 1. 基础表格示例

  // 一个2行2列的表格
  put("table0", Tables.of(new String[][] {
                  new String[] { "00", "01" },
                  new String[] { "10", "11" }
              }).border(BorderStyle.DEFAULT).create());

  

• Example 2. 表格样式示例

  // 第0行居中且背景为蓝色的表格
  RowRenderData row0 = Rows.of("姓名", "学历").textColor("FFFFFF")
        .bgColor("4472C4").center().create();
  RowRenderData row1 = Rows.create("李四", "博士");
  put("table1", Tables.create(row0, row1));

  

• Example 3. 表格合并示例

  // 合并第1行所有单元格的表格
  RowRenderData row0 = Rows.of("列0", "列1", "列2").center().bgColor("4472C4").create();
  RowRenderData row1 = Rows.create("没有数据", null, null);
  MergeCellRule rule = MergeCellRule.builder().map(Grid.of(1, 0), Grid.of(1, 2)).build();
  put("table3", Tables.of(row0, row1).mergeRule(rule).create());

  

TableRenderData表格模型在单元格内可以展示文本和图片，同时也可以指定表格样式、行样式和单元格样式，而且在N行N列渲染完成后可以应用单元格合并规则 MergeCellRule ，从而实现更复杂的表格。

TableRenderData的结构体

{
  "rows": [ 
    {
      "cells": [ 
        {
          "paragraphs": [ 
            {
              "contents": [
                {
                  [TextRenderData] 
                },
                {
                  [PictureRenderData] 
                }
              ],
              "paragraphStyle": null 
            }
          ],
          "cellStyle": { 
            "backgroundColor": "00000",
            "vertAlign": "CENTER"
          }
        }
      ],
      "rowStyle": { 
        "height": 2.0f
      }
    }
  ],
  "tableStyle": { 
    "width": 14.63f, 
    "colWidths": null
  },
  "mergeRule": { 
    "mapping": {
      "0-0": "1-2"
    }
  }
}

#行数据
#单元格数据
#单元格内段落
#单元格内文本
#单元格内图片
#单元格内段落文本的样式：对齐
#单元格样式：垂直对齐方式，背景色
#行样式：行高(单位cm)
#表格样式：表格对齐、边框样式
#表格宽度(单位cm)，表格的最大宽度 = 页面宽度 - 页边距宽度 * 2，页面宽度为A4(20.99 * 29.6，页边距为#3.18 * 2.54)的文档最大表格宽度14.63cm。
#单元格合并规则，比如第0行第0列至第1行第2列单元格合并

以上是常用类型 更多请参考官网示例