heatmap.js 安装与初始化：从 CDN 引入到创建实例

在前端交互统计与空间分布可视化开发中，如果需要直观展示用户点击聚集区、页面浏览停留轨迹或离散物理采样点的分布密度，heatmap.js 是一个成熟且无需庞大工程依赖的 HTML5 Canvas 轻量热力图库。实现热力图最简单、零构建工具依赖的方式是通过公共 CDN 引入脚本，在页面准备一个具备确定尺寸和相对定位的宿主 DOM 容器，并使用库暴露的全局对象 h337.create(config) 完成实例构建。本文从 CDN 地址选择与引入、宿主 DOM 盒模型布局规范、核心参数解析，一直到测试数据灌入和初始化故障排查，提供完整可操作的技术指导。

一、选择与引入 CDN 资源

heatmap.js 目前最稳定的通用版本为 2.0.x 系列（主要是 2.0.2 与 2.0.5）。该库没有外部前置依赖，编译后的生产文件体积不足 10 KB（经 Gzip 压缩后更小）。对于无需工程打包的原型验证、管理后台页面或轻量可视化单页，直接通过公共内容分发网络（CDN）引入是最快捷的方案。

各大主流公开 CDN 均收录了该库，可以选用以下任一可靠链接：

<!-- 方案 A：cdnjs (推荐，节点覆盖广、历史版本完备) -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/heatmap.js/2.0.2/heatmap.min.js"></script>

<!-- 方案 B：jsDelivr (国内访问较均衡) -->
<script src="https://cdn.jsdelivr.net/npm/heatmap.js@2.0.5/build/heatmap.min.js"></script>

<!-- 方案 C：unpkg -->
<script src="https://unpkg.com/heatmap.js@2.0.5/build/heatmap.min.js"></script>

关于脚本引入的位置与命名空间，需要特别留意以下两个技术细节：

• 全局对象标识符为 h337：脚本加载执行后，并非像直觉中那样挂载 window.heatmap，而是向全局注入一个名为 h337 的对象。这是作者 Patrick Wied 选用的标识符，来源于黑客圈俚语“leet”（1337）的变体写法。所有热力图的工厂函数与辅助工具均由此对象导出。
• 脚本执行时序：若将 <script> 放在 <head> 中且未加 defer 或 async，浏览器会阻塞 HTML 解析并优先下载执行脚本，这能确保后续业务逻辑代码执行时 window.h337 已经就绪；若将脚本放在 <body> 底部，则必须确保后续的业务初始化逻辑紧跟其后，或者放置在 DOMContentLoaded 事件回调中。

二、准备宿主 DOM 容器及其布局规范

在完成 <script> 引入后，如果直接在 HTML 中编写一个裸的 <div id="heatmap"></div>，往往会发现页面一片空白，或者控制台虽然没有报错，热力图却未呈现在预想位置。这类问题通常源于宿主 DOM 容器样式的疏漏。

heatmap.js 的内部机制是在给定的宿主容器节点内部，动态创建一个 <canvas class="heatmap-canvas"> 画布元素，并为其设置了行内样式：position: absolute; left: 0; top: 0;。为了让这块画布能够准确贴合目标区域，宿主容器必须满足以下两项严格的排版条件：

1. 必须显式声明定位上下文（建议 position: relative）

在 CSS 盒模型渲染规则中，一个绝对定位（position: absolute）的子元素，会沿着 DOM 树向外寻找最近的定位包含块（即 position 不为 static 的元素）。如果宿主容器使用默认的 static 定位，注入的 Canvas 画布就会越过宿主容器，直接锚定到页面的最顶层或者 <body>。这会导致整个热力图图层飞出容器边界，漂浮在页面左上角，与宿主内的底图或界面完全脱节。

2. 容器必须具备显式的宽度与高度

heatmap.js 初始化时，会通过容器的 clientWidth 和 clientHeight 属性来确定内部 Canvas 的实际像素分辨率。如果宿主容器未设置宽高、未被内部内容撑开，或者处于 display: none 的隐藏状态，其尺寸即为 0 像素。库内部建立的高宽为 0 的 Canvas 无法执行任何实际的像素绘制，导致热力图完全隐形。

