怎么将 heatmap.js 生成的 Canvas 热力图导出为图片

图 0：heatmap.js Canvas 热力图数据流向与图片导出总览

在数据可视化与分析系统中，heatmap.js 是一个非常经典的前端热力图类库。它通过向指定的 DOM 容器动态注入一个 <canvas class="heatmap-canvas"> 元素，使用双重缓冲算法计算灰度透明度，再映射渐变调色板完成渲染。

很多开发者在需要将热力图保存到本地或上传至服务器时，常常会困惑于 heatmap.js 并没有一个明显的“导出”按钮，或者在叠加了背景图后发现导出的图片只有孤立的热力光斑而缺失了底图。本文将针对这两种典型场景，详细说明标准导出实现方案及常见避坑细节。

一、纯热力图的两种直出方式

如果你的需求仅是获取热力图本身的透明图层，并不需要合并背景图，浏览器原生 Canvas API 以及 heatmap.js 自身就已经提供了直接提取图像数据的方法。

1. 使用内置方法：heatmapInstance.getDataURL()

在创建热力图实例时，heatmap.js 会将内部渲染引擎封装在对象中。官方实例直接暴露了 getDataURL() 方法，其内部实现等价于调用渲染画布的 toDataURL("image/png")。

// 1. 创建并渲染热力图实例
const heatmapInstance = h337.create({
  container: document.getElementById('heatmapContainer'),
  radius: 40,
  maxOpacity: 0.8
});

// 2. 设置热力数据
heatmapInstance.setData({
  max: 100,
  data: [{ x: 150, y: 120, value: 80 }, { x: 220, y: 190, value: 95 }]
});

// 3. 直接获取 Base64 图片编码（默认为 image/png）
const dataUrl = heatmapInstance.getDataURL();
console.log(dataUrl); // 输出类似 "data:image/png;base64,iVBORw0KGgo..."

2. 获取内部 Canvas 节点使用 toBlob() 异步导出

对于较大的热力图画布（例如超过 1920×1080 像素），Base64 字符串会带来约 33% 的内存冗余，容易引起移动端或低性能设备的卡顿。此时推荐直接获取 heatmap.js 创建的 Canvas DOM 节点，利用 canvas.toBlob() 生成二进制 Blob 对象。

// 从挂载容器内抓取真实的 Canvas 元素
const container = document.getElementById('heatmapContainer');
const canvasElement = container.querySelector('canvas.heatmap-canvas');

// 将 Canvas 转为二进制 Blob 并下载
canvasElement.toBlob((blob) => {
  if (!blob) return;
  const downloadUrl = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = downloadUrl;
  a.download = 'pure-heatmap.png';
  a.click();
  // 释放临时内存地址
  URL.revokeObjectURL(downloadUrl);
}, 'image/png');

图 1：heatmap.js 内部 Canvas 节点与两类导出 API 对应的结构示意图

二、端到端完整实现：从生成到自动下载

为了让导出功能在真实项目中平稳运行，通常需要封装一个通用的触发下载辅助函数，处理跨浏览器的兼容性以及内存垃圾回收。

1. 编写通用的客户端下载辅助函数

在现代浏览器中，通用的做法是动态创建一个具有 download 属性的虚拟 <a> 标签，将图片地址绑定至 href，模拟点击后再移除该元素。

/**
 * 触发浏览器本地文件下载
 * @param {string|Blob} content - Base64 字符串或 Blob 二进制流
 * @param {string} fileName - 下载保存的文件名
 */
function downloadExportedFile(content, fileName = 'heatmap.png') {
  let url;
  let isCreatedUrl = false;

  if (content instanceof Blob) {
    url = URL.createObjectURL(content);
    isCreatedUrl = true;
  } else {
    url = content;
  }

  const anchor = document.createElement('a');
  anchor.style.display = 'none';
  anchor.href = url;
  anchor.download = fileName;

  document.body.appendChild(anchor);
  anchor.click();
  document.body.removeChild(anchor);

  // 释放 createObjectURL 生成的引用，防止内存泄漏
  if (isCreatedUrl) {
    setTimeout(() => {
      URL.revokeObjectURL(url);
    }, 100);
  }
}

图 2：热力图从初始化、数据填充到文件落地与内存释放的全步骤时序

三、复合场景：将背景底图与热力图合并导出

在实际工程中，热力图绝大多数时候不是孤立存在的。例如：展示商场客流分布时，热力图下方会有建筑平面图；展示点击热力时，下方会有网页截图；展示轨迹密度时，下方会有瓦片地图。

此时，由于背景图通常是通过 <img>、CSS background-image 或另一个独立的图层 Canvas 呈现的，直接调用 heatmap.js 的 getDataURL() 导出的图片只包含悬浮的彩色光斑，背景将呈现全透明或黑底。

完整合并导出代码实现

