PDF分页被截断是因CSS未强制分页控制，需用page-break-before/after/inside或现代break-*属性显式声明断点，并注意wkhtmltopdf对flex/grid/float的限制、表格续页用thead{display:table-header-group}及Playwright需设置preferCSSPageSize:true。

PDF 分页被截断，是因为 CSS 未强制分页控制

HTML 转 PDF 工具（如 wkhtmltopdf、pdfmake、playwright 或浏览器 printToPDF）默认不识别语义化分页需求，遇到长表格、大段文字或浮动元素时，常在中间硬切页。这不是 bug，是渲染引擎按“可用高度”自然折行的结果。

核心解决思路：用 CSS 的分页控制属性显式声明断点位置。

• page-break-before: always —— 强制在元素前分页（适合章节标题）
• page-break-after: always —— 强制在元素后分页（适合章节结尾）
• page-break-inside: avoid —— 禁止在该元素内部断页（对 <table>、<div class="section"> 最有效）
• 现代等价写法（推荐）：break-before: page、break-after: page、break-inside: avoid（wkhtmltopdf 0.12.6+ 和 Chromium 系工具已支持）

wkhtmltopdf 中 page-break-inside: avoid 不生效？检查这些点

这个属性看似简单，但在 wkhtmltopdf 中失效极常见，根本原因不是写错了，而是它对盒模型和渲染上下文非常敏感。

• 父容器不能是 display: flex 或 display: grid —— 这些布局会破坏分页计算，改用 block 或 inline-block
• 目标元素不能有 float —— 浮动元素天然脱离文档流，page-break-inside 失效
• 确保目标元素有明确高度或内容边界，比如给 <table> 加 width: 100% 和 table-layout: fixed，避免自动撑开导致跨页
• 若用 --enable-local-file-access 加载本地 HTML，CSS 必须内联或通过 <style> 标签引入；外部 CSS 文件可能未加载完成就触发渲染

表格跨页断裂？用 <thead> + display: table-header-group 续页

单纯靠 page-break-inside: avoid 拦不住超长表格，尤其当行数远超单页容量时。真正稳定的做法是允许分页，但保证每页都有表头。

Web Accessibility (WCAG 2 AA))

将 WCAG 2 AA 无障碍标准应用于设计系统、UI 组件和网页——通过可运行的验证器进行对比度计算，采用设计 token 模式使颜色天生可访问，设定排版和焦点状态规则，并提供语义检查清单。适用于构建或审查 UI。

下载

立即学习“前端免费学习笔记（深入）”；

thead {
  display: table-header-group;
}
tbody {
  display: table-row-group;
}

这是 HTML 表格的原生续页机制，在 wkhtmltopdf 和 Chromium 的 PDF 导出中均有效。注意：

• <thead> 必须在 <tbody> 之前，且只能有一个 <thead>
• 不要给 <thead> 设 page-break-after，否则每页表头后强制空页
• 若需固定列宽，加 table { table-layout: fixed; width: 100%; }，再为 <th> 和 <td> 设置 width 百分比

Playwright / Puppeteer 导出 PDF 时分页错位？调整 printOptions

Chromium 内核导出 PDF 时，page.pdf() 默认使用浏览器打印样式，但容易忽略自定义 CSS 中的分页规则。必须显式启用 preferCSSPageSize 并传入匹配的 format。

• 错误写法：page.pdf({ format: 'A4' }) → 可能忽略 CSS 中的 @page { size: A4 }
• 正确写法：page.pdf({ format: 'A4', preferCSSPageSize: true }) → 让 CSS @page 规则优先生效
• 补充关键 CSS：

  @page {
    size: A4;
    margin: 2cm;
  }
  @media print {
    body {
      -webkit-print-color-adjust: exact;
    }
  }

• 如果仍错位，尝试在触发 pdf() 前加 await page.waitForTimeout(100)，确保所有 page-break 样式已应用完毕

实际分页效果高度依赖具体 HTML 结构与工具链版本。最稳妥的方式是：先用 Chrome 手动「打印预览」确认分页行为，再把相同 HTML + CSS 交给自动化工具 —— 预览不正常，自动化必然失败。