JS 生成的统计图怎么导出为 PNG 图片或 PDF 文件？

一、识别图表的底层形态：Canvas 与 SVG

在编写导出代码之前，首要任务是确认目标统计图在浏览器中到底以什么形态渲染。主流前端图表库通常采用两种渲染方案之一：一种是直接在 <canvas> 上进行位图绘制（例如 Chart.js 全系、ECharts 默认的 Canvas 渲染器）；另一种则是在页面中生成一棵由 <svg>、<path>、<rect>、<text> 等矢量图元构成的 DOM 树（例如 D3.js、Highcharts 以及 ECharts 开启 SVG 模式后生成的结果）。

这两种介质决定了后续导出路径的根本差异：Canvas 本身就是浏览器显存中管理的一块像素画布，天然支持提取二进制位图，但它无法直接输出原生可缩放的矢量 PDF；SVG 拥有结构化的矢量定义，在任意缩放比例下都极其锐利，但浏览器并未为 SVG DOM 元素提供类似 toBlob() 的原生栅格化方法。理解这一分歧是设计导出流程的基础前提。

实际开发中，可以通过浏览器的“检查元素”工具查看图表容器内部的标签：若容器内是一个带有固定像素宽高的 <canvas> 标签，则归属于 Canvas 链路；若看到的是一个挂载了大量图元子节点的 <svg> 标签，则必须走 SVG 序列化链路。

二、统计图导出为 PNG 图片的实战方案

1. Canvas 统计图的原生导出机制与下载触发

对于 Canvas 渲染的统计图，导出 PNG 最简便直接的方式是调用 Canvas API。许多开发者习惯使用 canvas.toDataURL('image/png')，但这在生产环境中存在隐患：该方法同步返回一段超长的 Base64 字符串，由于 Base64 编码存在约 33% 的体积冗余，对于分辨率较高或尺寸庞大的统计图，极易触发主线程顿卡甚至造成内存暴涨。

更为稳妥的做法是采用异步的 canvas.toBlob()。它直接在浏览器内部生成紧凑的二进制 Blob 对象，配合隐藏的 <a> 标签和 URL.createObjectURL() 触发下载，并在下载完成后及时调用 URL.revokeObjectURL() 释放内存引用。

2. 解决高分屏（Retina / 4K）导出图片模糊发虚

一个极其普遍的现象是：图表在屏幕上看起来非常清晰，但导出的 PNG 文件在手机或高分屏上放大查看时边缘毛糙、字迹模糊。这是因为图表在屏幕上是按照 CSS 逻辑像素显示的，而现代设备的 window.devicePixelRatio（设备像素比，简称 DPR）往往为 2 或 3。

如果直接截取当前屏幕上的 Canvas，其物理像素只有逻辑像素的一倍。要生成出版物级别的高清图，需要在导出前对画布进行高倍率绘制补偿：以原尺寸乘以 DPR（例如 2 或 3）作为物理分辨率重新渲染，或者借助 ECharts 实例内置的 getDataURL({ pixelRatio: 2 }) 参数直接提取高倍图。

3. SVG 统计图转 PNG 的 5 步数据流转

SVG 统计图导出为 PNG 无法一蹴而就，必须通过跨介质中转完成栅格化。具体步骤包括：首先通过 XMLSerializer 将 SVG DOM 树序列化为符合 XML 规范的字符串；其次封装为包含 image/svg+xml MIME 类型的 Blob 并生成临时对象 URL；第三步创建 HTMLImageElement 对象并异步加载该 URL；第四步在内存中构建带有目标高倍尺寸的离屏 Canvas，将解码完成的图像绘制到 Canvas 上；最后调用 canvas.toBlob() 输出 PNG 二进制流。

4. 通用 PNG 导出工具函数实现

下面是一个封装好的跨 Canvas 与 SVG 的高保真 PNG 导出函数，支持自动适配设备像素比以保障输出画质：

/**
 * 将指定容器内的统计图（支持 Canvas 或 SVG）导出为高质量 PNG 图片
 * @param {HTMLElement} container 图表所在的根 DOM 容器
 * @param {string} filename 导出保存的文件名称（需包含 .png 扩展名）
 * @param {number} scaleFactor 导出分辨率放大倍率，默认取 2 倍以适应高清屏幕
 */
