育機(jī)構(gòu)在做定制化軟件開(kāi)發(fā)的時(shí)候，會(huì)遇到這樣一個(gè)問(wèn)題：機(jī)構(gòu)需要定制自己的錯(cuò)題本封面和封底，并且題目界面需要有各種便簽可供學(xué)生標(biāo)記，例如下面這個(gè)圖：

要顯示這樣的錯(cuò)題界面，如果用word形式，一種辦法是通過(guò)html轉(zhuǎn)換成word，但是這樣會(huì)導(dǎo)致部分理科題目無(wú)法顯示的情況；另一個(gè)辦法是直接在word中顯示html，這種形式其實(shí)還是html，體驗(yàn)不太好，打印出來(lái)也會(huì)出問(wèn)題。所以我們采取的是通過(guò)PDF的形式展示這種格式，并且還可以定制封面和封底：如下圖:

因?yàn)镻DF是比較好的打印格式，不會(huì)出現(xiàn)混亂的情況，所以目前就是怎么解決html完美轉(zhuǎn)換成PDF的問(wèn)題。

我們嘗試了很多插件以后，最終發(fā)現(xiàn)下面這2個(gè)工具比較合適：wkhtmltopdf和phantomjs，下面分別試一下他們的效果：

• wkhtmltopdf：下載完成后需要添加到環(huán)境變量才能在代碼中使用，比如我們使用的是PHP，就可以通過(guò)shell_exec執(zhí)行命令行。通過(guò)官網(wǎng)我們知道wkhtmltopdf還是非常強(qiáng)大的，可以設(shè)置頁(yè)面為A3或者A4格式，可以設(shè)置頁(yè)眉頁(yè)腳，也可以設(shè)置字間距，字體，邊框等，能滿足大部分的轉(zhuǎn)換需求，但是wkhtmltopdf也有他的缺點(diǎn)，就是對(duì)于js渲染后的頁(yè)面轉(zhuǎn)換后顯示不太友好。對(duì)于我們的需求而言，要解決的難點(diǎn)就是理科公式的問(wèn)題，因?yàn)槲覀兊膌atex公式基本都是js渲染后才顯示。后來(lái)發(fā)現(xiàn)wkhtmltopdf有一個(gè)參數(shù)就是可以設(shè)置等待時(shí)間，最終我們?cè)O(shè)置等待5秒在導(dǎo)出，就解決了latex導(dǎo)出PDF的問(wèn)題，并且實(shí)現(xiàn)了完美的打印

• phantomjs：使用方法都差不多，只是phantomjs需要通過(guò)js來(lái)配置參數(shù)。一樣的需要先添加phantomjs到環(huán)境變量，然后通過(guò)代碼執(zhí)行命令行實(shí)現(xiàn)，也可以設(shè)置加載時(shí)間來(lái)實(shí)現(xiàn)js對(duì)html的渲染，只是phantomjs沒(méi)有wkhtmltopdf轉(zhuǎn)換專業(yè)。

本文希望通過(guò)自己的開(kāi)發(fā)經(jīng)驗(yàn)，減少教育軟件開(kāi)發(fā)者的坑。可以通過(guò)下面這個(gè)網(wǎng)站進(jìn)行測(cè)試：http://www.widomk12.cn

言

目前，教學(xué)、教研各種內(nèi)容線上沉淀、展示豐富多彩，但線上內(nèi)容“線下化”能力不足或過(guò)分依賴人力，比如，線上練習(xí)題組卷后以PDF形式分發(fā)給學(xué)生，家長(zhǎng)希望將考試、練習(xí)題目打印后，學(xué)生帶到學(xué)校去做（高中生使用手機(jī)等電子設(shè)備的時(shí)間有限），線上各類分析報(bào)告以PDF形式分享給學(xué)生/家長(zhǎng)等。

從業(yè)務(wù)方面看，不同業(yè)務(wù)線的多個(gè)業(yè)務(wù)場(chǎng)景都有輸出PDF的訴求，如果各業(yè)務(wù)線自己設(shè)計(jì)、實(shí)現(xiàn)符合自身業(yè)務(wù)場(chǎng)景的具體方案，除調(diào)研、開(kāi)發(fā)工作量較大之外，還會(huì)有重復(fù)調(diào)研，踩坑的情況。

