怎么自定义 heatmap.js 的渐变色 gradient 与半径 radius

作者：流萤

时间：2026-11-02

深入讲解 heatmap.js 中 gradient（渐变色调色板）与 radius（扩散半径）的自定义方法，涵盖底层离线调色板映射原理、全局配置与单点动态覆盖、运行时动态重绘及常见问题排查。

文章目录

怎么自定义 heatmap.js 的渐变色 gradient 与半径 radius — 图 0：heatmap.js 渐变色调色板与扩散半径核心机制速览

在 heatmap.js 中，热力图呈现的核心视觉效果完全取决于渐变色 gradient 与半径 radius 这两项配置。radius 决定了单个坐标点向四周漫延衰减的像素覆盖面积，而 gradient 则决定了累加密度从低到高映射成的颜色阶梯。若要实现自定义，只需在初始化配置对象中传入 gradient 映射表和 radius 数值，或在单个数据点中动态声明独立的 radius 属性。

一、核心原理：Canvas 离线调色板与 Alpha 密度采样

许多开发者在初次修改 gradient 或 radius 时，常会遇到渐变断层、黑边、或者边缘生硬的问题。要彻底掌握这两项参数的调试，首先要清楚 heatmap.js 在 HTML5 Canvas 下的渲染流程：

Alpha 灰度累加层：当调用 setData 载入点位时，heatmap.js 首先在隐藏的主 Canvas 上，按照设定的 radius 绘制中心不透明、四周逐渐透明（基于径向渐变或预缓存的 Alpha 模板）的灰度光晕。重叠越多的区域，Alpha 通道值（0 到 255）累积得越高。
离线调色板生成：heatmap.js 会在内存中创建一个宽度为 256 像素、高度为 1 像素的离线 Canvas，并将用户配置在 gradient 中的键值对依次作为颜色停靠点（addColorStop），绘制成一条 256 像素宽的水平线性渐变色带。
像素重绘上色：渲染引擎逐像素读取主 Canvas 的 Alpha 通道灰度值（对应 0 到 255 的整数索引），以此索引在离线调色板的像素数组中直接取出对应的 RGB 颜色，再写回画布完成着色。

因此，radius 直接决定了第一阶段每个数据点向外扩散并累积 Alpha 的范围；而 gradient 则在第二阶段通过离线 256 像素色带完成连续色彩插值。

二、自定义渐变色 gradient：色带区间与代码实现

gradient 的配置是一个普通的 JavaScript 对象。其键名（Key）必须是 0.0 到 1.0 之间的浮点数字符串，代表该颜色在热力密度归一化区间的停靠位置；键值（Value）可以是任意合法的 CSS 颜色表达式（包括十六进制色彩、RGB、RGBA 或标准颜色名）。

1. 标准冷暖经典配色

以下示例配置了从半透明蓝、浅青、翠绿、明黄到鲜红的经典五段色谱：

// 经典五段式冷暖渐变配置
const heatmapInstance = h337.create({
  container: document.getElementById('heatmapContainer'),
  radius: 30,
  maxOpacity: 0.8,
  minOpacity: 0.05,
  blur: 0.85,
  gradient: {
    '0.25': 'rgb(0, 0, 255)',    // 25% 密度：深冷蓝
    '0.55': 'rgb(0, 255, 128)',  // 55% 密度：蓝绿过渡
    '0.75': 'rgb(255, 255, 0)',  // 75% 密度：中高密度黄色
    '1.0': 'rgb(255, 0, 0)'      // 100% 密度：核心极热区红色
  }
});

渐变键值防坑注意

尽量避免将 '0.0' 或过低的阈值（例如 '0.01'）设为不透明深色。因为在 Canvas 密度映射中，最边缘只要有哪怕 1 像素的极微弱散乱点，其密度也会落在低阈值内。如果低阈值不是透明或浅淡色，整个画布边缘就会出现大面积生硬的底色色块。

2. 科技感暗调单色渐变（常用于大屏与暗黑主题）

若业务系统需要与深色底图搭配，可以将色谱约束在深蓝至高亮霓虹青之间：

// 暗调霓虹蓝绿科技风渐变
const darkThemeGradient = {
  '0.2': 'rgba(15, 32, 67, 0.4)',
  '0.4': 'rgb(30, 144, 255)',
  '0.7': 'rgb(0, 245, 212)',
  '0.95': 'rgb(255, 255, 255)' // 中心高光纯白
};

三、自定义半径 radius：全局设置与单点动态覆盖

radius 参数定义了热点核心向外渐变辐射的物理像素半径。heatmap.js 支持两种维度的半径定义：全局默认半径与数据点独立的动态半径。

1. 全局半径（Global Radius）