/**
 * 合并背景底图与热力图层并触发图片下载
 * @param {HTMLImageElement|string} backgroundImage - 背景图元素或图片 URL
 * @param {HTMLElement} heatmapContainer - 热力图外层容器
 * @param {string} fileName - 导出的目标图片名
 */
async function exportMergedHeatmap(backgroundImage, heatmapContainer, fileName = 'merged-heatmap.png') {
  // 1. 确保获取已就绪的热力图 Canvas
  const heatmapCanvas = heatmapContainer.querySelector('canvas.heatmap-canvas');
  if (!heatmapCanvas) {
    throw new Error('未在容器内检测到 heatmap-canvas 元素，请确认热力图是否已完成初始化渲染');
  }

  const targetWidth = heatmapCanvas.width;
  const targetHeight = heatmapCanvas.height;

  // 2. 加载背景图片对象（若传入的是 URL 则先异步加载）
  const bgImg = await new Promise((resolve, reject) => {
    if (backgroundImage instanceof HTMLImageElement && backgroundImage.complete) {
      resolve(backgroundImage);
      return;
    }
    const img = new Image();
    // 注意：如果底图跨域，必须声明 anonymous
    img.crossOrigin = 'anonymous';
    img.onload = () => resolve(img);
    img.onerror = (err) => reject(new Error('背景底图加载失败，请检查路径或跨域配置'));
    img.src = typeof backgroundImage === 'string' ? backgroundImage : backgroundImage.src;
  });

  // 3. 创建临时离屏 Canvas
  const offscreenCanvas = document.createElement('canvas');
  offscreenCanvas.width = targetWidth;
  offscreenCanvas.height = targetHeight;
  const ctx = offscreenCanvas.getContext('2d');

  // 4. 按图层先后顺序绘制
  // 第一步：绘制底图，拉伸或按原图比例平铺至 Canvas 规格
  ctx.drawImage(bgImg, 0, 0, targetWidth, targetHeight);

  // 第二步：绘制热力图层
  ctx.drawImage(heatmapCanvas, 0, 0, targetWidth, targetHeight);

  // 5. 从离屏 Canvas 导出合并后的图片
  offscreenCanvas.toBlob((blob) => {
    if (!blob) return;
    downloadExportedFile(blob, fileName);
  }, 'image/png');
}

图 3：离屏 Canvas 多图层坐标对齐、渲染覆盖与输出机制

四、避坑指南：排查导出失败与常见问题

在实现热力图导出时，大部分异常集中在浏览器安全策略（跨域污染）、时序错误以及高分辨率屏幕适配上。遇到问题时，可对照以下要点排查：

1. 报错 SecurityError: The operation is insecure（画布跨域污染）

修复步骤：

• 服务端配置： 托管底图的 CDN 或存储服务器必须在 HTTP 响应头中添加 Access-Control-Allow-Origin: *。
• 客户端声明： 加载底图时，必须在设置 img.src 之前，显式声明 img.crossOrigin = 'anonymous'。
• 本地调试陷阱： 若通过 file:/// 协议在本地双击打开 HTML 文件，浏览器会因为默认同源限制阻止导出，必须在本地 HTTP 服务器（如 Vite、Live Server 或 Python http.server）下运行测试。

2. 导出的图片为空白、纯黑或缺失热力点

• 未等待异步渲染： 检查 heatmapInstance.setData() 是否已调用。如果背景图是通过网络加载的，必须在 img.onload 事件回调触发后，再执行离屏 Canvas 的 drawImage。
• JPEG 格式黑底： 导出格式若指定为 image/jpeg，因为 JPEG 不支持透明度，原本透明的无热力区域默认会被填充为纯黑色。如需透明背景或白底，建议统一保存为 image/png，或者在绘制图层前用 ctx.fillStyle = '#ffffff'; ctx.fillRect(...) 预先涂白底层。

3. 高分屏（Retina / DPR）导致导出的图片模糊

许多现代前端框架在初始化 Canvas 时，会将 canvas.width 放大为 containerWidth * window.devicePixelRatio 以实现高清显示，而 CSS 宽高依然为逻辑像素。

导出时，离屏 Canvas 的 width 和 height 务必直接读取 heatmapCanvas.width 属性（物理像素），切勿使用 getBoundingClientRect().width 或 offsetWidth（CSS 逻辑像素），否则导出的图片会被压缩降质或出现内容错位。

图 4：导出方案选型逻辑与三类高频异常排查对照矩阵

五、方案对比与技术选型总结

在实际项目落地时，可以根据是否需要包含底层参考信息以及对导出性能的要求，选择匹配的实现组合：

掌握 Canvas 的像素数据读取（toDataURL / toBlob）与离屏多图层复合绘制原理，不仅能够彻底解决 heatmap.js 的图片导出需求，也能灵活应对各类基于 HTML5 Canvas 的图表与地图工具的图像持久化任务。