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;
}

"应该"是因为浏览器支持各不相同。彻底测试。

什么渲染，什么不渲染

Web字体： 有时工作，有时不工作。用实际字体测试，不要用后备字体。

背景颜色： 通常默认排除（节省墨水）。检查"打印背景"设置。

图片： 外部图片可能不加载。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这样的库创建PDF时不需要HTML转换层。

更多工作，更多控制，更可预测的结果。

---

HTML到PDF转换有效，但它需要注意打印样式、分页符，以及Web和打印媒介之间的差异。彻底测试并相应设定期望。