言

目前，教学、教研各种内容线上沉淀、展示丰富多彩，但线上内容“线下化”能力不足或过分依赖人力，比如，线上练习题组卷后以PDF形式分发给学生，家长希望将考试、练习题目打印后，学生带到学校去做（高中生使用手机等电子设备的时间有限），线上各类分析报告以PDF形式分享给学生/家长等。

从业务方面看，不同业务线的多个业务场景都有输出PDF的诉求，如果各业务线自己设计、实现符合自身业务场景的具体方案，除调研、开发工作量较大之外，还会有重复调研，踩坑的情况。

从技术角度看，线上内容转PDF的内容源头来自于H5富文本内容，业界内以此为基础的PDF生成方案多种多样，也各有优劣，比如：

方案对比-表格-1

因此，我们综合了各种PDF生成方案并总结了在探索讲义生成PDF过程中的经验，抽象出了一套通用的，可复用的能力供各业务线快速利用，基本方案和优劣如下：

最终方案-表格-2

目 标

旨在提供一套以H5为载体的PDF通用生成方案，这套方案有如下特点：

1. 通用性强：能够处理各类H5页面，从分页到生成，做到一套方案，多般兼容。
2. 扩展性、配置性强：各场景可根据自己的需要自定义页眉、页脚、页码，水印，背景等配置，做到输出形式丰富多彩。
3. 方便易接入：各业务场景只需关注要展现的内容，无需关注分页，PDF生成等背后的处理 ，为需要产出PDF的业务场景提效赋能；整体来看，调研、设计、开发（+踩坑）一整套 H5 转 PDF的能力至少需要近 30人/日，我们希望这套通用能力的接入成本控制在 7人/日左右；在很多场景接入后，从实际反馈来看，平均只需要 2-3 人/日就接入了。
4. 质量高：保证输出PDF中内容的展示与H5中无异，各种复杂公式的展示也丝毫无差错。
5. 性能好：保证 1 分钟内能处理 100+ 的 20页左右的PDF生成任务
6. 稳定性高：保证有各种兜底策略妥善处理各类异常，同时能够通过限流方案应对突发流量，保证服务稳定。

这套方案可分为两个核心部分，页面展示侧 - Medusa，PDF生成侧 - Hydra

页面展示侧 - Medusa

我们页面展示侧的通用能力——Medusa，是基于Paged.js的二次封装，并以NPM包形式提供给业务方使用。Medusa可对任何HTML进行分页、并根据配置添加页眉、页脚等，最终将处理后的HTML渲染到页面中。Medusa封装并简化了对PDF格式的配置，可覆盖绝大多数业务场景，使得各业务场景将更多精力投入其自身业务逻辑的开发。

之所以选择Pagedjs为基础开发我们自己的SDK，是因为它是目前我们能找到的唯一开源的、具有HTML内容分页，样式处理的前端库，同时我们也在讲义中经过了长期的摸索与沉淀。

接下来将详细介绍Paged.js原理、Medusa支持的功能与使用方法。

一 Paged.js是如何工作的

Paged.js包含了 3 个大模块

• Chunker（负责HTML内容分页）
• Polisher （负责CSS样式处理）
• Previewer （负责预览呈现Chunker和Polisher处理后的内容）
• 
  

这里将主要介绍 Previewer 和 Chunker，因为我们的二次开发和维护不涉及到Polisher。

Previewer

Previewer 的工作非常简单，但我们会主要利用它封装我们的Medusa，初始化一个Previewer对象，Previewer初始化了Chunker和Polisher对象：

Medusa-代码-1

再调用Previewer的preview()方法，preview()方法做了两件事：

1. 通过Polisher处理样式内容
2. 通过Chunker处理需要分页的HTML内容，如果没有指定需要分页的HTML，则会处理整个Body的内容

Medusa-代码-2

当chunker.flow结束，即可在浏览器看到整个页面处理完之后的样子。

Chunker

首先，Chunker解析、预处理需要分页的HTML，为其添加一些必要的属性

Medusa-代码-3

然后创建容纳所有页(pages)的容器，并挂载到renderTo容器下(默认Body)，以备组织后续的所有页：