async function exportChartToPNG(container, filename = 'chart.png', scaleFactor = 2) {
  const canvasNode = container.querySelector('canvas');
  const svgNode = container.querySelector('svg');

  if (canvasNode) {
    // 针对原生 Canvas 容器：克隆并重绘为高分辨率位图
    const originalWidth = canvasNode.width;
    const originalHeight = canvasNode.height;

    const offscreen = document.createElement('canvas');
    offscreen.width = originalWidth * scaleFactor;
    offscreen.height = originalHeight * scaleFactor;
    const ctx = offscreen.getContext('2d');

    // 填充纯白背景，防止导出透明通道导致图表刻度文字看不清
    ctx.fillStyle = '#FFFFFF';
    ctx.fillRect(0, 0, offscreen.width, offscreen.height);

    // 将原始 Canvas 平铺放大绘制到离屏画布
    ctx.drawImage(canvasNode, 0, 0, offscreen.width, offscreen.height);

    offscreen.toBlob((blob) => {
      if (!blob) return;
      const downloadUrl = URL.createObjectURL(blob);
      triggerFileDownload(downloadUrl, filename);
      URL.revokeObjectURL(downloadUrl);
    }, 'image/png');

  } else if (svgNode) {
    // 针对 SVG 容器：执行 DOM 序列化与离屏栅格化流程
    const rect = svgNode.getBoundingClientRect();
    const width = rect.width || parseInt(svgNode.getAttribute('width'), 10) || 600;
    const height = rect.height || parseInt(svgNode.getAttribute('height'), 10) || 400;

    // 1. DOM 序列化
    const serializer = new XMLSerializer();
    let sourceXml = serializer.serializeToString(svgNode);

    // 确保 XML 具备合法的命名空间
    if (!sourceXml.match(/^<svg[^>]+xmlns="http:\/\/www\.w3\.org\/2000\/svg"/)) {
      sourceXml = sourceXml.replace(/^<svg/, '<svg xmlns="http://www.w3.org/2000/svg"');
    }

    // 2. 构建 Blob URL
    const svgBlob = new Blob([sourceXml], { type: 'image/svg+xml;charset=utf-8' });
    const blobUrl = URL.createObjectURL(svgBlob);

    // 3. 异步解码图像
    const img = new Image();
    img.src = blobUrl;
    await new Promise((resolve, reject) => {
      img.onload = () => resolve();
      img.onerror = (err) => reject(err);
    });

    // 4. 离屏 Canvas 高倍绘制
    const offscreen = document.createElement('canvas');
    offscreen.width = width * scaleFactor;
    offscreen.height = height * scaleFactor;
    const ctx = offscreen.getContext('2d');

    ctx.fillStyle = '#FFFFFF';
    ctx.fillRect(0, 0, offscreen.width, offscreen.height);
    ctx.drawImage(img, 0, 0, offscreen.width, offscreen.height);

    // 5. 输出 PNG 并释放资源
    offscreen.toBlob((blob) => {
      if (!blob) return;
      const downloadUrl = URL.createObjectURL(blob);
      triggerFileDownload(downloadUrl, filename);
      URL.revokeObjectURL(downloadUrl);
      URL.revokeObjectURL(blobUrl);
    }, 'image/png');

  } else {
    throw new Error('未在指定容器内找到 Canvas 或 SVG 统计图元素');
  }
}

// 模拟点击 a 标签触发浏览器下载
function triggerFileDownload(url, filename) {
  const link = document.createElement('a');
  link.href = url;
  link.download = filename;
  document.body.appendChild(link);
  link.click();
  document.body.removeChild(link);
}

三、统计图导出为 PDF 文件的尺寸控制与分页截断

1. 引入 jsPDF 建立标准 PDF 文档模型

将网页中的统计图导出为 PDF 文件时，最成熟稳健的前端库是 jspdf。初始化 PDF 时，推荐使用毫米作为计量单位：const doc = new jsPDF('p', 'mm', 'a4');。竖向标准的 A4 页面物理宽度为 210mm，高度为 297mm。

实际排版不能直接顶格贴边，通常需要在四周预留至少 15mm 的边距（Margin）。因此，单页实际可用的最大图表印刷区域为宽 180mm、高 267mm。明确该可用区域是计算图表缩放比例的前提。