/* 宿主容器的标准 CSS 配置范例 */
#heatmapContainer {
  position: relative;          /* 强制声明为相对定位，作为内部 Canvas 的定位包含块 */
  width: 640px;                /* 明确的像素宽度或百分比（需父级尺寸确定） */
  height: 400px;               /* 明确的像素高度 */
  border: 1px solid #CBD5E1;   /* 调试期建议加上边框，便于核对可视边界 */
  overflow: hidden;            /* 裁切可能超出边缘的数据羽化光晕 */
}

三、调用 h337.create 创建热力图实例

完成 CDN 引入和 DOM 容器搭建后，即可使用工厂方法 h337.create(config) 构造热力图实例。该方法接收一个包含各种渲染参数的配置对象，并返回操作热力图的核心 API 句柄。

1. 核心配置参数列表

2. 内部色彩映射流水线（Two-Pass 机制）

在调用 h337.create() 时，库在内存中除了创建显示用的 Canvas，还会创建一块离屏阴影缓冲（Shadow Canvas）和一张 1×256 像素的调色板（Palette Look-Up Table）。绘制数据点时，首先利用纯黑灰度径向渐变将各点的 Alpha 透明度通道累加叠加；随后读取累加后的 Alpha 像素值（0 到 255），以此作为数组下标，在 1×256 的调色板中查询对应的 RGB 色彩，最终将彩色像素批量输出至屏幕 Canvas。因此，合理调整 gradient、blur 和 radius 能直接决定最终图像的信息表现力。

四、装载测试数据与结果验证

实例创建成功后，页面依然是空白的，因为此时 Canvas 中还没有注入数据点。heatmap.js 提供了两种数据灌入接口：

• heatmapInstance.setData(dataObject)：用于一次性重置或全量载入数据集。
• heatmapInstance.addData(pointOrPoints)：用于在保留既有图层的基准上，增量追加一个或多个数据点（常见于鼠标实时移动轨迹、WebSocket 实时流数据追加）。

全量数据对象的格式必须包含 max（数据极值，用于归一化权重计算）和 data（包含 x、y、value 属性的坐标数组）。以下是一份可以直接在浏览器中运行的完整单文件示例：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>heatmap.js 初始化演示</title>
  <style>
    /* 1. 约束宿主尺寸与相对定位包含块 */
    #heatmapBox {
      position: relative;
      width: 600px;
      height: 360px;
      border: 1px solid #CBD5E1;
      background-color: #F8FAFC;
    }
  </style>
  /* 2. 从 CDN 引入 heatmap.js 核心库 */
  <script src="https://cdnjs.cloudflare.com/ajax/libs/heatmap.js/2.0.2/heatmap.min.js"></script>
</head>
<body>

  <div id="heatmapBox"></div>

  <script>
    // 3. 待 DOM 结构就绪后执行初始化逻辑
    window.addEventListener('DOMContentLoaded', function () {
      
      // 获取目标容器
      const containerEl = document.getElementById('heatmapBox');

      // 4. 调用 h337.create 创建热力图实例
      const heatmapInstance = h337.create({
        container: containerEl,
        radius: 35,
        maxOpacity: 0.8,
        minOpacity: 0.05,
        blur: 0.85,
        gradient: {
          '.3': '#52677D',
          '.6': '#4ADE80',
          '.8': '#FBBF24',
          '.95': '#A66C5B'
        }
      });

      // 5. 构建规范的输入数据集
      const testData = {
        max: 100,
        min: 0,
        data: [
          { x: 150, y: 120, value: 95 },
          { x: 160, y: 130, value: 80 },
          { x: 300, y: 180, value: 50 },
          { x: 450, y: 240, value: 75 },
          { x: 470, y: 250, value: 90 }
        ]
      };

      // 6. 灌入数据并触发画布渲染
      heatmapInstance.setData(testData);
    });
  </script>
</body>
</html>

在浏览器中打开上述代码，可以看到 #heatmapBox 容器内自动渲染出了由蓝灰经绿、黄直至赭红的平滑热力分布斑块。检查 DOM 结构可以看到，该容器内部已多出一行 <canvas class="heatmap-canvas" width="600" height="360"></canvas>，证明初始化与首屏渲染顺利完成。

五、常见初始化故障与排查清单

在实际工程中，由于引入时机、组件生命周期以及 CSS 排版的多样性，经常会遇到以下四种典型异常。遇到问题时，可以按照下方排查决策树进行针对性定位。