Medusa-代码-4

接着，chunker创建了一个page模版，以便增加页面使用：

Medusa-代码-5

其中，TEMPLATE是Pagedjs内部创建页面时所使用的基础模版。

Medusa-代码-6

接下来，chunker进入了渲染+分页过程（这个过程我们不会在二次开发中做修改，但需要了解其基本思路以便在出问题时能有解决思路），这个过程在循环一个迭代器（*layout），迭代器一直在做3件事：

1. 将内容添加到模版内容区域的容器中 -> 渲染。
2. 探测overflow，找到overflow的offset并创建BreakToken （探测overflow过程中很多处都用到了迭代器，此处为了说明思路，简化了相关代码）。

原则：

寻找overflow时会将尽可能多的内容节点插入内容区域，这里，“尽可能多”分为几种情况，比如：

• 没有剩余节点需要再添加了
• 达到了一页所能承载的最大字符数；刚开始的时候，如果没有指定每页的最大字符数，Pagedjs会给一个默认值为 1500 的每页最大字符用做判断，在之后会记录分隔好的每一页中的字符数，并取最近4页 （少于4页取全部）的平均值作为之后分页的判断条件，这里，Pagedjs相当于对每一页中能够承载的内容做了一个简单的预测，这个算法对于比较规律的内容做分页时还是比较简单高效的。
• 
  

步骤：

Pagedjs遵循了如下步骤去寻找overflow：

两个前置条件：

• 内容区域盒子边界已经确定，下面以contentArea.right 和 contentArea.bottom 分别代指其右边界和下边界。
• 处理过程中每个节点的边界可以计算（对于文字节点，Pagedjs中使用了Range对象为其创建边界），下面以 node.left、 node.right、node.top 和 node.bottom 分别代指节点的左、右、上、下边界。

i. 从需要处理的内容第一个节点开始，判断是否 node.left >= contentArea.right || node.top >= contentArea.bottom

Medusa-代码-7

ii.如果不满足，则判断 node.right <= contentArea.right && node.bottom <= contentArea.bottom

Medusa-代码-8

iii.如果不满足，那说明有子节点overflow了，则继续深入其子节点查找即可。

3.使用模版添加新的页面，并从BreakToken处继续上述动作。

二 Medusa支持的功能及使用方法

基于Paged.js，Medusa支持了如下功能，并为业务方提供了更加简洁、定制化的配置。

1. 动态页面分页能力
2. 单页模版配置 -> 生成能力
3. 前、后置静态页面生成、与分页后的动态页面拼接能力
4. 页面处理成功后，通知PDF生成服务(Hydra)执行任务

下方是调用Medusa的代码示例：

Medusa-代码-9

1.1 动态页面分页能力

Medusa核心功能，可将连续的HTML页面转化成一页页PDF样式的HTML。

1.2 单页模版配置 -> 生成能力

通过Grid布局，Paged.js将一个单页模版分为多个区域，整体分为2个大的部分：

1. base 页面基础配置：每个PDF纸型、水印，内容区域的宽高、margin与padding等等
2. surround 页面周围区域：如页眉、页脚等配置

业务方通过简单的配置，即可还原UI设计稿中的PDF样式，例子如下图：

1.2.1 base

页面基础配置是对每页的。支持纸型或页面宽高、内容区域margin、padding、背景及水印的设置。

在封装Medusa时，Medusa将读取传入的页面模版配置、静态页内容配置，并将样式上的配置解析并转化为Previewer可理解的样式内容，比如页面宽高的设置：

Medusa-代码-10

将被转化为：

Medusa-代码-11

1.2.2 surround

1. 可以看到图中的16种不同位置的surround区域。通过设置position，可将业务方自定义的元素渲染到对应的位置上。

2. 目前支持3种类型的surround item:

• text 文字
• img 图片
• pageNum (动态获取)当前页码

example:

Medusa-代码-12

1.3 前/后置静态页面

业务方可通过如下方式配置静态页面的具体内容：

Medusa-代码-13

其中，传入的React JSX Element将会被这样处理：

Medusa-代码-14