2. 单张统计图的自适应等比缩放与居中算法

直接把图表强行拉伸到整个页面会导致图形变形失真，折线图的斜率和柱状图的胖瘦比例都会被破坏。正确的几何计算应分别算出宽度缩放比 ratioW = maxW / imgW 和高度缩放比 ratioH = maxH / imgH，并取二者之间的较小值：scale = Math.min(ratioW, ratioH)。

按此缩放比重新计算出最终打印宽度 finalW 与高度 finalH 后，再计算出水平居中偏移量 posX = margin + (maxW - finalW) / 2，确保导出的图表端正居中于 PDF 页面正中央。

3. 超长统计图与多图报表的纵向切片方案

当业务系统需要导出大型甘特图、时间跨度极长的时间轴折线图或垂直排列的完整监控仪表盘时，图表高度往往远远超出单张 A4 纸能容纳的极限。如果强行把整张长图缩小塞入单页，图表文字会缩得无法辨认。

面对超长图表，应当采取“多页垂直分块切片算法”：以单页可用高度对应的源图比例建立循环，利用离屏 Canvas 沿 Y 轴平移截取对应的矩形像素片段，依次调用 pdf.addPage() 添加新页面，并将切片依次绘制在各页的起始位置，保证每一页都有清晰可读的局部细节。

4. 导出为 PDF 的完整代码实现

以下示例演示了如何基于 jsPDF 实现包含等比缩放与自动超长切片的统计图 PDF 导出方案：

// 需提前通过 npm install jspdf 或 script 标签引入 jsPDF 构造函数
async function exportChartToPDF(container, filename = 'report.pdf') {
  if (!window.jspdf || !window.jspdf.jsPDF) {
    throw new Error('未检测到 jsPDF 库，请先引入 jspdf 脚本');
  }

  const { jsPDF } = window.jspdf;
  const pdf = new jsPDF('p', 'mm', 'a4');

  // A4 规格：宽 210mm，高 297mm；四周留白 15mm
  const pageWidth = 210;
  const pageHeight = 297;
  const margin = 15;
  const printableWidth = pageWidth - margin * 2;   // 180mm
  const printableHeight = pageHeight - margin * 2; // 267mm

  // 先将容器内的图表统一转换为离屏高分辨率 Canvas
  let canvas = container.querySelector('canvas');
  if (!canvas) {
    // 若为 SVG 则先转为临时 Canvas
    const svg = container.querySelector('svg');
    if (!svg) throw new Error('容器内未找到图表元素');
    canvas = await convertSvgToTempCanvas(svg);
  }

  const imgWidthPx = canvas.width;
  const imgHeightPx = canvas.height;

  // 计算等比映射到可打印宽度后的物理高度
  const renderedHeightMm = (imgHeightPx * printableWidth) / imgWidthPx;

  if (renderedHeightMm <= printableHeight) {
    // 情况 A：图表高度适中，单页完全放得下，执行等比居中渲染
    const scale = Math.min(printableWidth / imgWidthPx, printableHeight / imgHeightPx);
    const finalWidthMm = imgWidthPx * scale;
    const finalHeightMm = imgHeightPx * scale;
    const posX = margin + (printableWidth - finalWidthMm) / 2;
    const posY = margin + (printableHeight - finalHeightMm) / 2;

    const imgData = canvas.toDataURL('image/png', 1.0);
    pdf.addImage(imgData, 'PNG', posX, posY, finalWidthMm, finalHeightMm);
  } else {
    // 情况 B：图表为超长图，执行纵向分块切割循环
    let remainingHeightMm = renderedHeightMm;
    let currentSourceYPx = 0;
    // 单页容纳对应的源像素高度
    const pageCapacityPx = (printableHeight * imgWidthPx) / printableWidth;

    let isFirstPage = true;
    while (remainingHeightMm > 0) {
      if (!isFirstPage) {
        pdf.addPage();
      }

      // 计算当前切片的源画布高度
      const sliceHeightPx = Math.min(pageCapacityPx, imgHeightPx - currentSourceYPx);
      const sliceHeightMm = (sliceHeightPx * printableWidth) / imgWidthPx;

      // 提取切片到独立内存画布
      const sliceCanvas = document.createElement('canvas');
      sliceCanvas.width = imgWidthPx;
      sliceCanvas.height = sliceHeightPx;
      const sliceCtx = sliceCanvas.getContext('2d');
      sliceCtx.fillStyle = '#FFFFFF';
      sliceCtx.fillRect(0, 0, sliceCanvas.width, sliceCanvas.height);

      sliceCtx.drawImage(
        canvas,
        0, currentSourceYPx, imgWidthPx, sliceHeightPx,
        0, 0, imgWidthPx, sliceHeightPx
      );

      const sliceData = sliceCanvas.toDataURL('image/png', 1.0);
      pdf.addImage(sliceData, 'PNG', margin, margin, printableWidth, sliceHeightMm);

      currentSourceYPx += sliceHeightPx;
      remainingHeightMm -= sliceHeightMm;
      isFirstPage = false;
    }
  }

  pdf.save(filename);
}

