阿里开源项目-[Word文档生成神器poi.tl],[easyexcel解决poi的oom问题]

Word文档生成神器 poi-tl(poi-template-language)

github地址：https://github.com/Sayi/poi-tl

     

Word 模板引擎，基于Apache POI - the Java API for Microsoft Documents。

What is poi-tl

FreeMarker、Velocity基于文本模板和数据生成新的HTML页面、配置文件等，poi-tl是Word模板引擎，基于Microsoft Word模板和数据生成新的文档。

Word模板拥有丰富的样式，poi-tl在生成的文档中会完美保留模板中的样式，还可以为标签设置样式，标签的样式会被应用到替换后的文本上，因此你可以专注于模板设计。

poi-tl是一种 "logic-less" 模板引擎，没有复杂的控制结构和变量赋值，只有标签，一些标签可以被替换为文本、图片、表格等，一些标签会隐藏某些文档内容，而另一些标签则会将一系列文档内容循环渲染。

"Powerful" constructs like variable assignment or conditional statements make it easy to modify the look of an application within the template system exclusively... however, at the cost of separation, turning the templates themselves into part of the application logic.

《Google CTemplate》

poi-tl支持自定义函数(插件)，函数可以在Word模板的任何位置执行，在文档的任何地方做任何事情(Do Anything Anywhere)是poi-tl的星辰大海。

Maven

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

2分钟快速入门

从一个超级简单的例子开始：把{{title}}替换成"poi-tl 模板引擎"。

1. 新建文档模板template.docx，包含标签{{title}}
2. TDO模式：Template + data-model = output

//核心API采用了极简设计，只需要一行代码
XWPFTemplate.compile("template.docx").render(new HashMap<String, Object>(){{
        put("title", "poi-tl 模板引擎");
}}).writeToFile("out_template.docx");

打开out_template.docx文档吧，一切如你所愿。

标签

标签由前后两个大括号组成，{{title}}是标签，{{?title}}也是标签，title是这个标签的名称，?标识了标签类型，接下来我们来看看有哪些标签类型。

文本

文本标签是Word模板中最基本的标签类型，{{name}}会被数据模型中key为name的值替换，如果找不到默认会清空标签，可以配置是保留还是抛出异常。

文本标签的样式会应用到替换后的文本上，正如下面的例子所示。

数据:

{
  "name": "Mama",
  "thing": "chocolates"
}

Word模板:

{{name}} always said life was like a box of {{thing}}.
{{name}} always said life was like a box of {{thing}}.

输出:

Mama always said life was like a box of chocolates.
Mama always said life was like a box of chocolates.

图片

图片标签以@开始，如{{@logo}}会在数据中寻找key为logo的值，然后将标签替换成图片。由于Word文档中图片不是由字符串表示(在文本型模板中，比如HTML网页图片是由字符串<img src="" />表示)，所以图片标签对应的数据有一定的结构要求，这些结构都会有相应的Java类对应。

数据:

{
  "watermelon": {
    "image": "assets/watermelon.png",
    "pictureType" : "PNG"
  },
  "lemon": {
    "image": "http://xxx/lemon.png",
    "pictureType" : "PNG"
  },
  "banana": {
    "image": "sob.png",
    "pictureType" : "PNG",
    "width": 24,
    "height": 24
  }
}

Word模板:

Fruit Logo:
watermelon {{@watermelon}}
lemon {{@lemon}}
banana {{@banana}}

输出:

Fruit Logo:
watermelon 🍉
lemon 🍋
banana 🍌

表格

表格标签以#开始，如{{#table}}，它会被渲染成N行N列的Word表格，N的值取决于table标签的值。

数据:

