HTML 转 PDF 教程：从入门到精通 – wiki大全

作者： /

HTML 转 PDF 教程：从入门到精通

随着 Web 技术的发展，HTML 已经成为构建各种内容的主要方式。然而，在某些场景下，我们需要将 HTML 内容转换为可打印、易于分享的 PDF 格式，例如生成报告、发票、电子书或打印网页内容等。本文将为您提供一份详细的 HTML 转 PDF 教程，从基础概念到高级技巧，帮助您从入门到精通。

一、为什么需要 HTML 转 PDF？

HTML 作为一种灵活的标记语言，具有良好的排版能力和跨平台兼容性。但 PDF 格式在以下方面具有独特优势：

  1. 保持格式一致性：PDF 文件在不同设备、操作系统和打印机上都能保持原有的布局、字体和样式，避免了因浏览器或打印设置不同而导致的排版问题。
  2. 易于分享和打印：PDF 是广泛接受的文档标准，易于通过电子邮件、云存储等方式分享。同时，它对打印的支持也非常出色。
  3. 安全性：PDF 格式支持加密、密码保护等安全功能，可以限制文件的查看、编辑和打印，确保文档的安全性。
  4. 离线可用：PDF 文件是独立的，无需网络连接即可查看。

二、HTML 转 PDF 的基本方法

HTML 转 PDF 有多种方法，可以分为客户端转换和服务器端转换。

1. 客户端转换 (浏览器内置功能)

最简单直接的方法是利用浏览器自带的“打印”功能。

操作步骤：

  1. 在浏览器中打开您要转换的 HTML 页面。
  2. 按下 Ctrl + P (Windows/Linux) 或 Cmd + P (macOS) 打开打印对话框。
  3. 在打印目标或目标打印机中选择“另存为 PDF”或“Microsoft Print to PDF”等虚拟打印机选项。
  4. 点击“保存”或“打印”按钮，选择保存位置即可。

优点：

  • 无需安装额外软件或库。
  • 操作简单，适用于个人用户。

缺点：

  • 转换效果依赖于浏览器渲染引擎，可能无法完美还原复杂布局或动态内容。
  • 无法实现自动化批量转换。
  • 无法自定义 PDF 的高级属性（如页眉、页脚、目录、水印等）。

2. 在线转换工具

市面上有许多免费或付费的在线 HTML 转 PDF 工具。

操作步骤：

  1. 打开一个在线 HTML 转 PDF 网站（例如：html2pdf.com, sejda.com/html-to-pdf）。
  2. 输入 HTML 页面的 URL 或上传 HTML 文件。
  3. 根据工具提供的选项进行一些设置（如页面大小、方向等）。
  4. 点击转换按钮，下载生成的 PDF 文件。

优点：

  • 无需安装软件。
  • 通常提供一些自定义选项。

缺点：

  • 安全性问题：上传敏感 HTML 内容到第三方服务存在风险。
  • 依赖网络连接。
  • 免费工具通常有文件大小或使用次数限制。
  • 对于复杂或本地的 HTML 文件，可能无法很好地处理。

三、服务器端转换 (编程实现)

对于需要自动化、批量转换或高度定制化 PDF 的场景，服务器端编程是更合适的选择。这通常涉及使用特定的库或工具来渲染 HTML 并生成 PDF。

1. 使用 Headless 浏览器 (推荐)

Headless 浏览器（如 Puppeteer, Selenium with headless Chrome/Firefox）是服务器端 HTML 转 PDF 的黄金标准。它们能够模拟真实浏览器环境，完整渲染 HTML、CSS、JavaScript，从而生成高度还原的 PDF。

以 Node.js 和 Puppeteer 为例：

安装 Puppeteer:

bash
npm install puppeteer

示例代码 (Node.js):

