言

最近在業務上遇到了一個問題是要將頁面打印輸出成pdf文件，通過點擊一個按鈕，就能夠將頁面寫在一個pdf上，并下載下來，需要保證pdf的內容具有很好的可讀性。

經評估要實現這個需求，一種可行的方案是將HTML頁面轉為PDF，并實現下載。通過技術調研，最終的方案確定為通過html2canvas + jspdf這兩個庫來實現，通過使用html2canvas提供的方法，將頁面元素轉為base64圖片流，然后將其插入jspdf插件中，實現保存并下載pdf。

html2canvas + jspdf方案是前端實現頁面打印的一種常用方案，但是在實踐過程中，遇到的最大問題就是分頁截斷的問題：當頁面元素超過一頁A4紙的時候，連續的頁面就會因為分頁而導致內容被截斷，進而影響了pdf的可讀性。

由于網上關于分頁截斷的解決思路比較少，所以特意將此次的解決方案記錄下來。

使用 JSPDF 和 html2canvas 創建簡單的 PDF文件

首先，我們開始使用 JSPDF 和 html2canvas 生成一個簡單的 PDF文件。

創建一個 JSPDF 實例

創建一個 JSPDF 實例，設置頁面的大小、方向和其他參數。參考官網可以寫一個很簡單的實例