在 h337.create 初始化时配置 radius。当所有数据点的重要性或实体大小一致时（例如网页用户鼠标点击分布），应当采用全局配置。此时 heatmap.js 会预先缓存单个尺寸的画刷模板，具有最高的渲染性能：

// 基础全局半径配置
const heatmapInstance = h337.create({
  container: document.getElementById('heatmapContainer'),
  radius: 40,   // 全局基准半径：40 像素
  blur: 0.8     // 模糊边缘平滑系数 (0~1)
});

2. 单点动态半径（Per-point Dynamic Radius）

在实际地理信息（GIS）或基站信号模拟等场景中，不同实体的影响力范围往往不同。heatmap.js 允许在数据点对象中直接传入独立的 radius 字段。当存在该字段时，heatmap.js 会为该点单独生成指定大小的画刷：

// 数据注入时为特定点指定独立 radius
const dataPoints = [
  { x: 120, y: 150, value: 30 },               // 未传 radius，使用全局默认 40px
  { x: 260, y: 180, value: 85, radius: 20 },   // 局部密集聚焦，强制缩小为 20px
  { x: 420, y: 220, value: 95, radius: 70 }    // 核心大范围辐射源，扩展至 70px
];

heatmapInstance.setData({
  max: 100,
  min: 0,
  data: dataPoints
});

单点设置的 radius 具有最高优先级，会自动覆盖初始化时的全局参数，这使得单个热力图中展现多尺度混合实体成为可能。

四、操作步骤：配置并动态更新热力图

将渐变色与半径应用到实际前端页面中，通常包含容器声明、参数初始化、数据载入以及运行时动态调整四个阶段：

完整代码示例

<!DOCTYPE html>
<html>
<head>
  <style>
    #heatmapContainer {
      position: relative;
      width: 800px;
      height: 450px;
      background: #F8FAFC;
      border: 1px solid #CBD5E0;
    }
  </style>
</head>
<body>
  <div id="heatmapContainer"></div>

  <!-- 引入 heatmap.js -->
  <script src="https://cdnjs.cloudflare.com/ajax/libs/heatmap.js/2.0.2/heatmap.min.js"></script>
  <script>
    // 1. 初始化实例
    const heatmap = h337.create({
      container: document.getElementById('heatmapContainer'),
      radius: 35,
      maxOpacity: 0.75,
      minOpacity: 0.05,
      blur: 0.8,
      gradient: {
        '0.3': '#4361EE',
        '0.6': '#4CC9F0',
        '0.8': '#F72585',
        '1.0': '#7209B7'
      }
    });

    // 2. 模拟灌入数据
    heatmap.setData({
      max: 100,
      min: 0,
      data: [
        { x: 200, y: 150, value: 80 },
        { x: 220, y: 160, value: 60 },
        { x: 450, y: 250, value: 90, radius: 60 } // 自定义单点大半径
      ]
    });

    // 3. 运行时动态修改配置（例如用户在界面切换主题或滑动调节半径）
    function updateHeatmapSettings(newRadius, newGradient) {
      heatmap.configure({
        radius: newRadius,
        gradient: newGradient
      });
      // configure 会自动更新调色板并基于当前数据重新渲染
    }
  </script>
</body>
</html>

五、参数调优参考与常见问题排查

在实际配置过程中，渐变过渡与半径大小通常需要配合调试。以下是不同业务形态下的参考基准与注意事项：

场景类型	数据特征	推荐 Radius	推荐 Blur	Gradient 停靠点设计要点
细粒度点击热图	点密集、重合多、定位精确	12 ~ 25 px	0.85 ~ 0.90	提高起始阈值（如从 0.35 开始），避免密集处混成一片白光
区域辐射与环境场	点稀疏、需大面积连续插值	50 ~ 100 px	0.70 ~ 0.80	平缓的多段停靠（0.2、0.4、0.6、0.8、1.0），增强渐变平滑度
告警监控热区	高危阈值敏感、视觉强调	30 ~ 45 px	0.75	中高位（0.8 以上）直接截断进入亮红，突出异常点集中区域

排查清单与技巧

为什么画面边缘有明显的矩形或灰色黑圈？
这是由于 gradient 包含了过低的阈值（例如 '0.0': '#000000' 或带透明度不足的深色）。应确保渐变的最低起始键从 0.2 左右开始，或设置实例的 minOpacity: 0。
为什么修改了 radius 画面没有变化？
检查数据源中的点是否都自带了 radius 属性。单点属性优先级高于实例全局参数。此外，如果是通过调用 heatmap.configure() 进行运行时更改，确保未向数据点硬编码固定半径。
页面缩放或容器自适应时热力图错位或拉伸：
heatmap.js 内部 Canvas 尺寸绑定于容器的物理像素宽高。在窗口 Resize 后，应重新计算容器尺寸并调用 heatmap._renderer.setDimensions(width, height) 或更新实例配置并重新 setData。