企业官网建设流程全解析

上篇写了普通内容块的分页处理，这篇单独把表格行截断拎出来聊。如果你做过“把网页表格导出成PDF”这件事，大概率见过这种场景：表格一共20行，第一页底部出现半行文字，下一页顶部又出现另外半行；或者表头在第一页，第二页光秃秃地飘着几行数据，怎么都对不上。用html2canvas把整个表格截成长图，再交给jsPDF按页面高度去切，表格行被拦腰斩断几乎是必然的。原因不复杂，表格的行高很少能刚好整除PDF页面高度，而jsPDF的addImage只认画布坐标，到页面边界就是一刀切，它根本不知道“这一行是一个整体”。

这篇文章专门讲表格行截断的处理方案，重点放在“先按行分页，再逐页渲染”的分页容器法，同时会聊超高行的拆分、测量误差和几个我实际踩过的坑。代码可以直接抄，适配报表、订单明细、长文本备注这类常见表格导出场景。

1. 先弄清楚：表格行到底是怎么被“切断”的

1.1 一张长图切成多页，截断是数学上的必然

先说根因。我们最常写的导出逻辑是这样：先用html2canvas把整个table生成一张canvas，再用jsPDF的addImage把canvas画到PDF里。如果canvas高度超过一页，就手动截取canvas的一段，放到新的一页上。

这个思路本身没问题，问题出在“截取”的边界完全由页面高度决定。假设PDF页面内容区高度是700px，表格从顶部往下数，第10行的顶部在680px，底部在712px。那么第一页画到700px时，这一行只剩了20px；第二页又从700px开始画，于是这一行的另外12px出现在第二页。文字被横着劈开，边框中间断掉，这就是最常见的截断现象。

从jsPDF的角度看，它没有“HTML表格”这个概念，只有一串像素。它不可能知道某一行是否完整，因为传入的canvas是一整张位图。这才是所有表格截断问题的大前提：只要你在“整张canvas”上动手脚，行边界就只能靠算法去猜。猜得准，表格完整；猜不准，半行文字就来了。

1.2 表格行比普通div更麻烦的三个原因

为什么上篇处理普通段落和卡片时，用简单的canvas切片还能忍，到了表格就非得专门写一套逻辑？因为表格行有三个特殊之处。

第一是背景色。表格经常给tr设置斑马纹或表头底色，如果一行被切成两半，第一页底部的半行和第二页顶部的半行背景色是分开渲染的。在某些浏览器里，半行背景还会出现颜色断层，看起来像两条颜色不同的记录。

第二是边框。尤其border-collapse: collapse下，行边框是重叠计算的。切片的位置一旦落在边框线上，导出的PDF就会出现“有的行有上边框、有的行没有下边框”的残缺效果。你去看canvas原图是完好的，但切成多页后就裂了。

第三是行内内容的高度不稳定。单元格里有长文本、图片、超长英文单词时，行高是动态算出来的。同一个表格在不同屏幕宽度下，行高可能差出几十px。如果你用固定行高去分页，一旦测量值和实际渲染值有偏差，分页位置就会偏移，然后又开始截断。

所以处理表格行截断，不能走“整图硬切”的老路，必须让分页逻辑感知到每一行的边界。

2. 推荐路线：按行分页的“分页容器法”

2.1 常见方案对比

解决表格行截断，网上能搜到的方法大致有三种。

第一种是“行级canvas拼接”。对每一行分别跑html2canvas，生成一个个小canvas，再按顺序添加到PDF。优点是每一行一定是完整的，缺点也很明显：行与行之间的背景、边框、间距容易对不齐，而且如果一行里包含列合并或跨行合并的单元格，单行渲染出来的结构会乱掉。

第二种是“整张canvas + 行边界切片”。先把整表渲染成canvas，然后拿到每一行在canvas中的像素y坐标，把图片按行边界来切，而不是按固定高度切。思路是对的，但实现里要处理retina缩放、表格边框半像素、行边界计算偏差，稍有不慎就会出现“上一页多切了一行，下一页少了半行”的问题。

第三种就是我推荐的分页容器法：不直接把整个表格交给html2canvas，而是先在DOM层面把表格的行按页面容量分成若干组，每组生成一个只包含完整行的临时容器，然后对每个临时容器单独跑html2canvas，再一页一页写入jsPDF。