從技術(shù)角度看，線上內(nèi)容轉(zhuǎn)PDF的內(nèi)容源頭來(lái)自于H5富文本內(nèi)容，業(yè)界內(nèi)以此為基礎(chǔ)的PDF生成方案多種多樣，也各有優(yōu)劣，比如：

方案對(duì)比-表格-1

因此，我們綜合了各種PDF生成方案并總結(jié)了在探索講義生成PDF過(guò)程中的經(jīng)驗(yàn)，抽象出了一套通用的，可復(fù)用的能力供各業(yè)務(wù)線快速利用，基本方案和優(yōu)劣如下：

最終方案-表格-2

目 標(biāo)

旨在提供一套以H5為載體的PDF通用生成方案，這套方案有如下特點(diǎn)：

1. 通用性強(qiáng)：能夠處理各類H5頁(yè)面，從分頁(yè)到生成，做到一套方案，多般兼容。
2. 擴(kuò)展性、配置性強(qiáng)：各場(chǎng)景可根據(jù)自己的需要自定義頁(yè)眉、頁(yè)腳、頁(yè)碼，水印，背景等配置，做到輸出形式豐富多彩。
3. 方便易接入：各業(yè)務(wù)場(chǎng)景只需關(guān)注要展現(xiàn)的內(nèi)容，無(wú)需關(guān)注分頁(yè)，PDF生成等背后的處理 ，為需要產(chǎn)出PDF的業(yè)務(wù)場(chǎng)景提效賦能；整體來(lái)看，調(diào)研、設(shè)計(jì)、開(kāi)發(fā)（+踩坑）一整套 H5 轉(zhuǎn) PDF的能力至少需要近 30人/日，我們希望這套通用能力的接入成本控制在 7人/日左右；在很多場(chǎng)景接入后，從實(shí)際反饋來(lái)看，平均只需要 2-3 人/日就接入了。
4. 質(zhì)量高：保證輸出PDF中內(nèi)容的展示與H5中無(wú)異，各種復(fù)雜公式的展示也絲毫無(wú)差錯(cuò)。
5. 性能好：保證 1 分鐘內(nèi)能處理 100+ 的 20頁(yè)左右的PDF生成任務(wù)
6. 穩(wěn)定性高：保證有各種兜底策略妥善處理各類異常，同時(shí)能夠通過(guò)限流方案應(yīng)對(duì)突發(fā)流量，保證服務(wù)穩(wěn)定。

這套方案可分為兩個(gè)核心部分，頁(yè)面展示側(cè) - Medusa，PDF生成側(cè) - Hydra

頁(yè)面展示側(cè) - Medusa

我們頁(yè)面展示側(cè)的通用能力——Medusa，是基于Paged.js的二次封裝，并以NPM包形式提供給業(yè)務(wù)方使用。Medusa可對(duì)任何HTML進(jìn)行分頁(yè)、并根據(jù)配置添加頁(yè)眉、頁(yè)腳等，最終將處理后的HTML渲染到頁(yè)面中。Medusa封裝并簡(jiǎn)化了對(duì)PDF格式的配置，可覆蓋絕大多數(shù)業(yè)務(wù)場(chǎng)景，使得各業(yè)務(wù)場(chǎng)景將更多精力投入其自身業(yè)務(wù)邏輯的開(kāi)發(fā)。

之所以選擇Pagedjs為基礎(chǔ)開(kāi)發(fā)我們自己的SDK，是因?yàn)樗悄壳拔覀兡苷业降奈ㄒ?/span>開(kāi)源的、具有HTML內(nèi)容分頁(yè)，樣式處理的前端庫(kù)，同時(shí)我們也在講義中經(jīng)過(guò)了長(zhǎng)期的摸索與沉淀。

接下來(lái)將詳細(xì)介紹Paged.js原理、Medusa支持的功能與使用方法。

一 Paged.js是如何工作的

Paged.js包含了 3 個(gè)大模塊

• Chunker（負(fù)責(zé)HTML內(nèi)容分頁(yè)）
• Polisher （負(fù)責(zé)CSS樣式處理）
• Previewer （負(fù)責(zé)預(yù)覽呈現(xiàn)Chunker和Polisher處理后的內(nèi)容）
• 
  

