pdf-best-practices

PDF 最佳实践技能

创建可完美呈现为 PDF 文档的 HTML 的全面指南。

┌─────────────────────────────────────────────────────────────────────────────┐
│                         HTML to PDF Pipeline                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   ┌──────────┐    ┌──────────────┐    ┌─────────────┐    ┌──────────────┐  │
│   │  HTML    │───▶│  PDF Engine  │───▶│  Pagination │───▶│  Final PDF   │  │
│   │ Content  │    │  (Puppeteer) │    │  & Layout   │    │  Document    │  │
│   └──────────┘    └──────────────┘    └─────────────┘    └──────────────┘  │
│        │                                     │                              │
│        ▼                                     ▼                              │
│   ┌──────────┐                        ┌─────────────┐                       │
│   │  CSS     │                        │ Page Breaks │                       │
│   │  Styles  │                        │  & Margins  │                       │
│   └──────────┘                        └─────────────┘                       │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

快速参考

我想要……	阅读此内容
正确设置文档结构	文档设置
控制分页	分页
设置 PDF 表格格式	表格
正确处理图片	图片
优化内容密度	内容密度
设置颜色和背景	颜色与背景
添加页眉、页脚和页码	页眉与页脚
创建特定类型的文档	文档类型

从这里开始

要构建新的 PDF 文档？

1. 从文档设置开始，了解 HTML 结构
2. 查看分页，避免不恰当的分页
3. 检查内容密度，避免页面内容稀疏

要处理数据表格？

1. 阅读表格，了解格式设置和表头重复
2. 使用分页，避免表格行被拆分

文档中有图片？

1. 按照图片中的指南设置尺寸和位置
2. 使用分页，让图片与说明文字保持在一起

要创建特定类型的文档？

1. 查看文档类型，了解特定类型的指南
2. 可用类型：发票、报告、证书、信函、表格密集型、图片密集型

默认配置

生成 PDF 时，请使用以下推荐参数：

{
  "format": "A4",
  "margin": {
    "top": "40px",
    "right": "40px",
    "bottom": "40px",
    "left": "40px"
  },
  "printBackground": true
}

快速检查清单

生成任何 PDF 之前：

• HTML 结构完整，包含 DOCTYPE、html、head、body
• CSS 包含带有 A4 尺寸的 @page 规则
• body 设置了 -webkit-print-color-adjust: exact
• 所有图片都明确指定了宽度和高度
• 表格使用 thead/tbody 结构
• 在逻辑内容块上设置 page-break-inside: avoid
• 标题设置 page-break-after: avoid
• 没有过多空白或内容稀疏的页面
• 字号不小于 9pt
• 颜色对比度足够
• pdfParams 包含 format、margins 和 printBackground: true