分页容器法的核心优势在于：截断发生在“行与行之间”，而不是“行内部”。因为每个临时容器里放进去的都是完整的tr，html2canvas渲染它时，根本不存在跨页这个动作，自然不会有截断。

2.2 分页容器法的整体流程

这个方案的完整流程可以拆成五步：

1. 遍历表格的所有tr，用getBoundingClientRect()测量每行的实际高度。
2. 设置一个“页面可用高度”，通常是PDF页面高度减去上下边距。从第一行开始累加行高，如果当前页已经放不下一行完整内容，就把这一行放到新的一组里。
3. 对每一组行创建一个临时div，把表格克隆一份，只保留这一组对应的行，放进临时div。临时div的宽度要和PDF内容区宽度一致。
4. 对临时div执行html2canvas，得到一个单页canvas。
5. 把这个canvas通过jsPDF的addImage添加到当前页，然后执行addPage()，继续处理下一组。

为什么要逐个临时容器渲染，而不是把整个表格渲染一次然后用canvas裁剪？因为裁剪的本质还是像素操作，表格行是否完整完全依赖你算出来的y坐标，一旦有误差，截断问题会以另一种形式回来。而在DOM层面分组后，每组是一个独立的、完整的DOM快照，html2canvas渲染出来的就是“这一页应有的全部内容”，误差被压缩到最小。

3. 完整实现：从行测量到PDF落地

3.1 测量行高：别用offsetHeight

分页的基础是行高测量。很多人用offsetHeight，这在表格显示正常时问题不大，但一旦表格在隐藏的tab里，或者外层容器有display: none，offsetHeight会直接变成0。所以更稳妥的是用getBoundingClientRect()，它返回的是元素实际渲染后的几何尺寸，对transform、缩放也更敏感。

还有一点，如果你准备用html2canvas的scale参数提高清晰度，要注意：行高本身是按CSS像素计算的，而canvas是按scale放大后的像素计算的。所以不要把两者混在一起。我的做法是先把CSS像素下的行高全部测量完，再在渲染临时容器时统一乘以scale。

3.2 核心代码：行分组函数

先把行分组逻辑写出来，这是整个方案的地基：

function groupRowsByPage(rows, rowHeights, contentHeight, tolerance = 12) { const pages = []; let currentPageRows = []; let usedHeight = 0; rows.forEach((row, index) => { const rowHeight = rowHeights[index]; if (usedHeight + rowHeight > contentHeight + tolerance && currentPageRows.length > 0) { pages.push(currentPageRows); currentPageRows = []; usedHeight = 0; } currentPageRows.push(row); usedHeight += rowHeight; }); if (currentPageRows.length > 0) { pages.push(currentPageRows); } return pages; }

tolerance是一个容差参数。它的作用是避免“只差几px就分页”造成的过度敏感。比如某一行底部比页面可用高度多出了8px，如果不加容差，这行会被强制分到新页；但8px实际上完全可以通过行距或padding吃进去，不加容差反而会让页面底部多出一大片空白。

这个容差也不能给太大。我给12px，是因为大多数表格的单元格padding在4px到10px之间，12px足够抵消测量误差，又不会造成内容溢出到页面外。

3.3 单页容器渲染与PDF输出

分组完成后，接下来是渲染和输出。先写一个渲染单页row组的方法：

