3分钟封装一个完美 PDF 导出工具：支持图表保护、自动分页与异步防卡死

在前端开发中，将复杂的网页内容（如长报表、多图表看板）导出为 PDF 是一个常见但充满挑战的需求。通常我们会使用 html2canvas + jspdf 这对黄金组合，但在实际应用中，往往会遇到以下“灾难级”问题：

• 内容丢失：滚动区域下方的隐藏内容没有被导出。
• 元素被腰斩：分页线刚好落在 ECharts 图表或文字段落中间，被切成了两半。
• 黑底现象：PDF 最后留白的地方出现了一片黑块。
• 浏览器无响应：导出稍长一点的页面，浏览器直接弹窗提示“页面无响应，是否关闭”。

为了彻底解决这些痛点，本文梳理了一套完整的解决方案，并将其封装为一个高可用、支持 TypeScript 的工具类。

一、 技术思路

想要实现完美的长页面导出，我们需要对症下药：

二、 实现路程介绍

1. 临时展开 DOM：获取目标容器，记录原始样式，修改为可见状态，并通过 scrollHeight 告诉 html2canvas 完整高度。
2. 渲染为大长图：配置 html2canvas，开启白底、跨域，并利用 ignoreElements 过滤掉不需要导出的元素（如导出按钮、敏感信息）。
3. 计算避让断点：遍历所有传入的选择器（如 .avoid-break, p, tr），根据它们距离顶部的偏移量，计算出在最终 Canvas 像素中的 startY 和 endY 区间。
4. 智能切片与分页：通过 while 循环，按 A4 纸的高度（转换为像素）切割 Canvas。每次切割前检查刀口是否命中“避让区间”，若是则将刀口提前至该元素顶部。切片后转为图片塞入 jspdf。
5. 异步防卡死：在循环中加入 await delay(0)，让浏览器在密集计算时有喘息之机。

三、 完整代码

建议新建一个 htmlToPdf.ts 文件，放入以下代码：

 复制代码import html2Canvas from "html2canvas";
