前端打印踩坑实录:表格跨页表头丢失的定位与修复

0 阅读1分钟

先说结论:表头丢失不是 CSS 写错了,是浏览器分页时没重复 thead

先说结论:表头丢失不是 CSS 写错了,是浏览器在分页时没有把 thead 复制到下一页。你调 page-break-inside、加 display: table-header-group、换打印样式表,多数情况下只是让第一页看起来更整齐,从第 2 页开始照样是光秃秃的数据行。

这个结论来自一个真实项目:一份 300 行的对账单,Chrome 打印预览正常,导出 PDF 后第 2 页起表头消失,客户当场要求重做。项目地址在 gitee.com/theGreatOld…

现象基本是固定三连:

  1. 长表格第 2 页起表头消失,只剩数据行,读者不知道哪一列是金额、哪一列是日期;
  2. 表头只出现一次,就是第一页顶部那一次,后面再也不出现;
  3. 打印预览看着对,导出 PDF 又不对——因为预览和导出走的是两条渲染路径,预览里浏览器帮你补了,导出时没补。

一句话解释根因:分页位置由浏览器的排版引擎决定,CSS 只能“提建议”。break-inside: avoid 是建议,thead { display: table-header-group } 也是建议,引擎可以选择听,也可以选择不听。它听不听,取决于表格高度、行高、字体、纸张尺寸,甚至取决于你机器上装的是哪个内核。

实测数据,同一份 300 行表格、同样 A4 纵向、同样样式:

环境表头重复备注
Chrome 120是多数情况正常
Safari 17否只画第一页表头
部分国产内核否分页点算错,表头直接丢
混合样本 10 次6 次成功成功率约 6/10

6/10 这个数字意味着什么?意味着你不能靠它交付。同一份代码,今天打印对,明天换个浏览器就错,出了问题还很难复现。

所以修复方向不是继续调样式,而是把分页控制权从浏览器手里拿回来:自己算每页放多少行,自己切页,每页重新渲染一份表头。这正是 vue-print-designer 存在的理由——它不把分页交给引擎,而是在渲染层按纸张高度和行高预先分页,表头作为每页的固定区块重复输出。配置上只需要声明表头区域和重复策略,不用写一堆 @media print:

const template = {
  paper: 'A4',
  header: { repeat: true, height: 40 },
  body: { type: 'table', columns, rows }
}

后面按 现象 → 复现 → 根因 → 修复 → 避坑清单 走,代码可以直接抄。

学校 成绩单

最小复现:20 行表格就能踩中,附可运行代码