這里將主要介紹 Previewer 和 Chunker，因?yàn)槲覀兊亩伍_(kāi)發(fā)和維護(hù)不涉及到Polisher。

Previewer

Previewer 的工作非常簡(jiǎn)單，但我們會(huì)主要利用它封裝我們的Medusa，初始化一個(gè)Previewer對(duì)象，Previewer初始化了Chunker和Polisher對(duì)象：

Medusa-代碼-1

再調(diào)用Previewer的preview()方法，preview()方法做了兩件事：

1. 通過(guò)Polisher處理樣式內(nèi)容
2. 通過(guò)Chunker處理需要分頁(yè)的HTML內(nèi)容，如果沒(méi)有指定需要分頁(yè)的HTML，則會(huì)處理整個(gè)Body的內(nèi)容

Medusa-代碼-2

當(dāng)chunker.flow結(jié)束，即可在瀏覽器看到整個(gè)頁(yè)面處理完之后的樣子。

Chunker

首先，Chunker解析、預(yù)處理需要分頁(yè)的HTML，為其添加一些必要的屬性

Medusa-代碼-3

然后創(chuàng)建容納所有頁(yè)(pages)的容器，并掛載到renderTo容器下(默認(rèn)Body)，以備組織后續(xù)的所有頁(yè)：

Medusa-代碼-4

接著，chunker創(chuàng)建了一個(gè)page模版，以便增加頁(yè)面使用：

Medusa-代碼-5

其中，TEMPLATE是Pagedjs內(nèi)部創(chuàng)建頁(yè)面時(shí)所使用的基礎(chǔ)模版。

Medusa-代碼-6

接下來(lái)，chunker進(jìn)入了渲染+分頁(yè)過(guò)程（這個(gè)過(guò)程我們不會(huì)在二次開(kāi)發(fā)中做修改，但需要了解其基本思路以便在出問(wèn)題時(shí)能有解決思路），這個(gè)過(guò)程在循環(huán)一個(gè)迭代器（*layout），迭代器一直在做3件事：

1. 將內(nèi)容添加到模版內(nèi)容區(qū)域的容器中 -> 渲染。
2. 探測(cè)overflow，找到overflow的offset并創(chuàng)建BreakToken （探測(cè)overflow過(guò)程中很多處都用到了迭代器，此處為了說(shuō)明思路，簡(jiǎn)化了相關(guān)代碼）。

原則：

尋找overflow時(shí)會(huì)將盡可能多的內(nèi)容節(jié)點(diǎn)插入內(nèi)容區(qū)域，這里，“盡可能多”分為幾種情況，比如：

• 沒(méi)有剩余節(jié)點(diǎn)需要再添加了
• 達(dá)到了一頁(yè)所能承載的最大字符數(shù)；剛開(kāi)始的時(shí)候，如果沒(méi)有指定每頁(yè)的最大字符數(shù)，Pagedjs會(huì)給一個(gè)默認(rèn)值為 1500 的每頁(yè)最大字符用做判斷，在之后會(huì)記錄分隔好的每一頁(yè)中的字符數(shù)，并取最近4頁(yè) （少于4頁(yè)取全部）的平均值作為之后分頁(yè)的判斷條件，這里，Pagedjs相當(dāng)于對(duì)每一頁(yè)中能夠承載的內(nèi)容做了一個(gè)簡(jiǎn)單的預(yù)測(cè)，這個(gè)算法對(duì)于比較規(guī)律的內(nèi)容做分頁(yè)時(shí)還是比較簡(jiǎn)單高效的。
• 
  

步驟：

Pagedjs遵循了如下步驟去尋找overflow：

兩個(gè)前置條件：

• 內(nèi)容區(qū)域盒子邊界已經(jīng)確定，下面以contentArea.right 和 contentArea.bottom 分別代指其右邊界和下邊界。
• 處理過(guò)程中每個(gè)節(jié)點(diǎn)的邊界可以計(jì)算（對(duì)于文字節(jié)點(diǎn)，Pagedjs中使用了Range對(duì)象為其創(chuàng)建邊界），下面以 node.left、 node.right、node.top 和 node.bottom 分別代指節(jié)點(diǎn)的左、右、上、下邊界。

