PDF 分页控制详解：自动分页与强制分页完整指南

分页是 DOM 转 PDF 里最影响体验的环节：内容超过一页怎么断？表格跨页后表头还在不在？想让某个章节单独起一页怎么办？这些问题处理不好，导出的 PDF 就会出现标题孤行、表格被拦腰截断、章节错乱等低级问题，文档的专业度大打折扣，客户对产品的评价也会受影响。dompdf.js 内置自动分页引擎，内容超出页面尺寸时自动创建新页，同时支持 @page 分页媒体属性，可以精细控制页边距、强制分页和跨页行为。本文从分页原理讲起，结合代码示例，把自动分页、强制分页、表格跨页的常用控制方式一次讲清楚，帮你直接避开常见的分页坑，少走弯路，交付一次成型。

为什么分页如此重要

长文档（合同、报告、产品手册）超过一页是常态，分页质量直接决定文档专业度：孤行标题、表格截断、页脚错位都会让文档显得粗糙，影响客户和领导的第一印象，也影响文档的正式性，交付时观感差距很大，细节决定评价，分页问题会直接影响客户对产品的信任度。

打印场景下分页尤其关键，打印出来的效果必须与屏幕预览一致；分页控制不好，纸张切换、双面打印、装订都会出问题，返工成本很高，办公场景里打印 PDF 的频率远超想象，分页问题会反复被用户吐槽，务必重视，上线前用真实文档完整走一遍打印流程。

好的分页应该是“智能”的：内容自然流动、重要区块尽量完整、表格表头跨页重复，这些正是 dompdf.js 自动分页引擎处理的范畴，开发者只需关注内容本身，不必手动计算每个断点，效率高且不易出错，交付质量更稳定，尤其适合长报告、合同这类高频导出场景，投入产出比很高。

自动分页的工作原理

dompdf.js 把传入的 HTML 或 DOM 按页面尺寸进行排版，内容超过一页时自动创建新页，文字、图片、表格都会在页边界处得到正确处理，不会重叠或丢失，长内容也能完整呈现，再长的合同也能一次导出，稳定性有保障，大文件导出也不用担心内容残缺。

分页稳定性与容器宽度直接相关：A4 在 96 DPI 下对应 794px 宽，让导出容器的 CSS 宽度与目标纸张对应，能得到最稳定、最可预期的分页结果，这是官方推荐的做法，务必先对齐容器宽度再调其他参数，顺序别搞反，容器宽度与纸张不一致时，断点位置会随机漂移，排查起来很费劲，对齐后大部分问题自动消失。

排版计算在 Web Worker 中完成，导出大文档时主线程不会被阻塞，界面保持可响应；进度可以通过回调感知，长文档导出时也能给用户准确的进度反馈，体验更专业，用户不会误以为程序卡死了，反馈及时很重要，配合进度条展示当前页数和总页数，等待体验会好很多。

代码示例：基础分页与页边距

@page 规则统一设置纸张大小和页边距；page-break-before: always 让章节从新页开始，page-break-inside: avoid 保护重要区块不被拆分，两类控制组合使用即可覆盖大多数场景，模板结构也清晰，维护起来一目了然，问题定位也快，先规划好哪些章节需要另起一页、哪些区块不能拆开，再动手写模板，事半功倍。

这些都是标准 CSS 分页媒体属性，写在模板的 style 标签里即可生效，不需要额外的 JS 逻辑，模板维护成本低，设计师也能直接参与调整，协作效率更高，前后端职责也划分得更清楚，改动风险小，上线更放心。

break-before、break-inside 是更现代的等价写法，两者都可以使用；与表格、图片组合时按实际渲染效果微调，以最终 PDF 呈现为准，多测试几种内容组合更稳妥，上线前用真实数据验证一遍最放心，避免交付后返工，把常见的标题、表格、图片组合都过一遍，断点行为心里有数，后续维护也轻松。

import { DomPDF } from 'dompdf.js';

const html = `
  <style>
    @page { size: A4; margin: 20mm 15mm; }
    .chapter { page-break-before: always; }
    .keep-together { page-break-inside: avoid; }
  </style>
  <h1>产品手册</h1>
  <p>第一章：产品介绍，这里是不想被拆散的内容……</p>
  <div class="chapter">
    <h2>第二章</h2>
    <p>第二章内容从这里开始新的一页，与上一章清晰分隔……</p>
  </div>
  <div class="keep-together">
    <h3>不允许被拆开的区块</h3>
    <p>这个标题和这段文字要保持在同一页内，避免孤行标题……</p>
  </div>`;

const pdf = new DomPDF();
pdf.addPage(html, { format: 'A4', margin: '20mm' });
pdf.save('manual.pdf');

表格与长区块的跨页处理

表格是分页的重灾区：行高超过剩余空间时可能被截断，表头丢失后后续页面难以阅读。dompdf.js 对表格边框和跨页渲染有专门支持，长表格可以连续跨页展示，配合表头重复阅读体验更好，数据完整不断裂，信息呈现可靠，配合表头样式统一，跨页阅读体验和首屏一致。

实践建议：表格列宽用百分比，行内不要放超高图片；需要完整展示的重要表格，可以用 page-break-inside: avoid 让整个表格换到新页，保证完整性，关键数据绝不腰斩，客户看到的数据永远完整，可信度更高，金额、日期这类敏感列尤其要保护。

卡片、代码块、图表容器等区块级内容建议统一设置避免拆分，再配合“新章节另起一页”的规则，长文档的阅读体验会明显提升，翻页结构清晰，打印装订也更整齐，整体观感专业很多，用户好评率也会上升，尤其适合投标文件、产品手册这类对排版要求高的正式文档。

分页与页眉页脚的联动

多页文档通常需要页眉页脚：页眉放文档标题，页脚放“第 X 页 / 共 Y 页”，dompdf.js 支持页眉页脚与页码，并随分页自动更新，无需逐页处理，多页文档也能保持信息完整，页码从不出错，归档检索都方便，几十页的报告也无需人工核对页码，省时省力，交付更快。

页码随分页连续递增；封面页、目录页可以通过排除机制不显示页码，让正文从第 1 页开始计数，符合正式文档的排版习惯，客户拿到手的文档页码规范可信，投标文件这类场景尤其需要，细节上不能含糊。

分页、页眉页脚配合 @page 一起使用，可以在不写任何坐标代码的情况下，得到一份结构完整、风格统一的正式 PDF，维护成本很低，交付质量却明显提升，是性价比最高的组合，正式文档首选的配置方式，把分页与页眉页脚一起规划，一次成型。

常见问题

Q: 为什么分页位置和浏览器打印预览不一样？A: 分页与容器宽度、页面尺寸强相关，先把容器宽度调整为纸张对应的像素宽度（A4 为 794px），再对比效果，多数不一致都能解决，这是排查的第一步，也是最有效的办法，同时检查页面尺寸和缩放设置是否一致，双管齐下基本能解决九成的问题。

Q: 图片跨页会被截断吗？A: 图片作为整体块处理，默认避免拆分；超大图片建议先缩放到合适宽度再放入文档，效果最稳定，也不会撑破页面布局，长图记得按页高拆分处理，展示效果可控。

Q: 多页批量 addPage 与自动分页怎么配合？A: 每次 addPage 的内容独立排版，单页内容超长时自动分页，批量场景两者叠加使用，互不冲突，适合目录、发票簿等批量文档，生成效率很高，实测千页级文档也能稳定输出，内存占用也控制得不错，长文档场景可以放心使用。