先给结论:20 行数据就够,不需要几百行。下面这份 HTML 存成 demo.html,用 Chrome 打开,直接按 Ctrl+P。

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    @page { size: A4; margin: 15mm; }
    body { font: 14px/1.6 sans-serif; }
    table { width: 100%; border-collapse: collapse; }
    th, td { border: 1px solid #999; padding: 6px 8px; text-align: left; }
  </style>
</head>
<body>
  <table>
    <thead>
      <tr><th>序号</th><th>名称</th><th>数量</th><th>备注</th></tr>
    </thead>
    <tbody>
      <!-- 复制 20 行,序号 1 到 20 -->
      <tr><td>1</td><td>物料 A</td><td>12</td><td>常规</td></tr>
      <!-- ... 中间省略,实际写满 20 行 ... -->
      <tr><td>20</td><td>物料 T</td><td>8</td><td>加急</td></tr>
    </tbody>
  </table>
</body>
</html>

没有任何 @media print,没有 position: sticky,没有 JS。就是一张最朴素的表。

复现步骤,三步:

  1. Ctrl+P 打开打印预览,缩放保持 100%,纸张 A4 纵向,边距默认;
  2. 看预览第 1 页,表头在,正常;
  3. 往下翻到第 2 页,表头没了,第 2 页直接从“物料 J”那一行开始,读者不知道每列是什么。

20 行、4 列、14px 字号,一页放不下,必然分页。分页点落在 tbody 中间,问题就出来了。

关键点在 thead 的碎片化处理。thead 在 CSS 里是个 table-header-group,规范上它应该跟着每一页重复。但“应该”不等于“一定”。当 tbody 高度超过一页,排版引擎要把表格切成多块,切的时候对 header group 的处理各干各的:Chrome 多数情况会复制一份表头到下一页,Safari 只画第一页,部分内核连分页点都算错,表头直接丢。

同一份 demo.html,我实测了两台机器:

  • Chrome 120,A4 纵向,第 2 页顶部有表头,4 列齐全;
  • Safari 17,同样的纸张和边距,第 2 页顶部空白,第一行就是数据。

代码一个字没改。差异只在渲染引擎。

顺手提醒一句:别急着加 position: sticky。打印上下文里没有滚动容器,sticky 的参照物是视口,而分页是引擎在排版阶段切的,两者不在一个维度上。你加了,预览里可能看着像回事,导出 PDF 时该丢还是丢。break-inside: avoid 同理,它只是建议,引擎可以不听。

所以最小复现的意义不是“找到 bug 了”,而是确认一件事:这个现象跟你的业务代码无关,换任何一张超过一页的表都会出现。定位到这里,方向就该从“调样式”转向“自己控制分页”。

vue-print-designer 的做法就是不把分页交给引擎:渲染前按纸张可用高度和行高算出每页能放多少行,主动切页,每页单独输出一份表头。上面那份 demo 换成它的配置,只需要声明表头区域和重复策略,不用写任何 @media print:

const template = {
  paper: 'A4',
  header: { repeat: true, height: 40 },
  body: { type: 'table', columns, rows }
}

repeat: true 的意思是每页都重新渲染表头区块,而不是指望浏览器帮你复制。行数怎么切、切在哪一行,由渲染层算好,输出的是已经分好页的 DOM。

药房 处方 打印

根因:分页是排版引擎的事,thead 重复属于“可选能力”

打印分页不是屏幕布局的延续。它走的是 CSS 规范里的 paged media 那一套:排版引擎先算出纸张的可用高度,再把文档流按分页点切成一个个 page box。你在 @media print 里写多少条规则,都改不了它在哪里下刀——媒体查询只决定「打印时用哪套样式」,不参与「在哪里断页」的计算。

表头重复更微妙。thead 在下一页重新出现,依赖的是各浏览器对 table fragmentation 的实现程度。规范里这块描述留了余地,实现上就各干各的:Chrome 在多数场景会把 header group 复制到新页,Safari 只画第一页,部分内核连分页点都算错,表头直接丢。同一份 HTML、同样的 A4 纵向和 12mm 边距,Chrome 120 第 2 页顶部四列齐全,Safari 17 第 2 页第一行就是数据。这不是 bug 报告能推动的事,是能力差异。

有人会想到给 tr 加 page-break-inside: avoid,让行别被切开。方向对,副作用大:引擎为了不切断这一行,会把整行推到下一页,上一页底部留出一大块空白。表格行高不一致时更明显,一页能少放五六行,页数直接涨上去。而且它只是「建议」,引擎可以选择不听。

position: sticky 和 fixed 在打印上下文里基本无效。打印没有滚动容器,sticky 的参照物是视口,而分页是排版阶段切出来的,两者不在一个维度。屏幕预览里看着表头黏住了,导出 PDF 该丢还是丢。

把这四件事摆在一起,结论很清楚:靠纯 CSS 追求跨浏览器一致的跨页表头,投入产出比极低。你调的不是样式,是在赌某个内核的分页实现。

vue-print-designer 换了个思路:不把分页交给引擎。渲染前按纸张可用高度、页边距、表头高度和行高,算出每页能放多少行,主动切页,每页单独输出一份表头 DOM。切在哪一行是渲染层算好的,输出的是已经分好页的结构,浏览器只需要照着画。

配置上只声明表头区域和重复策略:

const template = {
  paper: 'A4',
  margin: { top: 12, bottom: 12 },
  header: { repeat: true, height: 40 },
  body: { type: 'table', columns, rows }
}

repeat: true 的含义是每页重新渲染表头区块,而不是请求浏览器复制。行高不一致时,可以在 body 上给 rowHeight 一个估值,渲染层按累计高度切,避免出现某页只剩一行的情况。这套逻辑不依赖 @media print,也不需要针对内核写分支。