import jsPDF from "jspdf";interface PdfExportOptions {
  // 需要避免被分页截断的元素选择器数组，如 ['.avoid-break', 'p', 'tr']
  noBreakSelectors?: string[];
  // 导出时需要排除(隐藏)的元素 ID 数组
  excludeIds?: string[];
  // 渲染倍率，默认 1.5（降低倍率可大幅缓解无响应问题）
  scale?: number;
}// 工具函数：让出主线程，防止浏览器卡死
const delay = (ms: number = 0) => new Promise((resolve) => setTimeout(resolve, ms));const htmlToPdf = {
  /**
   * 异步导出 PDF
   * @param title 文件名
   * @param id 要截取的根元素选择器
   * @param options 配置项
   */
  async getPdf(title: string, id: string, options?: PdfExportOptions): Promise<void> {
    const { 
      noBreakSelectors = [".avoid-break"], 
      excludeIds = [], 
      scale = 1.5 
    } = options || {};
    
    const pdfContent = document.querySelector(id) as HTMLElement | null;
    if (!pdfContent) {
      throw new Error(`Element with selector "${id}" not found.`);
    }    // 1. 临时修改样式，确保滚动区域全部展开被捕获
    const originalOverflow = pdfContent.style.overflow;
    const originalHeight = pdfContent.style.height;
    const containerRect = pdfContent.getBoundingClientRect();    pdfContent.style.overflow = "visible";
    pdfContent.style.height = "auto";    // 【关键优化1】：让出主线程，让浏览器有机会渲染 Loading 动画，缓解"无响应"
    await delay(50);    try {
      // 2. Canvas 渲染图像
      const canvas = await html2Canvas(pdfContent, {
        logging: false,
        useCORS: true,
        scale: scale, // 降低 scale 减少计算压力
        backgroundColor: "#ffffff", // 防止透明变黑
        height: pdfContent.scrollHeight,
        windowHeight: pdfContent.scrollHeight,
        ignoreElements: (element) => {
          // 过滤掉需要排除的元素
          return excludeIds.includes(element.id);
        },
      });      // 恢复原有样式
      pdfContent.style.overflow = originalOverflow;
      pdfContent.style.height = originalHeight;      const pdf = new jsPDF("p", "mm", "a4");
      const margin = 10;
      const a4Width = 190; // A4宽 210 - 边距 20
      const a4Height = 277; // A4高 297 - 边距 20      const pxPerMm = canvas.width / a4Width;
      const pageHeightPx = a4Height * pxPerMm;      // 3. 收集所有需要避免截断的元素坐标
      const breakPoints: Array<{ startY: number; endY: number }> = [];
      noBreakSelectors.forEach(selector => {
        const els = pdfContent.querySelectorAll(selector);
        els.forEach((el) => {
          const rect = el.getBoundingClientRect();
          const startY = (rect.top - containerRect.top) * scale;
          const endY = startY + rect.height * scale;
          breakPoints.push({ startY, endY });
        });
      });      let currentY = 0;
      let pageIndex = 0;      // 4. 智能分页切割 Canvas
      while (currentY < canvas.height) {
        let targetEndY = currentY + pageHeightPx;        // 检查是否切到了需要保护的元素
        for (let point of breakPoints) {
          if (targetEndY > point.startY && targetEndY < point.endY) {
            targetEndY = point.startY; // 提前换页，将元素推到下一页
            break;
          }
        }        // 边界保护
        if (targetEndY <= currentY) targetEndY = currentY + pageHeightPx;
        if (targetEndY > canvas.height) targetEndY = canvas.height;        const cropHeight = targetEndY - currentY;
        const cropCanvas = document.createElement("canvas");
        cropCanvas.width = canvas.width;
        cropCanvas.height = cropHeight;
        const ctx = cropCanvas.getContext("2d");
        
        if (ctx) {
          // 填充白色背景，解决最后留白处变黑的问题
          ctx.fillStyle = "#ffffff";
          ctx.fillRect(0, 0, cropCanvas.width, cropCanvas.height);          ctx.drawImage(
            canvas,
            0, currentY, canvas.width, cropHeight,
            0, 0, canvas.width, cropHeight
          );          const cropImgData = cropCanvas.toDataURL("image/jpeg", 1.0);
          const cropHeightMm = cropHeight / pxPerMm;          if (pageIndex > 0) pdf.addPage();
          pdf.addImage(cropImgData, "JPEG", margin, margin, a4Width, cropHeightMm);
        }        currentY = targetEndY;
        pageIndex++;
        
        // 【关键优化2】：每切一页让出主线程，防止切片循环导致浏览器假死
        await delay(0); 
      }      pdf.save(title + ".pdf");
    } catch (err) {
      // 发生异常时恢复样式并抛出错误
      pdfContent.style.overflow = originalOverflow;
      pdfContent.style.height = originalHeight;
      console.error("导出PDF失败:", err);
      throw err; 
    }
  },
};export default htmlToPdf;

四、 使用示例

在你的 Vue/React 组件中引入并使用。推荐结合 async/await 处理 Loading 状态。

1. HTML 结构准备

为需要保护不被切断的元素加上 avoid-break 类名。

 复制代码<div id="report-container">
  <h1>季度数据报表</h1>
  <div class="avoid-break">
    <!-- ECharts 图表内容 -->
  </div>
  <p>这是一段重要的说明文字，不希望被分页截断。</p>
  <button id="export-btn" @click="handleExport">导出 PDF</button>
</div>

2. 业务代码调用

 复制代码import htmlToPdf from './utils/htmlToPdf';const handleExport = async () => {
  // 1. 开启页面 loading 动画
  this.loading = true; 
  
  try {
    // 2. 调用导出方法
    await htmlToPdf.getPdf("季度数据报表", "#report-container", {
      // 保护 Echarts 图表、段落文字 p 不被切断
      noBreakSelectors: [".avoid-break", "p", "tr"], 
      // 导出时排除导出按钮
      excludeIds: ["export-btn"], 
      // 清晰度与性能的平衡点
      scale: 1.5, 
    });
    
    // 3. 导出成功提示
    this.$message.success("PDF 导出成功！");
  } catch (error) {
    this.$message.error("导出失败，请重试");
  } finally {
    // 4. 关闭 loading 动画
    this.loading = false; 
  }
};

五、 总结

前端原生导出 PDF 本质上是一个“DOM 转图片 -> 图片再切片排版”的过程。只要我们控制好 DOM 的展开状态、处理好图片切割时的边界避让，并时刻警惕主线程阻塞，就能实现堪比后端生成的完美 PDF 报表。

希望这套方案能帮大家填平 html2canvas 导出的各种大坑！如果有更好的优化思路，欢迎在评论区交流。