上篇写了普通内容块的分页处理这篇单独把表格行截断拎出来聊。如果你做过“把网页表格导出成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。分页容器法的核心优势在于截断发生在“行与行之间”而不是“行内部”。因为每个临时容器里放进去的都是完整的trhtml2canvas渲染它时根本不存在跨页这个动作自然不会有截断。方案行完整性样式还原度实现复杂度适用场景行级canvas拼接高一般较高简单表格无合并单元格整图 行边界切片中较高高行高稳定想省DOM操作分页容器法高高中报表、明细表、复杂表格2.2 分页容器法的整体流程这个方案的完整流程可以拆成五步遍历表格的所有tr用getBoundingClientRect()测量每行的实际高度。设置一个“页面可用高度”通常是PDF页面高度减去上下边距。从第一行开始累加行高如果当前页已经放不下一行完整内容就把这一行放到新的一组里。对每一组行创建一个临时div把表格克隆一份只保留这一组对应的行放进临时div。临时div的宽度要和PDF内容区宽度一致。对临时div执行html2canvas得到一个单页canvas。把这个canvas通过jsPDF的addImage添加到当前页然后执行addPage()继续处理下一组。为什么要逐个临时容器渲染而不是把整个表格渲染一次然后用canvas裁剪因为裁剪的本质还是像素操作表格行是否完整完全依赖你算出来的y坐标一旦有误差截断问题会以另一种形式回来。而在DOM层面分组后每组是一个独立的、完整的DOM快照html2canvas渲染出来的就是“这一页应有的全部内容”误差被压缩到最小。3. 完整实现从行测量到PDF落地3.1 测量行高别用offsetHeight分页的基础是行高测量。很多人用offsetHeight这在表格显示正常时问题不大但一旦表格在隐藏的tab里或者外层容器有display: noneoffsetHeight会直接变成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 问题速查表整个方案实现过程中我整理了一个问题速查表按照经验频率排序供参考。现象可能原因解决方案每页最后一行总被截断依赖整张canvas硬切改用分页容器法按行分组页面之间出现空白页行高测量值和实际渲染值偏差增加tolerance修复临时容器样式行背景色分页后不对tr背景和td背景同时存在给td设置内联背景避免半行渲染断层表格边框在分页处缺失border-collapse跨容器渲染问题临时容器设置border-collapse: collapse并固定width中文变成方块或乱码低级文本添加模式下字体缺失用canvas图片输出不需要嵌入字体表格里的图片不显示跨域图片未允许加载html2canvas加useCORS: true图片转base64行高测出来是0表格在隐藏容器中先显示再测量或使用离线不可见但占位的方式渲染导出后表格被拉伸变形addImage宽高比例和canvas不一致固定addImage的宽高为contentWidth/contentHeight5.2 实操中容易被忽略的样式细节第一临时容器的背景色一定要设成白色否则html2canvas会把透明区域渲染成黑色或者带灰色杂点。尤其表格存在半透明背景色时透明叠加的问题会很明显。第二jsPDF里addImage的格式参数建议直接写PNG不要用JPEG。PNG对表格这种强线条内容的还原度更好JPEG在文字边缘容易产生压缩色斑导出的表格看起来像被水泡过一样。第三如果表格特别宽不要硬塞进A4纵向页面。合理的做法是先判断表格的宽度是否超过contentWidth如果超过就该用A4横向或者等比缩小表格后再测量行高。顺序很重要缩小前测量和缩小后测量的行高完全不同必须等缩放完成再执行getBoundingClientRect。5.3 一个更省心的扩展方向分页容器法解决了“行被切断”的核心问题但每次导出都要重建DOM数据量特别大的时候性能会有点吃紧。我后来在项目里做了一个优化把行分组的计算放到Web Worker里只传行高数组不传DOM。主线程只负责临时容器的创建和销毁这样1000行以上的表格导出页面也不会卡死。另外如果你不想重复造轮子第三方库自带的某些pagebreak模式本质上也是类似思路。不过说实话依赖库的封装虽然省事一旦遇到你业务里的特殊表格比如多级表头、列合并、行合并理解和调试的成本反而更高。自己掌握这套分组逻辑遇到问题能很快定位到是测量、分组还是渲染环节出的问题。最后再分享一个实际经验我刚开始做导出功能时也偷懒用过“整图硬切”直到被产品拿着一张表头断了半截的PDF截图找上门才老老实实把分页逻辑重写了一遍。分页容器法写完之后最大的感受是所有和“截断”相关的bug都变得特别容易排查因为每一页的DOM结构是我亲手组出来的只要这一页容器渲染没问题PDF必然没问题。如果你现在正被表格行截断折磨建议直接按这篇文章的思路抄一遍测量行高、按行分组、逐页渲染。跑通一个最简单的案例之后再往里面加你要处理的合并单元格、超长行和图片会顺手很多。