{
  "rows": [
    {
      "cells": [
        {
          "paragraphs": [
            {
              "contents": [
                {
                  "text": "Song name"
                }
              ]
            }
          ]
        },
        {
          "paragraphs": [
            {
              "contents": [
                {
                  "text": "Artist"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Word模板:

{{#song}}

输出:

Song name

Artist

列表

列表标签对应Word的符号列表或者编号列表，以*开始，如{{*number}}。

数据:

{
  "format" : {
    "lvlText" : "●"
  },
  "items" : [ {
    "contents" : [ {
      "text" : "Plug-in grammar, add new grammar by yourself"
    } ]
  }, {
    "contents" : [ {
      "text" : "Supports word text, local pictures, web pictures, table, list, header, footer..."
    } ]
  }, {
    "contents" : [ {
      "text" : "Templates, not just templates, but also style templates"
    } ]
  } ]
}

Word模板:

{{*feature}}

输出:

● Plug-in function, define your own function
● Supports text, pictures, table, list, if, foreach...
● Templates, not just templates, but also style templates

区块对

区块对由前后两个标签组成，开始标签以?标识，结束标签以/标识，如{{?sections}}作为sections区块的起始标签，{{/sections}}为结束标签，sections是这个区块对的名称。

区块对在处理一系列文档元素的时候非常有用，位于区块对中的文档元素(文本、图片、表格等)可以被渲染零次，一次或N次，这取决于区块对的取值。

False或空集合

如果区块对的值是null、false或者空的集合，位于区块中的所有文档元素将不会显示，类似于if语句的条件为false。

数据:

{
  "announce": false
}

Word模板:

Made it,Ma!{{?announce}}Top of the world!{{/announce}}
Made it,Ma!
{{?announce}}
Top of the world!🎋
{{/announce}}

输出:

Made it,Ma!
Made it,Ma!

非False且不是集合

如果区块对的值不为null、false，且不是集合，位于区块中的所有文档元素会被渲染一次，if语句的条件为true。

数据:

{
  "person": { "name": "Sayi" }
}

Word模板:

{{?person}}
  Hi {{name}}!
{{/person}}

输出:

  Hi Sayi!

非空集合

如果区块对的值是一个非空集合，区块中的文档元素会被迭代渲染一次或者N次，这取决于集合的大小，类似于foreach语法。

数据:

{
  "songs": [
    { "name": "Memories" },
    { "name": "Sugar" },
    { "name": "Last Dance(伍佰)" }
  ]
}

Word模板:

{{?songs}}
{{name}}
{{/songs}}

输出:

Memories
Sugar
Last Dance(伍佰)

在循环中可以通过一个特殊的标签{{=#this}}直接引用当前迭代的对象。

数据:

{
  "produces": [
    "application/json",
    "application/xml"
  ]
}

Word模板:

{{?produces}}
{{=#this}}
{{/produces}}

输出:

application/json
application/xml

嵌套

嵌套是在Word模板中引入另一个Word模板，可以理解为import、include或者word文档合并，以+标识，如{{+nested}}。

数据:

{
  "nested": {
    "file": "template/sub.docx",
    "dataModels": [
      {
        "addr": "Hangzhou,China"
      },
      {
        "addr": "Shanghai,China"
      }
    ]
  }
}

给定两个WordWord模板:

main.docx:
Hello, World
{{+nested}}

template/sub.docx:
Address: {{addr}}

输出:

Hello, World
Address: Hangzhou,China
Address: Shanghai,China

详细文档与示例

中文文档Documentation

• 基础(图片、文本、表格、列表)示例：软件说明文档
• 表格示例：付款通知书
• 循环和图表示例：野生动物现状
• 文本框示例：证书奖状
• Example：个人简历创作
• Example：Swagger文档

更多的示例以及所有示例的源码参见JUnit单元测试。

 

Contributing贡献

你可以有很多途径加入这个项目，不限于以下方式：

• 反馈使用中遇到的问题
• 分享成功的喜悦
• 更新和完善文档
• 解决和讨论Issue

建议和完善

参见常见问题，欢迎在GitHub Issue中提问和交流。

社区交流讨论群：Gitter频道

 

 

--------------------------------------------------

 

 

EasyExcel

github地址：https://github.com/alibaba/easyexcel

  

官方网站: https://yuque.com/easyexcel

常见问题

因为公司不方便用QQ，所以建议加钉钉群

JAVA解析Excel工具EasyExcel

Java解析、生成Excel比较有名的框架有Apache poi、jxl。但他们都存在一个严重的问题就是非常的耗内存，poi有一套SAX模式的API可以一定程度的解决一些内存溢出的问题，但POI还是有一些缺陷，比如07版Excel解压缩以及解压后存储都是在内存中完成的，内存消耗依然很大。easyexcel重写了poi对07版Excel的解析，能够原本一个3M的excel用POI sax依然需要100M左右内存降低到几M，并且再大的excel不会出现内存溢出，03版依赖POI的sax模式。在上层做了模型转换的封装，让使用者更加简单方便

64M内存1分钟内读取75M(46W行25列)的Excel

当然还有急速模式能更快，但是内存占用会在100M多一点 

相关文档

• 快速开始
• 关于软件
• 更新记事
• 贡献代码

维护者

玉霄、庄家钜、怀宇

快速开始

读Excel

DEMO代码地址：https://github.com/alibaba/easyexcel/blob/master/src/test/java/com/alibaba/easyexcel/demo/read/ReadTest.java

    /**
     * 最简单的读
     * <p>1. 创建excel对应的实体对象 参照{@link DemoData}
     * <p>2. 由于默认一行行的读取excel，所以需要创建excel一行一行的回调监听器，参照{@link DemoDataListener}
     * <p>3. 直接读即可
     */
    @Test
    public void simpleRead() {
        String fileName = TestFileUtil.getPath() + "demo" + File.separator + "demo.xlsx";
        // 这里 需要指定读用哪个class去读，然后读取第一个sheet 文件流会自动关闭
        EasyExcel.read(fileName, DemoData.class, new DemoDataListener()).sheet().doRead();
    }

写Excel

DEMO代码地址：https://github.com/alibaba/easyexcel/blob/master/src/test/java/com/alibaba/easyexcel/test/demo/write/WriteTest.java

    /**
     * 最简单的写
     * <p>1. 创建excel对应的实体对象 参照{@link com.alibaba.easyexcel.test.demo.write.DemoData}
     * <p>2. 直接写即可
     */
    @Test
    public void simpleWrite() {
        String fileName = TestFileUtil.getPath() + "write" + System.currentTimeMillis() + ".xlsx";
        // 这里 需要指定写用哪个class去读，然后写到第一个sheet，名字为模板 然后文件流会自动关闭
        // 如果这里想使用03 则 传入excelType参数即可
        EasyExcel.write(fileName, DemoData.class).sheet("模板").doWrite(data());
    }

web上传、下载

DEMO代码地址：https://github.com/alibaba/easyexcel/blob/master/src/test/java/com/alibaba/easyexcel/test/demo/web/WebTest.java

   /**
     * 文件下载（失败了会返回一个有部分数据的Excel）
     * <p>
     * 1. 创建excel对应的实体对象 参照{@link DownloadData}
     * <p>
     * 2. 设置返回的 参数
     * <p>
     * 3. 直接写，这里注意，finish的时候会自动关闭OutputStream,当然你外面再关闭流问题不大
     */
    @GetMapping("download")
    public void download(HttpServletResponse response) throws IOException {
        // 这里注意 有同学反应使用swagger 会导致各种问题，请直接用浏览器或者用postman
        response.setContentType("application/vnd.ms-excel");
        response.setCharacterEncoding("utf-8");
        // 这里URLEncoder.encode可以防止中文乱码 当然和easyexcel没有关系
        String fileName = URLEncoder.encode("测试", "UTF-8").replaceAll("\\+", "%20");
        response.setHeader("Content-disposition", "attachment;filename*=utf-8''" + fileName + ".xlsx");
        EasyExcel.write(response.getOutputStream(), DownloadData.class).sheet("模板").doWrite(data());
    }

    /**
     * 文件上传
     * <p>1. 创建excel对应的实体对象 参照{@link UploadData}
     * <p>2. 由于默认一行行的读取excel，所以需要创建excel一行一行的回调监听器，参照{@link UploadDataListener}
     * <p>3. 直接读即可
     */
    @PostMapping("upload")
    @ResponseBody
    public String upload(MultipartFile file) throws IOException {
        EasyExcel.read(file.getInputStream(), UploadData.class, new UploadDataListener(uploadDAO)).sheet().doRead();
        return "success";
    }