“`javascript
const puppeteer = require(‘puppeteer’);

async function convertHtmlToPdf(htmlContentOrUrl, outputPath) {
const browser = await puppeteer.launch();
const page = await browser.newPage();

if (htmlContentOrUrl.startsWith('http://') || htmlContentOrUrl.startsWith('https://')) {
    await page.goto(htmlContentOrUrl, { waitUntil: 'networkidle0' }); // 等待网络空闲
} else {
    await page.setContent(htmlContentOrUrl, { waitUntil: 'networkidle0' }); // 等待网络空闲
}

await page.pdf({
    path: outputPath,
    format: 'A4',
    printBackground: true, // 打印背景颜色和图片
    margin: {
        top: '20mm',
        right: '20mm',
        bottom: '20mm',
        left: '20mm'
    },
    displayHeaderFooter: true,
    headerTemplate: '<div style="font-size: 10px; margin-left: 20mm; color: #555;">Header - Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>',
    footerTemplate: '<div style="font-size: 10px; margin-left: 20mm; color: #555;">Footer - Generated on ' + new Date().toLocaleDateString() + '</div>',
});

await browser.close();
console.log(`PDF saved to ${outputPath}`);

}

// 示例用法：从 URL 转换
convertHtmlToPdf(‘https://www.example.com’, ‘example.pdf’);

// 示例用法：从 HTML 字符串转换
const htmlString = <!DOCTYPE html>
<html>
<head>
<title>My Document</title>
<style>
body { font-family: Arial, sans-serif; margin: 50px; }
h1 { color: #333; }
p { line-height: 1.6; }
</style>
</head>
<body>
<h1>Hello, PDF!</h1>
<p>This is a sample HTML content converted to PDF using Puppeteer.</p>
<img src="https://via.placeholder.com/150" alt="Placeholder Image">
<p>This paragraph spans multiple lines to test layout.</p>
<div style="page-break-before: always;"></div>
<h2>New Page Content</h2>
<p>This content should appear on a new page.</p>
</body>
</html>;
convertHtmlToPdf(htmlString, ‘sample.pdf’);
“`

优点：

  • 高保真度：完美还原 HTML、CSS、JavaScript 渲染效果，包括动态内容和复杂的布局。
  • 高度可定制：支持设置页面大小、方向、边距、页眉页脚、背景打印、目录生成等高级选项。
  • 自动化：非常适合在服务器端进行批量转换和集成到工作流中。
  • 跨平台：Puppeteer 等工具可在 Linux, macOS, Windows 上运行。

缺点：

  • 性能开销：需要启动一个完整的浏览器实例，对服务器资源（CPU、内存）消耗较大。
  • 安装复杂：需要安装 Chromium/Firefox 等浏览器二进制文件。
  • 调试相对复杂。

2. 使用专门的 HTML 转 PDF 库

除了 Headless 浏览器，还有一些专门的库用于 HTML 转 PDF，它们通常不依赖完整的浏览器环境，而是自己实现 HTML/CSS 的解析和渲染。

  • Python:

    • WeasyPrint: 一个强大的、支持 CSS Paged Media 规范的 Python 库，用于将 HTML 和 CSS 转换为 PDF。它无需浏览器，但需要安装一些依赖（如 Cairo, Pango）。
      bash
      pip install WeasyPrint
      “`python
      from weasyprint import HTML, CSS

      从 URL 转换

      HTML(‘https://weasyprint.org/’).write_pdf(‘/tmp/weasyprint-docs.pdf’)

      从 HTML 字符串和 CSS 字符串转换

      html_string = “

      Hello WeasyPrint!

      This is a test.

      ”
      css_string = “h1 { color: blue; }”
      HTML(string=html_string).write_pdf(‘./output.pdf’, stylesheets=[CSS(string=css_string)])
      ``
      * **xhtml2pdf:** 另一个 Python 库，基于 ReportLab。
      * **Java:**
      * **Flying Saucer:** 一个开源的 Java 库，用于渲染 XML（包括 XHTML）和 CSS 到 PDF。
      * **OpenHtmlToPdf:** 另一个基于 Flying Saucer 的 Java 库，提供了更好的 CSS3 支持。
      * **PHP:**
      * **Dompdf:** 一个流行的 PHP 库，可以将 HTML 和 CSS 渲染为 PDF。
      * **Wkhtmltopdf (PHP 包装器):** 虽然      wkhtmltopdf是一个独立的命令行工具，但很多 PHP 库（如barryvdh/laravel-dompdf）都会使用它作为后端，因为它基于 WebKit 渲染引擎，效果较好。
      * **Go:**
      * Go 语言本身没有特别成熟的纯 Go 实现库，通常会选择调用外部命令行工具      wkhtmltopdf或Chrome/Puppeteer`。

以命令行工具 wkhtmltopdf 为例 (跨语言通用)：

wkhtmltopdf 是一个开源命令行工具，使用 WebKit 渲染引擎，可以将 HTML 页面转换为 PDF。它在很多语言中都有相应的包装器。

安装 (例如 Debian/Ubuntu):

bash
sudo apt-get update
sudo apt-get install wkhtmltopdf

命令行使用：

bash
wkhtmltopdf https://www.example.com output.pdf
wkhtmltopdf input.html output.pdf

优点：

  • 性能较好：相对于 Headless 浏览器，一些库可能资源消耗更少。
  • 离线工作：大多数库无需完整的浏览器环境。
  • 多语言支持：不同编程语言都有对应的库。

