怎么将 Plotly.js 图表导出为 PNG、SVG 或 PDF 静态文件

一、Plotly.js 导出静态文件的底层机制与格式差异

在着手编写导出代码前，需要理解 Plotly.js 在浏览器底层是如何绘制图表的，以及 PNG、SVG、PDF 在技术实现上的本质区别：

• 图表 DOM 渲染结构：对于常见的折线图、柱状图、散点图和饼图等二维可视化，Plotly.js 在网页中构建的是一棵由 <svg class="main-svg"> 组织的矢量 DOM 树；而对于三维图表（如 3D 散点、曲面）、高密度 WebGL 散点（scattergl）或热力图，Plotly.js 则使用 HTML5 <canvas> 借助 GPU 着色器直接渲染。
• PNG 导出的底层路径：Plotly.js 内部使用 XMLSerializer 读取 SVG DOM 文本，将其转换为 Base64 编码的临时图像并载入一个隐藏的离屏 Canvas。随后，Canvas 上下文将矢量或 WebGL 内容栅格化为点阵像素，最后调用 canvas.toDataURL('image/png') 得到最终图像。导出质量的关键取决于 scale（缩放倍率）参数。
• SVG 导出的底层路径：对于纯 2D 图表，Plotly.js 直接提取 SVG 根节点，将依赖的计算样式（Computed Styles）、剪裁路径（ClipPath）以及字体定义全部内联至 XML 字符串中输出。SVG 属于纯文本矢量文件，具有无限放大不失真的特性，体积小巧且能在 Adobe Illustrator 或 Inkscape 中二次编辑。
• PDF 导出的技术限制：Plotly.js 官方库在较早版本迭代中，已移除了依赖特定老旧插件的纯前端直接导出 PDF 机制。若直接在浏览器端指定 format: 'pdf'，控制台将提示该格式不受支持。因此生成 PDF 文件必须采取前端第三方库桥接或服务端无头渲染两类有效手段。

二、浏览器端：使用 Plotly.js 内置 API 导出 PNG 与 SVG

在纯客户端网页交互场景中，Plotly.js 提供了两种最直接的导出方式：一种是通过图表顶部的 ModeBar 工具栏按钮，另一种是通过 JavaScript 编程式调用。

2.1 通过 ModeBar 工具栏一键导出

Plotly.js 默认在图表右上角提供了一排操作工具栏（ModeBar），其中包含一个照相机图标的“Download plot as a png”按钮。可以通过在 Plotly.newPlot 的第四个参数 config 中配置 toImageButtonOptions，来定制下载文件的格式、分辨率与文件名：

// 初始化 Plotly 图表并定制 ModeBar 导出参数
const data = [{
  x: ['一月', '二月', '三月', '四月'],
  y: [120, 180, 240, 310],
  type: 'bar',
  marker: { color: '#17324D' }
}];

const layout = {
  title: '季度业务营收统计',
  font: { family: 'PingFang SC, Microsoft YaHei, sans-serif' }
};

const config = {
  responsive: true,
  // 配置相机图标导出参数：设为导出 SVG 矢量图
  toImageButtonOptions: {
    format: 'svg',           // 支持 'png', 'svg', 'jpeg', 'webp'
    filename: 'revenue_chart', // 下载文件名（自动补全后缀）
    height: 600,               // 导出物理像素高度
    width: 900,                // 导出物理像素宽度
    scale: 2                   // 像素缩放倍率，提升位图清晰度
  }
};

Plotly.newPlot('chartContainer', data, layout, config);

2.2 编程式触发自动下载：Plotly.downloadImage

当需要在页面上提供自定义样式的下载按钮，或者在特定操作后自动触发文件下载时，应直接使用 Plotly.downloadImage() 方法。该方法接收图表 DOM 容器对象和配置参数，执行后会自动在浏览器中唤起文件存盘动作：

