言

目前，教學、教研各種內容線上沉淀、展示豐富多彩，但線上內容“線下化”能力不足或過分依賴人力，比如，線上練習題組卷后以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需求的時候，無論是用電腦還是手機都可以 可以輕松進行轉換，有需要的小伙伴們可以用起來啦~