43 Star 424 Fork 153

Rayin / rayin

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
Apache-2.0

睿印

Hex.pm Hex.pm Hex.pm
Hex.pm Hex.pm Hex.pm Hex.pm Hex.pm Hex.pm Hex.pm Hex.pm Hex.pm

中文 |English

睿印是什么

可以应对复杂显示、模板组合业务场景的电子凭证批量生成工具。

项目起源和痛点

某大型公司的内部项目的启发而来。
项目过程中发现的问题:

  1. 版式设计不方便:原有针对PDF的模板制作方式复杂,依赖某A的工具,而从系统层面通过该模板实现的生成逻辑复杂,而绑定数据项也是比较繁琐。
  2. 扩展性不好:系统虽然实现模板配置,但是由于依赖大量固定坐标,扩展性很差,对模板上面的元素调整是一件十分痛苦的事情,模板制作的时间成本以及需要对系统的熟悉的成本很高。
  3. 可维护性差:由于扩展性差,因此很多依赖硬代码去实现,维护性很差。
  4. 个性化应对困难:业务场景的个性化多,进而带来衍生大量的模板,一旦发生业务变动,所牵涉的模板变动工作量巨大。
  5. 生僻字问题:经常会遇到人名字库不支持,导致生成的文档错误。 以上问题要想让普通的业务人员通过自服务方式去实现模板的制作就不太现实。 因此基于以上问题,去解决如何更方便快捷的进行PDF模板的配置,如果能够更好支持扩展性以及多变的业务场景。

项目过程

从2019年项目至于开始构思设计,断断续续。也是做了一些尝试,反复测试,反复修改。 项目需求中遇到很多新的需求,尤其是不同的省份可能会有不同的个性化样式需求,以及不同的个性穿插内容,如果产品类型多,又存在个性化,那应对的模板将是指数级别的增长。
项目中变更的需求,如果模板过多,对于一个变更的需求是一件很痛苦的过程,并且很容易遗漏。
因此不断测试尝试能够覆盖的需求点,通过配置的方式尽可能简化的方式满足多样的需求。

达到目标

扩展性、灵活性、低代码。 基于上面的目标实现分层设计,逐层消化多变的个性化需求,从而减少模板的数量。 通过"数据规则"-"构件"-"模板"三层结构尽量通过配置来解决业务场景,而非硬代码来处理。

  • 数据规则:处理数据业务逻辑,可通过数据相关的规则引擎去完成,包括数据的延展,数据的转换,以及通过规则进行指定模板或者动态拼接模板。
  • 构件:解决数据与样式的结合,样式的展现,样式的扩展;
  • 模板:解决设计过程中的构件的复用,页码,空白页,针对大型打印机的纸盒选择问题。

综上:三位一体多个环节的动态配置,解决业务多变性场景。

样例展示

字体演示

版式样图

基于工具包实现的设计管理端展示

构件设计

模板编辑与预览

模板文件生成

关于html转PDF技术成熟度

网上有一些文章针对网页转PDF进行了一些开源组件的转换测试,其实在大部分场景下文档类并不需要类似网页那么复杂的样式需求,并且网页会存在很多动态的js(而且有些网页的html并不一定规范),即使有也可以通过其他的支持标签去实现,并且文档类并不需要类似js的处理逻辑和动态效果。

睿印概念

数据规则

数据规则为辅助工具包对数据的转换,通常源系统的数据如果不符合生成的要求或者为了某些特殊业务需要定制数据时,可通过数据规则脚本进行转换,实现场景可配置化,降低硬代码,增强灵活性。

构件定义

构件是PDF模板设计中的子模板,即将一个PDF拆分成多个块进行设计,最终的模板配置是由多个构件组成。
构件作用

  1. 增强复用性,降低重复的模板制作,当以个业务场景中的某一块内容出现不同时,不需要重新取制作模板,只需要将不同的模块替换重新组合即可。对于一些传统行业地域需求尤其突出,如果无法很好复用将出现模板灾难。
  2. 可根据后续实际需求对其进行处理,例如针对某一个子模块页面需要增加处理。还有就是方便将子模块映射至不同的打印机纸盒,应对大型打印机的打印需求.
  3. 可灵活控制其空白页填充以及页码的设置需求。

模板定义

上面说到,模板就是一个或多个构件的组合拼接,模板配置是自定义的一套JSON Schema,主要是构件的组合列表以及相关的页码、空白页、构件类型相关设置。
模板可以是配置文件,也可以是动态拼接的JSON数据。可以依据实际的业务逻辑进行动态的JSON数据拼接,来实现模板中灵活的构件组合。

主要的开源框架一览

PDFBOX

官网:https://pdfbox.apache.org/

thymeleaf 官网

https://www.thymeleaf.org/index.html
类似freemaker的动态脚本,好处是直接打开html,浏览器可以正常解析,不破坏html结构,在设计预览比较重要。

openhtmltopdf

https://github.com/danfickle/openhtmltopdf

Adobe Fonts 思源字体

https://github.com/adobe-fonts

google Fonts noto-cjk

https://github.com/googlefonts/noto-cjk

阿里普惠字体

https://fonts.alibabagroup.com/#/font

W3C CSS