处理完成后，将HTML String拼接到页面模版中，再插入分页后内容的前后。

PDF生成侧 - Hydra：

页面展示侧为PDF生成做好了页面的准备，对于PDF生成侧，需要做的工作就更纯粹了，业务方除了请求生成PDF，定期检查PDF生成的进度，无需做任何额外工作。

1.整体流程：

PDF生成是CPU和内存密集型的，由于页面内容的不确定性，也意味着页面渲染时间与生成PDF的时间都是不确定的，因此整体PDF生成的链路被设计成是异步的，如下图：

整体流程上，业务方在请求生成PDF时，会先在后端做一条记录，后端再将任务发送给Node服务，即Hydra；

在生成PDF时， 第 1 步是做页面上的准备，一个生成任务可能有多个URL页面需要生成PDF，所以我们预先启动对应URL数量的PPTR Page，页面都启动完成后，进入下一步；

第 2 步：渲染页面，这个过程中，如果请求是包含多个URL的，这些页面会同步渲染，在所有页面渲染完成后，进入下一步。

第 2.5 步，如果是需要生成连续页码的一整个PDF，还会做额外的一个动作：页码矫正，通过页码矫正，可以将同步渲染的每个页面，按照其之前页面的页码数修正，以保证整体PDF的页码的连贯。

第 3 步，通过PPTR Page的能力将页面转换为PDF buffer，如有必要，再将生成的PDF buffer拼接到一起生成一整个PDF，或者将每个PDF buffer都生成一个PDF，压缩成zip文件。

第 4 步，文件上传OSS，最终返回OSS CDN链接。

2.请求生成PDF：

业务侧请求将对应页面生成PDF的时，只需传入如下字段：

Hydra-代码-1

3.PDF生成过程：

正如在整体流程中所述，PDF生成侧，我们借助 PPTR 的能力打开页面并生成PDF流。

在页面调用 Medusa 分页、组装能力时，所有内容分页组装完成后会向body中插入了一个额外的DOM以标识该页面处理完成：

Hydra-代码-2

这是为了 Hydra 感知页面渲染完成所做的准备，当生成服务的 PPTR 等到该DOM出现时，则表示页面成功渲染并处理完成了：

Hydra-代码-3

此后，在上面已经提到过，对于需要将多个页面生成的PDF拼接成一个PDF的情况，在生成PDF之前需要做一个重要的动作，即页码矫正，原因如下：

1. 每个页面无法感知其他页面情况的，如：第二个页面不知道第一个页面会生成多少页的PDF。
2. 它们的页码需要是连续的。

并且我们不希望页面的处理是串行的，因为串行势必导致速度较慢，生成时间长。

这个问题的解决方案如下：

1. 对于每个页面都启用一个page，并同时处理

2. 每个页面处理完成后（pdfLastDOM出现），通过Page.$eval()来统计页数并记录:

Hydra-代码-4

3. 计算出页面中分页之后每一个页面的起始页码，以及所有页面的页码总和

4. 再修改页码容器样式的 counterReset 值即可，其后续页码可自递增。

Hydra-代码-5

5. 之后，再通过 Medusa 在页面window对象中Polyfill的相关配置，比如需要生成的PDF的单页宽、高以生成PDF流。

Hydra-代码-6

6. 最后如有必要，通过pdf-lib拼接这些 pdfBuffer 即可。

Hydra-代码-7

7. PDF生成完成后，上传OSS并返回URL链接

4.性能、稳定性保证：

在整体方案落地前，我们对服务进行了多次性能测试：

以下载题目为例，在4个容器，每个容器 3C 12G 的配置下的并行处理能力如下：

对于 20 道题目，每个PDF生成任务在 15 页左右，平均 1 分钟内能完成 280 个任务的处理。

对于 40 道题目，每个PDF生成任务在 30 页左右，平均 1 分钟内能完成 105 个任务的处理。

对于 60 到题目，每个PDF生成任务在 40 页左右，平均 1 分钟内能完成 54 个任务的处理。

同时，根据 Hydra 服务的整体的处理能力，后端通过任务队列的形式帮助我们保证服务不被瞬间的突刺流量击垮。

