Poi-tl Documentation

Apache POI不仅在上层封装了易用的文档API(文本、图片、表格、页眉、页脚、图表等),也可以在底层直接操作文档XML结构,正是一个基于Apache POI的Word模板引擎,并且拥有着让人喜悦的特性。

条形图(3D条形图)、柱形图(3D柱形图)、面积图(3D面积图)、折线D折线D饼图)等图表数据渲染

poi-tl是一个免费开源的Java类库,你可以非常方便的加入到你的Java项目中。

所有的标签都是以{{开头,以}}结尾,模板标签可以出现在任何位置,包括页眉,页脚,表格内部,文本框等等。poi-tl遵循“所见即所得”的设计,模板的样式会被完全保留,标签的样式也会应用在替换后的文本上。

FreeMarker、Velocity文本模板中可以通过三个标签设置图片路径、宽和高:

但是Word模板不是由简单的文本表示,所以在渲染图片、表格等元素时提供了数据模型,它们都实现了接口RenderData,比如图片数据模型PictureRenderData包含图片路径、宽、高三个属性。

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

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

图片标签无法设置环绕版式和样式,如果对环绕版式有更高的要求可以采用替换占位图片方式:参见引用标签-图片,或者完全自定义图片插件:参见插件-开发一个插件。

poi-tl默认实现了N行N列的样式(如下图),同时提供了当数据为空时,展示一行空数据的文案(如下图中的No Data Descs),数据模型是

: 模板中已经有一个表格,我们只想动态的处理表格的某一部分数据,poi-tl提供了

方案三: 编写插件,完全由自己生成整个表格,这个方案需要你熟悉Apache POI XWPFTable相关API,但是自由度最高:参见插件-开发一个插件。

区块对由前后两个标签组成,开始标签以?标识,结束标签以/标识:{{?sections}}{{/sections}}

,且不是集合,位于区块中的所有文档元素会被渲染一次,这就等同于if语句的条件为

在循环中,有一个特殊的变量#this可以直接引用当前迭代的对象。由于#和已有表格标签标识冲突,所以在文本标签中需要使用=号标识来输出文本。

segment.docx是一个包含了{{title}}和{{content}}的子模板,使用subData集合渲染后合并到主模板

引用标签是一种特殊位置的特殊标签,提供了直接引用文档中的元素句柄的能力,

这个重要的特性在我们只想改变文档中某个元素极小一部分样式和属性的时候特别有用,因为其余样式和属性都可以在模板中预置好,真正的所见即所得

引用图片标签是一个文本:{{var}},标签位置在:设置图片格式可选文字标题(高版本office标签位置在:编辑替换文字-替换文字)。

多系列图表指的是条形图(3D条形图)、柱形图(3D柱形图)、面积图(3D面积图)、折线D折线图)、雷达图等。

多系列图表的标签是一个文本:{{var}},标签位置在:图表区格式可选文字标题(高版本office标签位置在:编辑替换文字-替换文字)。

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

由于这八个插件如此通用,因此将这些插件注册为不同的标签类型,从而搭建了poi-tl的标签体系,也构筑了poi-tl高度自由的插件机制。

插件的实现就是要告诉我们在模板的某个地方用某些数据做某些事情,我们可以通过实现

随心所欲的意思是原则上Apache POI支持的操作,都可以在当前标签位置进行渲染,Apache POI不支持的操作也可以通过直接操纵底层XML来实现。

ConfigureBuilder采用了链式调用的方式,可以一次性设置多个标签的插件:

源码参见JUnit HackLoopTableRenderPolicyTest

接下来的示例采取三段式output+template+data-model来说明,首先直接展示生成后的文档,然后一览模板的样子,最后我们对数据模型作个介绍。

需要生成这样的一份软件说明书:拥有封面和页眉,正文含有不同样式的文本,还有表格,列表和图片。下载最终生成的文件poi_tl.docx

默认表格数据模型(MiniTableRenderData)实现了最基本的样式,当需求中的表格更加复杂的时候,我们完全可以设计好那些固定的部分,将需要动态渲染的部分单元格交给自定义模板渲染策略。

的用法,示例中货物明细和人工费仅仅是循环渲染表格行,使用HackLoopTableRenderPolicy插件会更方便。

将表格放到区块对中,当区块对取值为空集合或者null则不会展示目标表格,当区块对是一个非空集合则循环展示表格。

不确定动物种类使用区块对{{?animals}}的循环功能实现,图片和图表如模板所示,使用引用标签,在可选文字标题位置输入标签。

因为模版即样式,模版引擎无需考虑样式,只关心数据,我们甚至可以制作10种不同样式的简历模板,用同一份数据去渲染。

如果你觉得它节省了你的时间,给你带来了方便和灵感,或者认同这个开源项目,可以为我的付出打赏点小费哦(

标签:

发表评论

电子邮件地址不会被公开。 必填项已用*标注

Related Post

鸿宝资源(01131):Tiger Courage的采矿业务及运营管理未发生变动

于2020年2月24日,公司已取得来自第三贷方的保证,尽管已委任Tiger Courage及质押股份接管人,但 […]

KPLRW侠花满楼要退役?不去训练却打五排车队水友:不如转去QG

说起RW侠大家会想起什么?是他们每个人武侠小说般的名字还是像莽夫一样敢打敢拼的风格,其实RW侠从进入kpl以来 […]

英雄联盟:没有Faker的SKT会变成什么样?

【导读】英雄联盟:没有Faker的SKT,会变成什么样? Faker目前所在的战队T1(原SKT)地位已经逐渐 […]