var doc = new jsPDF({
  orientation: 'landscape',
  unit: 'in',
  format: [4, 2]
}

doc.text('Hello world!', 1, 1)
doc.save('two-by-four.pdf')

生成一個pdf文件，并且在文件中寫入一定內容，其實JSPDF這個庫就能做到。

但是很多業務場景下，我們的目標內容會更復雜，而且還要考慮樣式，所以最好的方式是引入html2canvas這個庫，將頁面元素轉換成base64數據，然后貼在pdf中(使用addImage方法），這樣就能保證頁面的內容。

引入了html2canvas庫后，我們更多關注是利用現成組件庫、框架或者原生html和css實現更復雜的頁面內容。

引入 html2canvas

使用 html2canvas 捕捉 HTML 內容或特定的 HTML 元素，并將其轉換為 Canvas。其中，html2canvas 函數的主要用法是：

html2canvas(element, options);

• element： 要渲染為 canvas 的 HTML 元素。這可以是一個 DOM 元素，也可以是一個選擇器字符串，表示需要渲染的元素。
• options（可選）： 一個包含配置選項的對象，用于定制 html2canvas 的行為。

以下是一些常見的配置選項：

• allowTaint（默認值: false）： 是否允許加載跨域的圖片，默認為 **false**。如果設為 true，html2canvas 將嘗試加載跨域的圖片，但在某些情況下可能會受到瀏覽器的限制。
• backgroundColor（默認值: #ffffff）： canvas 的背景顏色。
• useCORS（默認值: false）： 是否使用 CORS（Cross-Origin Resource Sharing）來加載圖片。如果設置為 **true**，則 html2canvas 將嘗試使用 CORS 來加載圖片。
• logging（默認值: false）： 是否輸出日志信息到控制臺。
• width 和 height： canvas 的寬度和高度。如果未指定，則默認為目標元素的寬度和高度。
• scale（默認值: window.devicePixelRatio）： 縮放因子，決定 canvas 的分辨率。

下面是一個簡單的demo，可以看到html2canvas能夠將dom元素轉化為一張base64圖片，將鼠標選中元素，可以感受到圖片和文字的不同。

<div id="capture" style="padding: 10px; background: #f5da55">
    <h4 style="color: #000; ">Hello world!</h4>
</div>

html2canvas(document.querySelector("#capture")).then(canvas => {
    document.body.appendChild(canvas)
});

Untitled.png

將html2canvas轉化的圖片放到pdf中

這一步我們需要使用JSPDF 的addImage方法，其語法如下：

addImage(imageData, format, x, y, width, height, alias, compression)

• imageData - 要添加的圖像數據。可以是圖像的 URL、圖像的 base64 編碼字符串或圖像的二進制數據
• format - 圖像的格式。可以是 "JPEG"、"PNG" 或 "TIFF"。
• x - 圖像在 PDF 文檔中的 x 坐標。
• y - 圖像在 PDF 文檔中的 y 坐標。
• width - 圖像的寬度。
• height - 圖像的高度。
• alias - 圖像的別名。此別名可用于在 PDF 文檔中引用圖像。
• compression - 圖像的壓縮級別。可以是 "NONE"、"FAST" 或 "SLOW"。

下面是一串示例代碼：

import jsPDF from 'jspdf';

export default function addImageUsage() {
  const doc = new jsPDF();
  const imageData = 【替換成base64數據流】;
  doc.addImage(imageData, 'png', 0, 0, 10, 10);
  doc.addImage(imageData, 'png', 100, 100, 10, 10);
  doc.addImage(imageData, 'png', 200, 200, 10, 10);

  drawNet(doc);

  doc.save('output.pdf');
}

const drawNet = (doc) => {
  const gap = 10;
  const start = [0, 0];
  const end = [595.28, 841.89];

  // 所有橫線
  for (let i = start[0]; i < end[0]; i = i + gap) {
    doc.line(i, 0, i, end[0]);
  }
  // 所有縱線
  for (let j = start[1]; j < end[1]; j = j + gap) {
    doc.line(0, j, end[1], j);
  }
};

此示例將在 PDF 文檔（默認是A4紙大小，寬高為[595.28, 841.89]像素）的 (10, 10) 、(100, 100) 、(200, 200) 坐標處，添加一張png 圖像。圖像的寬度和高度將分別為 10 和 10 像素，為了了解pdf中的坐標系統，此示例還在pdf文檔中生成了間距為10px的網格系統。

JSPDF 和 html2canvas結合起來用

了解了上面的三個關鍵點，接下來我們將這三個步驟串聯起來，實現一個基本的html→pdf的方案。大致步驟如下：

1. 寫一個基本html頁面
2. 創建jspdf實例
3. 獲取頁面的dom節點，使用html2canvas將其轉化為base64數據流
4. 將base64數據流裝載到jspdf提供的addImage方法中
5. 保存pdf

基于這5個步驟，可以實現基本的頁面打印。

import html2canvas from 'html2canvas';
import jsPDF, { RGBAData } from 'jspdf';

// 將元素轉化為canvas元素
// 通過 放大 提高清晰度
// width為內容寬度
async function toCanvas(element: HTMLElement) {
  if (!element) return { width: 0, height: 0 };

  // canvas元素
  const canvas = await html2canvas(element, {
    scale: window.devicePixelRatio * 2, // 增加清晰度
    useCORS: true // 允許跨域
  });

  // 獲取canvas轉化后的寬高
  const { width: canvasWidth, height: canvasHeight } = canvas;

  // 轉化成圖片Data
  const canvasData = canvas.toDataURL('image/jpeg', 1.0);

  return { width: canvasWidth, height: canvasHeight, data: canvasData };
}

/**
 * 生成pdf(A4多頁pdf截斷問題， 包括頁眉、頁腳 和 上下左右留空的護理)
 */
export async function generatePDF({
  /** pdf內容的dom元素 */
  element,

  /** pdf文件名 */
  filename
}) {
  if (!(element instanceof HTMLElement)) {
    return;
  }

  const pdf = new jsPDF();

  // 一頁的高度， 轉換寬度為一頁元素的寬度
  const {
    width: imageWidth,
    height: imageHeight,
    data
  } = await toCanvas(element);

  // 添加圖片
  function addImage(
    _x: number,
    _y: number,
    pdfInstance: jsPDF,
    base_data:
      | string
      | HTMLImageElement
      | HTMLCanvasElement
      | Uint8Array
      | RGBAData,
    _width: number,
    _height: number
  ) {
    pdfInstance.addImage(base_data, 'JPEG', _x, _y, _width, _height);
  }

  addImage(0, 0, pdf, data!, imageWidth, imageHeight);

  return pdf.save(filename);
}

多頁：比例縮放+循環移位

通常，在我們的實踐中，會發現2個問題：

• 生成的pdf內容與實際的頁面元素比例不一致
• 頁面內容超出一頁pdf的高度，但是生成的pdf只有一頁，沒有展示全部的頁面信息

這兩個問題的解決方案是等比例縮放+循環移位：

• 等比例縮放

通過比例縮放，實現頁面內容等比例展示在pdf文檔中

令頁面元素的寬高為x, y（轉化成canvas圖片的寬高），pdf文檔的寬高為w, h。因為高度可以通過加頁延伸，所以可以按照寬度進行縮放，縮放后的圖片高度可以通過下列公式計算

• 循環移位

如果頁面的高度超出了pdf文檔的高度，即y > h，使用addPage方法添加一頁即可。但是在新的一頁中，我們的圖片內容的高度需要調整。

假設y = 2 * h，這意味我們需要兩頁才能完整得展示頁面內容。在一頁pdf中，圖片在起始位置插入即可，即

 PDF.addImage(pageData, 'JPEG', 0, 0, x, y)// 注意x,y 是縮放后的大小

在第二頁pdf中，圖片的縱向位置需要調整一頁pdf的高度，即

 PDF.addImage(pageData, 'JPEG', 0, -h, x, y)// 注意x,y 是縮放后的大小

通過循環計算剩余高度，然后不停調整縱向位置移動base64的圖片位置，可以解決多頁的問題。

分頁截斷的挑戰

盡管 JSPDF 和 html2canvas 是功能強大的工具，但是他們也有很多槽點，比如得手動分頁，手動處理分頁截斷的問題。等你實踐到這一步，就開始面臨分頁截斷的問題，類似的問題也有網友在Github上提出，但是底下依然沒有很好的解決思路。

好在掘金上有人分享了一個不錯的方法：

jsPDF + html2canvas A4分頁截斷 完美解決方案（含代碼 + 案例） - 掘金

概括一下，其處理分頁截斷的原理就是在使用addImage之前，將html進行分頁，通過維護一個高度位置數據，來記錄每次循環迭代addImage的位置。

從高到低遍歷維護一個分頁數組pages，該數組記錄每一頁的起始位置，如：pages[0] 對應 第一頁起始位置，pages[1] 對應第二頁起始位置

Untitled2.png

接下來我們重點討論如何將頁面進行切割，然后生成pages這個數組。

假設頁面的高度是1500，pdf寬高是[500, 900]，如果不用處理分頁截斷的問題，我們可以想到第一頁（0-900）是用來承載頁面從高度為0到900的信息；

第二頁（900-1800）是用來承載頁面從高度900到1500的，所以pages數組為[0, 900]。

如果要處理分頁截斷呢，這時候就需要計算頁面元素的距離pdf文檔起始位置的高度h1，以及該元素的內部高度h2，通過這兩個高度來判斷這個元素要不要放在下一頁，防止截斷，示意圖如下：

Untitled4.png

如果h1 + h2 > 頁面高度， 這時候說明這個元素不處理的就會被分頁截斷，所以應該要把這個元素放到第二頁去渲染，這就意味著pages記錄的數據要變化，示意圖如下，可以看到pages[1]我們往上調整了，比第二頁pdf的起始位置更高。

Untitled5.png

說明渲染第二頁pdf的時候，要從h1開始渲染，pages數組為[0, h1]，解釋為第一頁pdf渲染頁面高度區域為0-900, 第二頁pdf渲染html高度區域為h1-1500。注意到第一頁渲染的時候到尾部的時候，會有部分內容和第二頁頭部內容重合。因為h1到900這部分的內容肯定會渲染，這部分內容一直都是頁面元素，我們改變pages[1]的值的原因只是創建一個副本，讓頁面看起來內容沒有被截斷。

為了解決這個問題（為了美觀），我們用填充一塊白色區域遮掉它！此處使用jspdf的rect和setFillColor方法，把重合的區域遮白處理。

pdf.setFillColor(255, 255, 255);
pdf.rect(x, y, Math.ceil(_width), Math.ceil(_height), 'F');

如何獲得h1和h2

上面我們談到了h1和h2，其中h1是元素盒子的上邊距到打印區域的高度（比例縮放后的高度），h2是元素盒子的內部高度。

計算h1: getBoundingClientRect方法

const rect = contentElement.getBoundingClientRect() || {};
const topDistance = rect.top;
return topDistance;

Untitled6.png

計算h2：offsetHeight方法

Untitled7.png

值得注意的是，因為打印區域的html元素不一定是從窗口頂部開始，所以為了計算實際的h1(元素到打印區域的頂部距離），可以采用這樣的方法：

• 用getBoundingClientRect方法計算元素到窗口頂部的距離
• 循環打印之前將pages信息針對第一個元素進行一個高度校準。

// 對pages進行一個值的修正，因為pages生成是根據根元素來的，根元素并不是我們實際要打印的元素，而是element，
  // 所以要把它修正，讓其值是以真實的打印元素頂部節點為準
  const newPages = pages.map((item) => item - pages[0]);

在線demo演示和源代碼

上述即是在實現前端頁面生成pdf的過程中遇到的問題，以及解決思路。

為了更直觀得感受效果，本文也給出了不同場景（單頁、多頁、多頁截斷、自定義頁眉頁腳、橫向）下的pdf生成效果，可以通過此鏈接體驗：https://pdf-demo-phi.vercel.app/

此demo的源代碼如下：pdf-demo

與現有文章不同的是，本倉庫的代碼特點在于：

• 支持設置pdf打印的方向，比如橫向
• 修正了高度計算問題，解決了多出一個空白頁問題。掘金那篇文章計算元素高度時候沒有減去容器距離頂部高度，所以導致很多新手使用那份代碼的時候，會發現自己的頁面頂部被裁剪到了，原因就是這個
• 支持自定義頁眉頁腳
• 支持擴展自定義分頁方法，如果遇到復雜的組件，可以自定擴展邏輯計算高度

作者:燕平

來源:微信公眾號:Goodme前端團隊

出處:https://mp.weixin.qq.com/s/-1nA-VI6kmgqHRcYs_NZFA