HTML 轉 PDF:比應該的還要難

你有一個漂亮的網頁。你需要它作為 PDF。Control+P,另存為 PDF。完成?

有時候。但結果通常有損壞的佈局、缺失的圖片、奇怪的分頁符,以及被截斷到一半的標題。

HTML 和 PDF 根本上是不同的。讓它們一起工作需要付出努力。

為什麼它很複雜

HTML 是流動的。 內容流動以填充可用空間。響應式。靈活。

PDF 是固定的。 特定的頁面尺寸。精確的定位。沒有流動。

轉換意味著把設計為適應的東西強制放到剛性的頁面上。

分頁符是敵人

你美麗的段落最終被分割到兩頁。表格標題在第 3 頁,資料從第 4 頁開始。

CSS 有 page-break-before、page-break-after 和 page-break-inside 屬性。它們應該控制這個。

h2 {
  page-break-after: avoid;
}

table {
  page-break-inside: avoid;
}

「應該」,因為瀏覽器支援各不相同。徹底測試。

什麼會渲染,什麼不會

網頁字型: 有時有效,有時無效。用實際字型測試,而不是回退字型。

背景顏色: 通常預設排除(節省墨水)。檢查「列印背景」設定。

圖片: 外部圖片可能無法載入。CORS 問題在轉換時出現。

JavaScript 渲染的內容: 如果內容透過 JS 載入,當 PDF 擷取頁面時它可能不存在。

動畫和過渡: 消失了。PDF 是靜態的。

列印樣式表

CSS 有一個列印的媒體類型:

@media print {
  .no-print {
    display: none;
  }

  body {
    font-size: 12pt;
  }

  a::after {
    content: " (" attr(href) ")";
  }
}

隱藏導航,調整字型,為連結顯示 URL。專門為列印輸出設計。

不同的轉換方法

瀏覽器列印為 PDF: 適合一次性轉換。結果因瀏覽器而異。

無頭瀏覽器 (Puppeteer、Playwright): 程式化控制。一致的結果。需要設定。

PDF 函式庫 (wkhtmltopdf、WeasyPrint): 專用工具。更好地控制輸出。

線上服務: 上傳 HTML,取得 PDF。方便偶爾使用。

每種都有品質、速度和控制的權衡。

獲得更好結果的技巧

使用固定寬度。 響應式佈局會導致不可預測的結果。為 PDF 輸出設定特定寬度。

簡化佈局。 複雜的 CSS grid 和 flexbox 可能會損壞。更簡單的佈局轉換更可靠。

嵌入字型。 不要依賴系統字型可用。

早期測試。 不要建立整個頁面然後再嘗試 PDF 轉換。在建立時測試。

設定明確的頁面大小。 PDF 以頁面思考。告訴它什麼大小。

@page {
  size: A4;
  margin: 1cm;
}

何時使用原生 PDF

如果你需要精確控制——合約、發票、具有精確格式的報告——考慮直接生成 PDF 而不是轉換 HTML。

像 PDFKit、ReportLab 或 iText 這樣的函式庫在沒有 HTML 轉換層的情況下創建 PDF。

更多工作,更多控制,更可預測的結果。

---

HTML 到 PDF 轉換有效,但需要注意列印樣式、分頁符以及網頁和列印媒體之間的差異。徹底測試並相應地設定期望。