// 绑定自定义导出按钮事件
document.getElementById('btnExportPng').addEventListener('click', async () => {
  const chartElement = document.getElementById('chartContainer');

  const exportOptions = {
    format: 'png',             // 目标格式：PNG
    filename: 'sales_report',   // 保存文件名
    width: 1200,                // 画布宽度
    height: 800,                // 画布高度
    scale: 3                    // 3倍采样，确保 300 DPI 印刷级高保真
  };

  try {
    await Plotly.downloadImage(chartElement, exportOptions);
    console.log('PNG 文件已成功触发下载');
  } catch (error) {
    console.error('导出图表失败:', error);
  }
});

2.3 获取图像数据流：Plotly.toImage

如果不需要立即让浏览器下载文件，而是希望将图片数据用于前端页面缩略预览、嵌入富文本编辑器，或者通过 AJAX / Fetch 接口上传到后台服务器，应当使用 Plotly.toImage()。该方法返回一个解析为 Data URL（Base64 字符串）的 Promise：

// 提取图表的 Base64 Data URL 并展示或上传
async function extractChartImageData() {
  const chartElement = document.getElementById('chartContainer');

  const dataUrl = await Plotly.toImage(chartElement, {
    format: 'svg',
    width: 800,
    height: 500
  });

  // 此时 dataUrl 为形如 "data:image/svg+xml;base64,..." 的字符串
  // 示例 1：赋给页面上的 <img> 预览
  document.getElementById('previewImage').src = dataUrl;

  // 示例 2：转换为 Blob 并发送给后端
  const response = await fetch(dataUrl);
  const blob = await response.blob();
  
  const formData = new FormData();
  formData.append('chart', blob, 'chart.svg');
  // await fetch('/api/upload', { method: 'POST', body: formData });
}

三、浏览器端：将 Plotly.js 图表导出为 PDF 文件

在没有后端服务支持的纯前端单页应用（SPA）中，若需要将图表保存为标准 PDF 文档，通常配合成熟的开源库 jsPDF 实现。实现思路由两步构成：先通过 Plotly.toImage() 生成指定尺寸的高分辨率 PNG 图像，再将图像写入 jsPDF 构建的标准 A4 页面容器中并保存。

3.1 引入依赖库

在 HTML 页面 <head> 中引入 jsPDF 库（以国内常见可靠 CDN 为例）：

<!-- 引入 jsPDF 纯前端 PDF 构造库 -->
<script src="https://cdn.jsdelivr.net/npm/jspdf@2.5.1/dist/jspdf.umd.min.js"></script>

3.2 完整导出 PDF 实现代码

下面的代码演示了如何精确计算标准 A4 纸张页面（210mm × 297mm）的版心边距与宽高比，自动将 Plotly.js 图表居中排版并导出为 PDF：

async function exportPlotlyToPdf() {
  const chartElement = document.getElementById('chartContainer');
  const { jsPDF } = window.jspdf;

  // 1. 先通过 Plotly.toImage 获取高分辨率 PNG (scale: 3 避免打印模糊)
  const imgWidthPx = 1200;
  const imgHeightPx = 800;
  const imgDataUrl = await Plotly.toImage(chartElement, {
    format: 'png',
    width: imgWidthPx,
    height: imgHeightPx,
    scale: 3
  });

  // 2. 创建 A4 纵向 (portrait) PDF 文档，单位为毫米 (mm)
  const pdf = new jsPDF({
    orientation: 'portrait',
    unit: 'mm',
    format: 'a4'
  });

  // A4 尺寸定义: 210mm x 297mm
  const pageWidth = 210;
  const marginX = 15; // 左右边距各 15mm
  const printWidth = pageWidth - (marginX * 2); // 图表可用宽度 180mm
  const printHeight = (imgHeightPx / imgWidthPx) * printWidth; // 等比缩放高度

  // 3. 添加文档页眉标题与导出时间
  pdf.setFontSize(16);
  pdf.text('数据分析统计报告', marginX, 22);
  pdf.setFontSize(10);
  pdf.setTextColor(100);
  pdf.text(`生成日期: ${new Date().toLocaleDateString()}`, marginX, 29);

  // 4. 将图表图像嵌入 PDF 页面 (起始 Y 坐标设为 36mm)
  pdf.addImage(imgDataUrl, 'PNG', marginX, 36, printWidth, printHeight);

  // 5. 保存并触发浏览器下载
  pdf.save('analytics_report.pdf');
}