i. 從需要處理的內(nèi)容第一個(gè)節(jié)點(diǎn)開(kāi)始，判斷是否 node.left >= contentArea.right || node.top >= contentArea.bottom

Medusa-代碼-7

ii.如果不滿足，則判斷 node.right <= contentArea.right && node.bottom <= contentArea.bottom

Medusa-代碼-8

iii.如果不滿足，那說(shuō)明有子節(jié)點(diǎn)overflow了，則繼續(xù)深入其子節(jié)點(diǎn)查找即可。

3.使用模版添加新的頁(yè)面，并從BreakToken處繼續(xù)上述動(dòng)作。

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

基于Paged.js，Medusa支持了如下功能，并為業(yè)務(wù)方提供了更加簡(jiǎn)潔、定制化的配置。

1. 動(dòng)態(tài)頁(yè)面分頁(yè)能力
2. 單頁(yè)模版配置 -> 生成能力
3. 前、后置靜態(tài)頁(yè)面生成、與分頁(yè)后的動(dòng)態(tài)頁(yè)面拼接能力
4. 頁(yè)面處理成功后，通知PDF生成服務(wù)(Hydra)執(zhí)行任務(wù)

下方是調(diào)用Medusa的代碼示例：

Medusa-代碼-9

1.1 動(dòng)態(tài)頁(yè)面分頁(yè)能力

Medusa核心功能，可將連續(xù)的HTML頁(yè)面轉(zhuǎn)化成一頁(yè)頁(yè)P(yáng)DF樣式的HTML。

1.2 單頁(yè)模版配置 -> 生成能力

通過(guò)Grid布局，Paged.js將一個(gè)單頁(yè)模版分為多個(gè)區(qū)域，整體分為2個(gè)大的部分：

1. base 頁(yè)面基礎(chǔ)配置：每個(gè)PDF紙型、水印，內(nèi)容區(qū)域的寬高、margin與padding等等
2. surround 頁(yè)面周圍區(qū)域：如頁(yè)眉、頁(yè)腳等配置

業(yè)務(wù)方通過(guò)簡(jiǎn)單的配置，即可還原UI設(shè)計(jì)稿中的PDF樣式，例子如下圖：

1.2.1 base

頁(yè)面基礎(chǔ)配置是對(duì)每頁(yè)的。支持紙型或頁(yè)面寬高、內(nèi)容區(qū)域margin、padding、背景及水印的設(shè)置。

在封裝Medusa時(shí)，Medusa將讀取傳入的頁(yè)面模版配置、靜態(tài)頁(yè)內(nèi)容配置，并將樣式上的配置解析并轉(zhuǎn)化為Previewer可理解的樣式內(nèi)容，比如頁(yè)面寬高的設(shè)置：

Medusa-代碼-10

將被轉(zhuǎn)化為：

Medusa-代碼-11

1.2.2 surround

1. 可以看到圖中的16種不同位置的surround區(qū)域。通過(guò)設(shè)置position，可將業(yè)務(wù)方自定義的元素渲染到對(duì)應(yīng)的位置上。

2. 目前支持3種類型的surround item:

• text 文字
• img 圖片
• pageNum (動(dòng)態(tài)獲取)當(dāng)前頁(yè)碼

example:

Medusa-代碼-12

1.3 前/后置靜態(tài)頁(yè)面

業(yè)務(wù)方可通過(guò)如下方式配置靜態(tài)頁(yè)面的具體內(nèi)容：

Medusa-代碼-13

其中，傳入的React JSX Element將會(huì)被這樣處理：

Medusa-代碼-14

處理完成后，將HTML String拼接到頁(yè)面模版中，再插入分頁(yè)后內(nèi)容的前后。

PDF生成側(cè) - Hydra：

頁(yè)面展示側(cè)為PDF生成做好了頁(yè)面的準(zhǔn)備，對(duì)于PDF生成側(cè)，需要做的工作就更純粹了，業(yè)務(wù)方除了請(qǐng)求生成PDF，定期檢查PDF生成的進(jìn)度，無(wú)需做任何額外工作。