缺点：

  • 渲染限制：这些库通常有自己的 HTML/CSS 解析器和渲染引擎，对 CSS3、JavaScript 或复杂布局的支持可能不如真实浏览器。
  • 兼容性问题：某些复杂的 CSS 属性或 JavaScript 交互可能无法正确渲染。
  • 维护成本：需要关注库的更新和依赖。

四、HTML 转 PDF 的高级技巧与最佳实践

1. 样式控制 (CSS)

  • @page 规则: 用于控制打印页面的样式，如边距、页面大小 (size)、方向 (orientation)。
    css
    @page {
    size: A4 portrait; /* A4 纵向 */
    margin: 2cm;
    }
  • page-break-before, page-break-after, page-break-inside: 控制元素在打印时的分页行为。
    • page-break-before: always;: 在元素之前强制分页。
    • page-break-after: always;: 在元素之后强制分页。
    • page-break-inside: avoid;: 避免在元素内部（如图片、表格行）分页。
  • display: none for print: 在打印时隐藏某些不必要的元素（如导航栏、广告）。
    css
    @media print {
    .no-print {
    display: none;
    }
    }
  • 背景图片和颜色: 默认情况下，浏览器打印时可能不包含背景颜色和图片。在使用 Headless 浏览器或 wkhtmltopdf 时，通常需要显式设置 printBackground: true (Puppeteer) 或 -B (wkhtmltopdf)。
  • 字体嵌入: 确保使用的字体能够正确嵌入到 PDF 中，以保证在任何设备上都能正确显示。通常，在使用 Headless 浏览器时，如果字体在系统上可用，它们会自动嵌入。对于某些库，可能需要额外配置。

2. 页眉和页脚

  • Headless 浏览器: 如 Puppeteer 提供了 headerTemplate 和 footerTemplate 选项，允许您使用 HTML 字符串定义页眉和页脚，并支持动态插入页码 (<span class="pageNumber"></span>) 和总页数 (<span class="totalPages"></span>)。
  • CSS Paged Media (@page): 某些支持 CSS Paged Media 规范的库 (如 WeasyPrint) 允许使用 @page 规则配合生成内容 (content) 和定位 (position) 来创建页眉页脚。

3. 链接和书签

  • 超链接: HTML 中的 <a href="..."> 链接通常会自动转换为 PDF 中的可点击链接。
  • 目录/书签: 对于长文档，生成一个可点击的目录或书签非常有用。
    • Headless 浏览器: 某些工具可以根据 HTML 的标题结构 (<h1>, <h2>) 自动生成 PDF 书签。
    • 专门库: 像 WeasyPrint 这样的库提供更强大的功能来根据文档结构生成目录和书签。

4. 图片处理

  • 相对路径: 确保 HTML 中引用的图片路径在转换环境中是可访问的。如果是服务器端转换，相对路径应相对于 HTML 文件。
  • Base64 编码图片: 将小图片直接 Base64 编码嵌入到 HTML 中，可以避免外部资源加载问题。
  • 大图片优化: 对于大尺寸图片，考虑在转换为 PDF 之前进行压缩，以减小 PDF 文件大小。

5. 性能优化

  • 并发转换: 对于批量转换任务，可以考虑使用并发处理，但要注意服务器资源限制。
  • 资源缓存: 如果您从 URL 转换，确保服务器端缓存策略得当，避免重复下载资源。
  • 优化 HTML/CSS/JS: 简化不必要的 DOM 结构，优化 CSS 选择器，减少不必要的 JavaScript 执行，可以加快渲染速度。

五、选择合适的工具

选择哪种 HTML 转 PDF 的方法和工具，取决于您的具体需求：

  • 个人用户或简单转换: 浏览器内置功能或在线转换工具。
  • 需要高保真度、动态内容、高级定制且对性能有一定要求的服务器端自动化: Headless 浏览器 (Puppeteer, Selenium)。
  • 对渲染精度要求较高，但不希望运行完整浏览器，且支持 CSS Paged Media 的服务器端自动化 (Python): WeasyPrint。
  • 对渲染精度要求一般，但追求轻量级、快速的服务器端自动化 (跨语言): wkhtmltopdf (通过命令行或相应语言的包装器)。
  • Java 或 PHP 生态系统中的服务器端自动化: Flying Saucer (Java), Dompdf (PHP) 等。

六、总结

HTML 转 PDF 是一个常见的需求，从简单的浏览器打印到复杂的服务器端自动化，有多种解决方案可供选择。理解不同方法的优缺点，掌握 CSS 打印样式控制，以及利用 Headless 浏览器或专业库的高级功能，将帮助您高效、高质量地完成 HTML 到 PDF 的转换任务。希望这篇教程能帮助您从入门走向精通！

滚动至顶部