HTML 2 PDF通用能力的设计与实现

目前，教学、教研各种内容线上沉淀、展示丰富多彩，但线上内容“线下化”能力不足或过分依赖人力，比如，线上练习题组卷后以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，是基于Paged.js的二次封装，并以NPM包形式提供给业务方使用。Medusa可对任何HTML进行分页、并根据配置添加页眉、页脚等，最终将处理后的HTML渲染到页面中。Medusa封装并简化了对PDF格式的配置，可覆盖绝大多数业务场景，使得各业务场景将更多精力投入其自身业务逻辑的开发。

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

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

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)，以备组织后续的所有页：

接着，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处继续上述动作。

基于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生成做好了页面的准备，对于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。