1.整體流程：

PDF生成是CPU和內(nèi)存密集型的，由于頁(yè)面內(nèi)容的不確定性，也意味著頁(yè)面渲染時(shí)間與生成PDF的時(shí)間都是不確定的，因此整體PDF生成的鏈路被設(shè)計(jì)成是異步的，如下圖：

整體流程上，業(yè)務(wù)方在請(qǐng)求生成PDF時(shí)，會(huì)先在后端做一條記錄，后端再將任務(wù)發(fā)送給Node服務(wù)，即Hydra；

在生成PDF時(shí)， 第 1 步是做頁(yè)面上的準(zhǔn)備，一個(gè)生成任務(wù)可能有多個(gè)URL頁(yè)面需要生成PDF，所以我們預(yù)先啟動(dòng)對(duì)應(yīng)URL數(shù)量的PPTR Page，頁(yè)面都啟動(dòng)完成后，進(jìn)入下一步；

第 2 步：渲染頁(yè)面，這個(gè)過(guò)程中，如果請(qǐng)求是包含多個(gè)URL的，這些頁(yè)面會(huì)同步渲染，在所有頁(yè)面渲染完成后，進(jìn)入下一步。

第 2.5 步，如果是需要生成連續(xù)頁(yè)碼的一整個(gè)PDF，還會(huì)做額外的一個(gè)動(dòng)作：頁(yè)碼矯正，通過(guò)頁(yè)碼矯正，可以將同步渲染的每個(gè)頁(yè)面，按照其之前頁(yè)面的頁(yè)碼數(shù)修正，以保證整體PDF的頁(yè)碼的連貫。

第 3 步，通過(guò)PPTR Page的能力將頁(yè)面轉(zhuǎn)換為PDF buffer，如有必要，再將生成的PDF buffer拼接到一起生成一整個(gè)PDF，或者將每個(gè)PDF buffer都生成一個(gè)PDF，壓縮成zip文件。

第 4 步，文件上傳OSS，最終返回OSS CDN鏈接。

2.請(qǐng)求生成PDF：

業(yè)務(wù)側(cè)請(qǐng)求將對(duì)應(yīng)頁(yè)面生成PDF的時(shí)，只需傳入如下字段：

Hydra-代碼-1

3.PDF生成過(guò)程：

正如在整體流程中所述，PDF生成側(cè)，我們借助 PPTR 的能力打開(kāi)頁(yè)面并生成PDF流。

在頁(yè)面調(diào)用 Medusa 分頁(yè)、組裝能力時(shí)，所有內(nèi)容分頁(yè)組裝完成后會(huì)向body中插入了一個(gè)額外的DOM以標(biāo)識(shí)該頁(yè)面處理完成：

Hydra-代碼-2

這是為了 Hydra 感知頁(yè)面渲染完成所做的準(zhǔn)備，當(dāng)生成服務(wù)的 PPTR 等到該DOM出現(xiàn)時(shí)，則表示頁(yè)面成功渲染并處理完成了：

Hydra-代碼-3

此后，在上面已經(jīng)提到過(guò)，對(duì)于需要將多個(gè)頁(yè)面生成的PDF拼接成一個(gè)PDF的情況，在生成PDF之前需要做一個(gè)重要的動(dòng)作，即頁(yè)碼矯正，原因如下：

1. 每個(gè)頁(yè)面無(wú)法感知其他頁(yè)面情況的，如：第二個(gè)頁(yè)面不知道第一個(gè)頁(yè)面會(huì)生成多少頁(yè)的PDF。
2. 它們的頁(yè)碼需要是連續(xù)的。

并且我們不希望頁(yè)面的處理是串行的，因?yàn)榇袆?shì)必導(dǎo)致速度較慢，生成時(shí)間長(zhǎng)。

這個(gè)問(wèn)題的解決方案如下：

1. 對(duì)于每個(gè)頁(yè)面都啟用一個(gè)page，并同時(shí)處理

2. 每個(gè)頁(yè)面處理完成后（pdfLastDOM出現(xiàn)），通過(guò)Page.$eval()來(lái)統(tǒng)計(jì)頁(yè)數(shù)并記錄:

Hydra-代碼-4