四、服务端环境：使用 Node.js + Puppeteer 导出高保真静态文件

在定时生成业务周报、自动化邮件附件投递或离线数据归档等企业级场景中，图表生成通常在没有真实显示器的后端服务器上执行。过去曾有基于 Electron 的 @plotly/orca 工具，但目前该工具已停止积极维护且环境依赖臃肿。现代技术栈推荐使用 Node.js + Puppeteer（无头 Chromium），该方案不仅支持完整的 WebGL 与 CSS 特性，还可直接调用 Chromium 原生打印引擎生成出版级矢量 PDF。

4.1 安装 Node.js 依赖

npm install puppeteer

4.2 自动化导出脚本实现（支持 PNG、SVG 与原生矢量 PDF）

创建 export_service.js 脚本，演示如何启动无头浏览器、载入图表配置、等待图表完全渲染并分别输出三种静态文件：

const puppeteer = require('puppeteer');
const fs = require('fs');
const path = require('path');

async function renderAndExport() {
  // 1. 启动无头 Chromium 浏览器
  const browser = await puppeteer.launch({
    headless: 'new',
    args: ['--no-sandbox', '--disable-setuid-sandbox']
  });

  const page = await browser.newPage();
  await page.setViewport({ width: 1200, height: 800, deviceScaleFactor: 2 });

  // 2. 构建包含 Plotly.js 绘图逻辑的 HTML 内容
  const htmlTemplate = `
    <!DOCTYPE html>
    <html>
    <head>
      <meta charset="utf-8">
      <script src="https://cdn.plot.ly/plotly-2.29.1.min.js"></script>
      <style>
        body { margin: 0; padding: 20px; font-family: sans-serif; }
        #chart { width: 1000px; height: 600px; }
      </style>
    </head>
    <body>
      <div id="chart"></div>
      <script>
        const data = [{
          x: ['2026-Q1', '2026-Q2', '2026-Q3', '2026-Q4'],
          y: [320, 450, 580, 710],
          type: 'scatter',
          mode: 'lines+markers',
          line: { color: '#17324D', width: 3 },
          marker: { size: 8, color: '#659B9B' }
        }];
        const layout = {
          title: '年度核心业务指标演进趋势',
          margin: { t: 60, r: 40, b: 50, l: 60 }
        };
        Plotly.newPlot('chart', data, layout, { responsive: false });
      </script>
    </body>
    </html>
  `;

  await page.setContent(htmlTemplate, { waitUntil: 'networkidle0' });

  // 3. 等待 Plotly 完成图表绘制 (检测 main-svg 节点出现)
  await page.waitForSelector('.main-svg');

  // 4. 导出方式 A: 获取真矢量 PDF (调用浏览器底层打印管道)
  await page.pdf({
    path: path.join(__dirname, 'output.pdf'),
    format: 'A4',
    printBackground: true,
    margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' }
  });
  console.log('[输出完成] 矢量 PDF: output.pdf');

  // 5. 导出方式 B: 获取高分辨率 PNG (通过 page.evaluate 调用内部 Plotly.toImage)
  const pngDataUrl = await page.evaluate(async () => {
    const gd = document.getElementById('chart');
    return await Plotly.toImage(gd, { format: 'png', width: 1000, height: 600, scale: 2 });
  });
  const pngBuffer = Buffer.from(pngDataUrl.split(',')[1], 'base64');
  fs.writeFileSync(path.join(__dirname, 'output.png'), pngBuffer);
  console.log('[输出完成] PNG 图像: output.png');

  // 6. 导出方式 C: 获取 SVG 矢量图
  const svgDataUrl = await page.evaluate(async () => {
    const gd = document.getElementById('chart');
    return await Plotly.toImage(gd, { format: 'svg', width: 1000, height: 600 });
  });
  const svgText = decodeURIComponent(svgDataUrl.split(',')[1]);
  fs.writeFileSync(path.join(__dirname, 'output.svg'), svgText);
  console.log('[输出完成] SVG 文件: output.svg');

  // 7. 优雅关闭页面与浏览器进程
  await page.close();
  await browser.close();
}