已接入/正在接入的相关业务线及场景：

目前，公司有 5 大业务线，8 个场景已经完全接入我们的能力用于 H5 转 PDF，如下是错题本、内容资料库接入后生成的PDF样例：

错题本：

内容资料库试卷：

未来展望

目前整体的PDF生成方案已经能够满足大多数场景和内容，但依然有可改进空间。

HTML的流式布局要求我们必须手动的对内容分页，才能添加页眉，页脚等（即Mdusa做的工作），正因为如此，在处理复杂的内容时，可能会出现一些问题：比如，遇到复杂表格时，由于表格可能会有多种多样的行、列合并，同时表格单元格内的内容也可以多种多样，在分页过程中，Medusa内部的PagedJS并不能完美的处理对于长、且复杂的表格的分割，因此可能遇到分割后表格单元格缺失、错乱或宽高错误的问题，这些问题在讲义中体现较明显。

我们仍在持续关注与研究复杂DOM内容的分割问题，会尝试加以优化和改进PagedJS的能力，同时，我们也以另外一种思路设计了自己的DOM分页器方案，但经过评估，由于实现比较复杂，成本较高，暂时没有投入开发资源。

不过，我们相信，未来我们一定能以更完美的方式分割DOM以生成更高质量的PDF。

作者:高源、陈欣博

来源:微信公众号:高途技术

出处:https://mp.weixin.qq.com/s/c_N7jdNklrNFKR_Cub2Tgg

言

好东西要分享，之前一直在使用wkhtmltopdf进行pdf文件的生成，常用的方式就是先安装wkhtmltopdf，然后在程序中用命令的方式将对应的html生成pdf文件，简单而且方便；但重复的编码使得想在wkhtmltopdf基础上进行封装，偶然间发现有小伙伴已经封装的还不错啦，常用的功能都已经实现，源码地址：https://github.com/fpanaccia/Wkhtmltopdf.NetCore。

作者将其打包成Nuget包(Wkhtmltopdf.NetCore)，直接引入使用即可；

正文

既然用到了.NetCore，肯定就要考虑到跨平台兼容性，对于wkhtmltopdf之前一直是在Windows上使用，还没有在其他平台尝试；这个包封装的行不行，拉出来遛遛就知道啦，接下来就试试：

1. 建个API项目，引入包和兼容对应平台的wkhtmltopdf执行文件；

注： 默认依赖的wkhtmltopdf执行文件需要存放在Rotativa目录下，可以自定义名称，如果自定义，需要再注册服务时指定对应的文件名；这里的wkhtmltopdf已经根据不同平台进行编译打包了，无需安装，这些文件在源码那就有；

2.创建PDFTestController控制器，添加如下接口进行测试；

首先把生成pdf的服务注入进来，后续直接使用就可以啦：

接下来就开始写接口啦，这里只是测试，代码冗余没有考虑，在实际项目中小伙伴可以根据自己需求进行封装；

• ExportPDFByHtml 接口，用html直接生成pdf文件，但这里没有保存，以文件流的形式访问，通过浏览器查看文件，可以自行下载；html模板在实际开发过程中可以单独用文件存储；

• SavePDFByHtml接口，直接保存文件，文件名可以根据需要进行自定义；

• TestMarginAndPageSize接口，设置Margin和PageSize参数，其他参数也可以设置；

ConvertOptions默认封装了以下属性，小伙伴也可以自定义扩展，只要继承IConvertOptions即可，这里就不演示的，因为官方有对应的案例，下伙伴下去搞搞，wkhtmltopdf的参数挺多的，都可以进行封装使用。

• ExportByRazorView使用Razor视图的方式进行pdf文件生成，此库已经支持cshtml文件的读取

根据指定视图生成对应的pdf效果，如下：

• ExportByRazorViewData数据动态绑定，既然支持视图，那就应该支持Razor语法，一般常用的就是数据绑定了，上面是静态的，接下来来个动态绑定的。

根据指定视图生成对应的pdf效果，如下：

如上基本的使用演示就说那么多，使用还是很简单，小伙伴后续可以根据自己的需要进行相关扩展；当然还有其他功能，比如设置页眉/页脚等，作者提供有对应的案例；这里不说那么多，不然又是长文。