四、导出过程中的典型暗坑与排查方案

在实际项目中，导出统计图往往不会一帆风顺。由于浏览器的安全沙箱机制、动画帧异步性以及样式作用域隔离，开发者通常会遭遇以下四个高频暗坑。

1. 图表初始动画未播放完毕导致“白屏”或“缺漏”

ECharts、Chart.js 等图表库为了视觉效果，在初次渲染时默认会执行持续约 800 至 1200 毫秒的入场缓动动画（例如柱条从底部往上生长、折线自左向右绘制）。如果用户一进入页面或在数据刚加载完成时立即调用导出函数，此时 Canvas 上的图形正处于首帧或半生长状态，导出的图片必然是残缺甚至完全空白的。

2. SVG 导出后变成全黑块或字体样式彻底丢失

当导出基于 SVG 的图表时，导出的图片常常出现文字位移、背景缺失，甚至所有几何图形全变成黑块。这是因为原图表在网页中显示时，其颜色、线条粗细等样式是通过外部 CSS 类名（Class）由 HTML 统一赋予的；但一旦用 XMLSerializer 将 <svg> 标签单独剥离为 XML 文档，外部的 CSS 文件便与之断开关联，所有图形元素回退到 SVG 规范的默认填充色（纯黑）。

修复此问题的方法有两种：其一是在图表代码生成阶段就尽量使用内联属性（如直接在标签上写 fill="#52677D"、stroke="#A66C5B"）；其二是在序列化前，通过 JavaScript 递归遍历 SVG 的每一个子元素，调用 window.getComputedStyle(node) 获取最终渲染样式，并强制重写回节点的 style 属性中。

3. 跨域图片导致 Canvas 报 SecurityError（画布污染）

如果统计图内部嵌入了自定义图标、散点气泡上的用户头像或外部背景水印图，一旦调用 canvas.toBlob() 或 canvas.toDataURL()，控制台很可能会抛出 Uncaught DOMException: Failed to execute 'toDataURL' on 'HTMLCanvasElement': Tainted canvases may not be exported 报错。

这是浏览器的同源安全策略在起作用：只要 Canvas 绘制过未经 CORS 授权的异域图片资源，该画布就会被标记为“受污染”（Tainted），禁止 JavaScript 提取其原始像素数据。解决这一问题的根本办法是：存储外部图片的静态资源服务器必须返回 Access-Control-Allow-Origin: * 响应头，且在图表代码实例化 Image 对象时必须显式标注 img.crossOrigin = 'anonymous'。

4. 字体未加载完成导致文本折行与排版错位

使用特殊网络字体或企业定制字体的统计图，如果在字体尚未完全下载就执行了离屏栅格化，Canvas 内部会以系统默认回退字体（如 Arial 或宋体）测量字宽。由于不同字体的字形宽度差异，导出后的标签往往会发生文字重叠或超出图表边界。在执行导出前，应先通过 await document.fonts.ready 保证全部网络字体就绪。

五、业务场景技术选型与落地总结

面对不同的业务要求，不应盲目使用最复杂或单一的方案。下表梳理了常见业务诉求下的最优落地组合：

总结而言，导出 JavaScript 统计图并不是一个单纯的“文件保存”操作，而是一个涵盖“确定图表底层渲染介质、选择合适的二进制桥梁、进行 DPI 高清放大补偿以及根据 A4 版面规划几何尺寸”的系统化流程。只要把控好动画完成时机与跨介质样式保真，就能在各种终端环境下稳定交付符合要求的图片与文档。