renderAndExport().catch(console.error);

五、实际操作中的关键问题与注意事项

5.1 图像模糊与 scale 缩放倍率设置

许多开发者初次导出 PNG 时，常反馈导出的图片在高清显示屏（Retina）或插入 Word 打印时字迹模糊。这是由于默认情况下 Plotly.toImage() 以 1:1 CSS 逻辑像素输出（约 72~96 DPI）。

• 普通网页展示：使用默认 scale: 1 或 scale: 1.5 即可满足要求并控制文件体积。
• PPT 演示与电子文档：推荐设置 scale: 2，能够获得清晰的视觉表现。
• 印刷排版与出版级物料：建议设置 scale: 3 或 scale: 4，输出图像的等效 DPI 可达 300 以上，线条锐利无锯齿。注意：过大的 scale（例如大于 5）会导致离屏 Canvas 内存暴增，甚至在移动端浏览器上引发 OOM（内存溢出）崩溃。

5.2 中文字体缺失与乱码排查

导出为 SVG 或在 Linux 服务器生成 PDF 时，若系统中未安装图表指定的字体族，中文字符可能会回退为默认等宽字体，甚至出现“□□”方块乱码：

• 前端声明回退：在图表的 layout.font.family 中，务必使用多个通用的系统回退字体，如："PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif。
• 服务端字体包补全：若在 Docker 容器（如 Alpine 或 Ubuntu minimal）中运行 Puppeteer，镜像构建时必须安装基础中文字体库（例如 Debian/Ubuntu 执行 apt-get install -y fonts-noto-cjk fonts-wqy-microhei），确保无头 Chromium 能正常匹配字形。

5.3 避免导出动画中间态与图表截断

Plotly.js 在初始渲染或调用 Plotly.react() 更新时通常带有过渡动画（默认时长约 500ms）。如果在调用绘图函数后立即无等待地调用 toImage()，可能会导出柱子只升起一半或坐标轴尚未对齐的残缺图片。务必确保在异步 Promise 决议之后，或者监听 plotly_afterplot 事件触发后再行调用导出逻辑。

5.4 容器百分比宽度的尺寸固化

如果图表挂载在设置了 width: 100% 的响应式容器中，未显式传参给 toImage() 时，导出的图片尺寸将受限于当前浏览器的视口宽度。为了确保批处理导出的图片尺寸统一规范，强烈建议在 options 中显式指定固定像素的 width 和 height（例如 width: 1200, height: 750）。

六、技术选型决策与总结

为便于在实际工程项目中快速决策，下表汇总了四种核心实现方案的对比维度与选型建议：

综上所述，将 Plotly.js 图表导出为静态文件并不存在单一万能解法，而是应当根据具体业务诉求组合使用：对于即时交互场景，优先使用官方原生的 Plotly.downloadImage() 生成 PNG 或 SVG；若需向用户提供成套的独立文档，可在前端通过 jsPDF 进行快速包装；而对于对保真度、排版规整度与稳定性要求极高的企业级自动化流水线，基于 Node.js 与 Puppeteer 的服务端渲染方案则是业界公认的最佳实践。