https://www.w3.org/TR/css-page-3/
主要针对@page 样式的设置,通用样式基本支持,css2基本支持,css3部分支持。

项目结构

  1. rayin-htmladapter-base 基础类包
  2. rayin-tools 工具类
  3. rayin-htmladapter-openhtmltopdf openhtmltopdf生成pdf核心包
  4. rayin-htmladapter-spring-boot-starter springboot启动适配
  5. rayin-test 测试样例
  6. rayin-springboot-sample springboot 样例
  7. rayin-datarule 数据规则工具包

列举一些实现功能与特性

  1. 以下罗列为openhtmltopdf支持的CSS生成电子文件常用的特性:
    1. 支持自动扩展,包括表格,长文本;
    2. 支持表格头尾分页保留头尾;
    3. 支持CSS2.0 以及 3.0部分样式;
    4. 支持 @Page 媒体特性,即纸张大小定义,Page盒模型(页四周显示);
    5. 支持图片本地加载,http/https等协议的加载显示,图片的base64显示;
    6. 支持目录标签;
    7. 支持二维码和条形码的显示。
  2. 以下罗列部分thymeleaf动态数据绑定生成电子文件常用的特性:
    1. 动态数据绑定;
    2. 数据多层嵌套循环;
    3. 显示块整体循环,table,div;
    4. 数据格式化;
    5. 表达式,逻辑判断,例如显示逻辑判断;
    6. 国际化。
  3. 通过构件->模板 + 数据规则->数据,灵活配置生成PDF.
  4. 模板中可以对不同尺寸的构件进行组合,例如A4+B5+A3.
  5. 实现构件类型自定义配置(主要用于后续大型打印机的纸盒识别,可通过模板配置后,绑定至PDF对应的元数据中,通过读取再加工转换为PS文件指定至对应的纸盒).
  6. 实现构件空白页填充(奇数页构件补空白页).
  7. 实现页码灵活计数,页码灵活显示,支持构件重计数,单页显示多页码.
  8. 自动加载字体,支持多字体联动显示,生僻字显示.
  9. 实现pdf元数据的保存与获取,通过模板生成的PDF,元数据中包括页码信息,隐藏标签页码坐标,可用于后续加工使用。
  10. 实现pdf嵌入.
  11. 实现隐藏标记,并可通过元数据进行获取对应页码,坐标(可用于后续再加工的定位,例如签章位置)。
  12. 实现线程池。
  13. 集成简便,可单独引用jar包,也可与服务集成。

项目地址

Gitee : https://gitee.com/Rayin/rayin
GitHub: https://github.com/pipti/rayin

开始使用

  • 第一步:新建项目,引入依赖包
    如果使用阿里云最新的版本可能会存在同步滞后,如果不能自动下载可使用原始的maven源。
   <!-- ${rayin.version} 为版本号  -->
   <dependency>
       <groupId>ink.rayin</groupId>
       <artifactId>rayin-htmladapter-openhtmltopdf</artifactId>
       <version>${rayin.version}</version>
   </dependency>
  • 第二步:创建构件(即单个html)

  • 第三步:创建模板(即json配置文件) 具体参见 帮助手册

  • 第四步:调用生成API

    PDFGeneratorInterface pdfGenerator = new OpenHtmlGenerator();
    pdfGenerator.init();
    
    //单个构件生成,数据参数可以为空
    pdfGenerator.generatePdfFileByHtmlAndData(htmlLocation, jsonData, outputFilePath);

    //通过模板定义生成,数据参数可以为空
    pdfGenerator.generatePdfFileByTplConfigFile(templateLocation, jsonData, outputFilePath);

v1.0.6 以上版本 新增数据规则处理

可以对数据进行规则转换,模板配置动态生成。
参见:数据规则帮助

详细使用说明请参见帮助文档

帮助文档

⭐⭐⭐⭐⭐

如果觉得项目不错,麻烦给个⭐️star噢,你的⭐️就是我前进的动力!
程序问题或者使用问题可加群或提交issue!
程序难免存在问题,欢迎提出问题以及宝贵的建议!
如果你有好的需求和建议,也欢迎提出!

测试样例以及共享行业样例模板

所有测试样例包含在该项目中
https://gitee.com/Rayin/rayin-template-sample

本项目采用Apache 2.0许可,请尊重开源项目作者,在软件中附带睿印开源软件许可。

收费版本

支持css3(flex等) 支持js 支持echarts img.png 具体参见:收费版本说明

免责申明:

任何直接或间接因使用睿印生成的任何内容所导致的全部后果与睿印的开发者无关,内容不限于字体,图片,文字等相关内容。

交流群

微信二维码七天有效期刷新比较麻烦,企业微信省事,无需下载企业微信,可微信扫码

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

简介

睿印 PDF pdf html to pdf PDFBOX HTML PDF生成 json数据 基于HTML+CSS作为底板样式设计的批量PDF生成工具,通过自定义模板配置,减少复杂业务场景下模板的制作数量,提高底板的复用。 展开 收起
Java 等 4 种语言
Apache-2.0
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
Java
1
https://gitee.com/Rayin/rayin.git
git@gitee.com:Rayin/rayin.git
Rayin
rayin
rayin
release-1.1.3

搜索帮助