async function renderRowsToCanvas(pageRows, contentWidth, tableClone, scale = 2) { const wrapper = document.createElement('div'); wrapper.style.position = 'absolute'; wrapper.style.left = '-9999px'; wrapper.style.top = '0'; wrapper.style.width = `${contentWidth}px`; wrapper.style.backgroundColor = '#ffffff'; wrapper.style.padding = '0'; wrapper.style.margin = '0'; const clonedTable = tableClone.cloneNode(true); const allClonedRows = Array.from(clonedTable.querySelectorAll('tr')); // 把不在当前页的行全部移除 allClonedRows.forEach((clonedRow, index) => { if (!pageRows.includes(index)) { clonedRow.remove(); } }); wrapper.appendChild(clonedTable); document.body.appendChild(wrapper); try { const canvas = await html2canvas(wrapper, { scale: scale, useCORS: true, backgroundColor: '#ffffff', logging: false, windowWidth: contentWidth, }); return canvas; } finally { document.body.removeChild(wrapper); } }

注意，pageRows传的是行的索引数组，因为克隆表里的行和原始表的行不是同一个对象，直接传DOM对象反而容易错位。用索引对应是最稳妥的。

然后是主流程：

async function exportTableToPdf(tableSelector) { const table = document.querySelector(tableSelector); const rows = Array.from(table.querySelectorAll('tr')); // 等待表格稳定渲染 await new Promise((resolve) => requestAnimationFrame(() => setTimeout(resolve, 50))); const rowHeights = rows.map((row) => row.getBoundingClientRect().height); const { jsPDF } = window.jspdf; const pdf = new jsPDF('p', 'pt', 'a4'); const pageWidth = pdf.internal.pageSize.getWidth(); const pageHeight = pdf.internal.pageSize.getHeight(); const margin = { top: 40, bottom: 40, left: 40, right: 40 }; const contentWidth = pageWidth - margin.left - margin.right; const contentHeight = pageHeight - margin.top - margin.bottom; const pages = groupRowsByPage(rows, rowHeights, contentHeight); const tableClone = table.cloneNode(true); for (let i = 0; i < pages.length; i++) { const pageRowIndexes = pages[i]; const canvas = await renderRowsToCanvas(pageRowIndexes, contentWidth, tableClone); const imgData = canvas.toDataURL('image/png'); if (i > 0) { pdf.addPage(); } pdf.addImage(imgData, 'PNG', margin.left, margin.top, contentWidth, contentHeight); } pdf.save('table-export.pdf'); }

这里有几个关键点。

第一，pdf.addImage的宽高要固定成contentWidth和contentHeight，而不是直接使用canvas的像素尺寸。因为html2canvas画出来的canvas宽度可能因为scale变成contentWidth * 2，如果把这个像素宽度直接传给jsPDF，页面会严重超出边界。

第二，因为每页的canvas宽高比例和PDF内容区是一致的，即使某一行组的总高度小于contentHeight，图片也会被拉伸填满整页。所以如果某页只有一行内容，这行会被放大，这在小范围内可以接受，但如果你不想拉伸，可以按实际行组总高度去计算addImage的高度，再在页面垂直居上放置。这个根据实际需求调整。

第三，我加了50ms的延迟，是为了给浏览器一点时间去完成表格的reflow。如果你在表格刚插入DOM、图片还没加载完时就测量，行高一定是错的。这一步看起来多余，但实际导出报表时，很多诡异的分页错位都是因为“测量时表格还没稳定”。

3.4 行高差一个像素导致莫名的空白页

我用这套方案时遇到过一种奇怪现象：导出的PDF在每两页之间会夹一个几乎全白的页面，里面只有一行孤零零的数据。查了很久，发现是测量高度和实际渲染高度差了1px到2px。

原因是html2canvas在渲染临时容器时，临时容器是绝对定位的，脱离正常文档流。原始表格里的字体、行高、边框在脱离流以后，可能会因为父容器宽度变化产生细微的reflow。解决方法是让临时容器的样式尽量还原原始表格所在的环境，特别是font-family、line-height、width、border-collapse。如果还不够，把groupRowsByPage的容差从12改成16，基本就能把这种情况吸收掉。

4. 单行超过一页怎么办

4.1 场景

分组逻辑会假设每一行的高度都小于contentHeight。但报表里经常有一种“超长备注行”，一个单元格里塞了几百字甚至上千字，行高超过一整页。这时分组代码会进入一个尴尬分支：如果rowHeight > contentHeight，并且currentPageRows为空，这一行还是会硬塞进当前页。结果就是addImage时整个页面塞满，内容溢出，或者html2canvas渲染出来的高度超过PDF页面，又被jsPDF裁掉一部分。

遇到这种情况，任何“整行移动”的思路都没用。因为这一行本身放不进任何一页，唯一的办法是拆行。

4.2 按单元格内部的块级子元素重排

拆行的基本思路是：不要把tr当成不可分割的最小单元，而是继续往下钻，把tr拆成若干“虚拟行”。具体来说，一行里的每个单元格，内部往往包含多个块级元素，比如p、div、ul、列表项。我们可以按这些子元素的高度累计，把它们分配到多个页中。

以最常见的td里多个p标签为例：

function splitTallRowIntoFragments(tdElements, fragmentHeight) { const fragments = []; let currentFragment = []; let usedHeight = 0; tdElements.forEach((td) => { const children = Array.from(td.children); children.forEach((child) => { const childHeight = child.getBoundingClientRect().height; if (usedHeight + childHeight > fragmentHeight && currentFragment.length > 0) { fragments.push(currentFragment); currentFragment = []; usedHeight = 0; } currentFragment.push(child.cloneNode(true)); usedHeight += childHeight; }); }); if (currentFragment.length > 0) { fragments.push(currentFragment); } return fragments; }

拿到fragments之后，为每个fragment创建一个临时tr：把每个单元格里属于当前fragment的子元素clone出来，放进对应的td中，其他子元素全部移除。这个临时tr就是“虚拟行”，它的行高刚好在一页容量的范围内。然后把这组虚拟行用之前的分组逻辑继续处理即可。

这个方案会牺牲一部分视觉完整性，比如一个单元格里的两个段落可能被分到两页，但至少不会出现文字被水平切成两半的问题。在真实业务里，长备注跨页比切断文字更容易接受。

4.3 拆分后的表头处理

拆分出来的续页，最好在顶部补一个重复表头，否则读者看到第二页、第三页时，根本不知道那些长文本对应的是哪一列。

实现上，分组时不要只存当前页的行，还要同时在每个页组合里插入一个标记：如果当前页不是第一页，且表格有thead，就把表头行对应的clone放到页组合的最前面。注意，插入表头会占用高度，所以分组的时候要把表头高度预留在contentHeight里扣除。我习惯把contentHeight先减掉一个表头高度，分完组后再在渲染阶段把表头行插进去，这样分页不会被表头挤乱。

5. 常见问题与排查心得

5.1 问题速查表

整个方案实现过程中，我整理了一个问题速查表，按照经验频率排序，供参考。

5.2 实操中容易被忽略的样式细节

第一，临时容器的背景色一定要设成白色，否则html2canvas会把透明区域渲染成黑色，或者带灰色杂点。尤其表格存在半透明背景色时，透明叠加的问题会很明显。

第二，jsPDF里addImage的格式参数建议直接写PNG，不要用JPEG。PNG对表格这种强线条内容的还原度更好，JPEG在文字边缘容易产生压缩色斑，导出的表格看起来像被水泡过一样。

第三，如果表格特别宽，不要硬塞进A4纵向页面。合理的做法是先判断表格的宽度是否超过contentWidth，如果超过，就该用A4横向，或者等比缩小表格后再测量行高。顺序很重要：缩小前测量和缩小后测量的行高完全不同，必须等缩放完成，再执行getBoundingClientRect。

5.3 一个更省心的扩展方向

分页容器法解决了“行被切断”的核心问题，但每次导出都要重建DOM，数据量特别大的时候性能会有点吃紧。我后来在项目里做了一个优化：把行分组的计算放到Web Worker里，只传行高数组，不传DOM。主线程只负责临时容器的创建和销毁，这样1000行以上的表格导出，页面也不会卡死。

另外，如果你不想重复造轮子，第三方库自带的某些pagebreak模式本质上也是类似思路。不过说实话，依赖库的封装虽然省事，一旦遇到你业务里的特殊表格，比如多级表头、列合并、行合并，理解和调试的成本反而更高。自己掌握这套分组逻辑，遇到问题能很快定位到是测量、分组还是渲染环节出的问题。

最后再分享一个实际经验

我刚开始做导出功能时，也偷懒用过“整图硬切”，直到被产品拿着一张表头断了半截的PDF截图找上门，才老老实实把分页逻辑重写了一遍。分页容器法写完之后，最大的感受是：所有和“截断”相关的bug都变得特别容易排查，因为每一页的DOM结构是我亲手组出来的，只要这一页容器渲染没问题，PDF必然没问题。如果你现在正被表格行截断折磨，建议直接按这篇文章的思路抄一遍：测量行高、按行分组、逐页渲染。跑通一个最简单的案例之后，再往里面加你要处理的合并单元格、超长行和图片，会顺手很多。