3. 計(jì)算出頁(yè)面中分頁(yè)之后每一個(gè)頁(yè)面的起始頁(yè)碼，以及所有頁(yè)面的頁(yè)碼總和

4. 再修改頁(yè)碼容器樣式的 counterReset 值即可，其后續(xù)頁(yè)碼可自遞增。

Hydra-代碼-5

5. 之后，再通過(guò) Medusa 在頁(yè)面window對(duì)象中Polyfill的相關(guān)配置，比如需要生成的PDF的單頁(yè)寬、高以生成PDF流。

Hydra-代碼-6

6. 最后如有必要，通過(guò)pdf-lib拼接這些 pdfBuffer 即可。

Hydra-代碼-7

7. PDF生成完成后，上傳OSS并返回URL鏈接

4.性能、穩(wěn)定性保證：

在整體方案落地前，我們對(duì)服務(wù)進(jìn)行了多次性能測(cè)試：

以下載題目為例，在4個(gè)容器，每個(gè)容器 3C 12G 的配置下的并行處理能力如下：

對(duì)于 20 道題目，每個(gè)PDF生成任務(wù)在 15 頁(yè)左右，平均 1 分鐘內(nèi)能完成 280 個(gè)任務(wù)的處理。

對(duì)于 40 道題目，每個(gè)PDF生成任務(wù)在 30 頁(yè)左右，平均 1 分鐘內(nèi)能完成 105 個(gè)任務(wù)的處理。

對(duì)于 60 到題目，每個(gè)PDF生成任務(wù)在 40 頁(yè)左右，平均 1 分鐘內(nèi)能完成 54 個(gè)任務(wù)的處理。

同時(shí)，根據(jù) Hydra 服務(wù)的整體的處理能力，后端通過(guò)任務(wù)隊(duì)列的形式幫助我們保證服務(wù)不被瞬間的突刺流量擊垮。

已接入/正在接入的相關(guān)業(yè)務(wù)線及場(chǎng)景：

目前，公司有 5 大業(yè)務(wù)線，8 個(gè)場(chǎng)景已經(jīng)完全接入我們的能力用于 H5 轉(zhuǎn) PDF，如下是錯(cuò)題本、內(nèi)容資料庫(kù)接入后生成的PDF樣例：

錯(cuò)題本：

內(nèi)容資料庫(kù)試卷：

未來(lái)展望

目前整體的PDF生成方案已經(jīng)能夠滿足大多數(shù)場(chǎng)景和內(nèi)容，但依然有可改進(jìn)空間。

HTML的流式布局要求我們必須手動(dòng)的對(duì)內(nèi)容分頁(yè)，才能添加頁(yè)眉，頁(yè)腳等（即Mdusa做的工作），正因?yàn)槿绱耍谔幚韽?fù)雜的內(nèi)容時(shí)，可能會(huì)出現(xiàn)一些問(wèn)題：比如，遇到復(fù)雜表格時(shí)，由于表格可能會(huì)有多種多樣的行、列合并，同時(shí)表格單元格內(nèi)的內(nèi)容也可以多種多樣，在分頁(yè)過(guò)程中，Medusa內(nèi)部的PagedJS并不能完美的處理對(duì)于長(zhǎng)、且復(fù)雜的表格的分割，因此可能遇到分割后表格單元格缺失、錯(cuò)亂或?qū)捀咤e(cuò)誤的問(wèn)題，這些問(wèn)題在講義中體現(xiàn)較明顯。

我們?nèi)栽诔掷m(xù)關(guān)注與研究復(fù)雜DOM內(nèi)容的分割問(wèn)題，會(huì)嘗試加以優(yōu)化和改進(jìn)PagedJS的能力，同時(shí)，我們也以另外一種思路設(shè)計(jì)了自己的DOM分頁(yè)器方案，但經(jīng)過(guò)評(píng)估，由于實(shí)現(xiàn)比較復(fù)雜，成本較高，暫時(shí)沒(méi)有投入開(kāi)發(fā)資源。

不過(guò)，我們相信，未來(lái)我們一定能以更完美的方式分割DOM以生成更高質(zhì)量的PDF。

作者:高源、陳欣博

來(lái)源:微信公眾號(hào):高途技術(shù)

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