3. 小伙伴用的时候可能会遇到的问题

• 在开发调试运行项目时，会报找不到wkhtmltopdf文件，那是因为运行时的确找不到对应的文件，将对应Rotativa下的文件设置为始终复制即可：

• 在Windows下怎么玩都没问题啦，开始发布到Linux(我用的centos 7)，我擦，莫名其妙的错。

看见这个错我懵的，一顿搜索猛如虎，还是没找到答案；冷静下来，重新捋捋，原来是自己在犯傻；

两个问题需要解决，1.上传到Linux下的wkhtmltopdf没有给执行权限；2.可能环境缺少对应的依赖库；

设置可执行权限

在Linux环境下，可以通过ll命令查看权限，刚开始是没有权限的，只需要执行chmod 777 wkhtmltopdf命令，执行权限就有了，如下图中红框中的x就是可执行权限；关于Linux常用命令后续单独整理一篇分享吧，这里先不延伸。

安装缺少的依赖库

可执行权限开启之后，别急着去访问页面，这样可能还是错误。因为可能缺少依赖库，那咋知道缺少呢，我是直接执行wkhtmltopdf，执行成功就没啥，不成功就会报缺少相关依赖，然后直接安装就行啦；执行./wkhtmltopdf https://www.baidu.com ./test.pdf试试就知道啦，因为wkhtmltopdf本身是可以单独运行的，并不依赖我们写的程序。

• 当执行成功之后，然后开始访问接口导出功能，如果不出意外，遇到中文就产生乱码啦，那是因为Linux环境下缺少相关的字体文件，将对应的字体文件拷贝到Linux上即可，字体我找好了，下载地址如下：

链接: https://pan.baidu.com/s/1jikC0DUkpEzpXL5ysjEQPA 提取码: tn4j ；

将下载下来的字体解压，然后拷贝到Linux下的 /usr/share/fonts目录下即可

最后这样应该就没啥问题啦，剩下的就交给小伙伴自己摸索搞实践吧；

此文源码地址：https://github.com/zyq025/DotNetCoreStudyDemo

wkhtmltopdf官网地址：https://wkhtmltopdf.org/

总结

使用还是很简单的，常规的需求没啥问题，如果需要功能定制化，小伙伴可以参考源码，自己封装一个(封装思路不难的)； 如果小伙伴有比较好的导出库，免费开源的那种，一起分享出来玩玩。

感谢小伙伴的：点赞、收藏和评论，下期继续~~~

一个被程序搞丑的帅小伙，关注"Code综艺圈"，跟我一起学~~~

tml作为一种网页的通用格式，被广泛地应用于计算机工作的方方面面。对于一些网页编辑员来说，为了节约建站的开发时间，会在网上搜索一些开源代码直接进行修改使用，但是有的代码是PDF格式，没办法进行编辑修改，要是能将PDF转换成HTML就好办了。

其实要想完成这一操作只需要用到风云PDF工具集就可以轻松地解决。

不过，有的PDF转换器需要安装体积较大的安装包，而且转换速度也很慢。因此，选择对的PDF转换器可以大大提高我们的工作效率，同时也能保障文件的安全性。

那么究竟如何在数秒内实现PDF转换成HTML呢？一起来瞧瞧吧~

使用教程

1.web端

（1）下载风云PDF转换器到桌面上，打开软件之后点击首页「PDF转HTML」，软件支持批量转换PDF文件。

（2）将文件拖入添加框或直接点击选择本地文件；

（3）稍等片刻显示上传完成时，点击“开始转换”，一般文件3M内15秒内提示转换完成

（4）点击“打开文件”可查看文件转换后的效果。转换后的文件也会保存到输出目录处。

2.APP端

（1）下载安装「风云PDF转换器」APP，

（2）可在首页中选择「PDF转HTML」功能，之后选择PDF文件进行转换。

好啦，风云PDF转换器有PC端和手机端的，当我们有转换PDF需求的时候，无论是用电脑还是手机都可以 可以轻松进行转换，有需要的小伙伴们可以用起来啦~