本文介绍如何通过自定义 colorscale 实现 plotly.js 热力图中基于数值阈值的条件高亮——将高于指定阈值的像素以醒目颜色（如红色）突出显示，而低于阈值的部分则设为灰度或透明，从而快速聚焦关键区域。
本文介绍如何通过自定义 colorscale 实现 plotly.js 热力图中基于数值阈值的条件高亮——将高于指定阈值的像素以醒目颜色（如红色）突出显示，而低于阈值的部分则设为灰度或透明，从而快速聚焦关键区域。
在 Plotly.js 中，热力图（type: 'heatmap'）默认使用连续色阶映射整个数据范围。若需强调满足特定条件（如 value > threshold）的数据点，不能依赖交互式选择或后置 DOM 操作，而应通过语义化、声明式的方式——即重构 colorscale，将数值区间按阈值“切片”，实现视觉上的条件渲染。
核心思路是：将原始数据范围 [min, max] 归一化为 [0.0, 1.0]，再在 colorscale 数组中插入重复的归一化断点（breakpoint），形成“阶梯状”色阶。Plotly 会自动对落在同一区间内的所有值应用对应颜色。
✅ 基础双色高亮示例（白→红）
以下代码将所有 z[i][j] ≥ 5 的单元格渲染为红色，其余为白色：
<script src="https://cdn.plot.ly/plotly-2.26.0.min.js"></script> <div id="plot"></div>
const min = 0;
const max = 10;
const threshold = 5;
const z = Array.from({length: 100}, () =>
Array.from({length: 100}, () => Math.floor(Math.random() * (max + 1)))
);
// 归一化断点：5 / 10 = 0.5
const breakpoint = threshold / max;
const colorscale = [
[0.0, 'white'], // [0.0, breakpoint): 白色（含 0.0，不含 breakpoint）
[breakpoint, 'white'], // 断点左边界仍为白色
[breakpoint, 'red'], // 断点右边界起 → 红色（含 breakpoint）
[1.0, 'red'] // 覆盖至最大值
];
Plotly.newPlot('plot', [{
z,
type: 'heatmap',
colorscale,
zmin: min,
zmax: max,
showscale: true // 推荐开启色标便于理解阈值位置
}]);? 关键机制说明：[[0,'w'],[0.5,'w'],[0.5,'r'],[1,'r']] 构造了一个“硬切换”色阶。Plotly 在插值时，对任意 zVal ∈ [0,5) 映射到 [0.0, 0.5) 区间 → 白色；对 zVal ∈ [5,10] 映射到 [0.5, 1.0] → 红色。重复的 breakpoint 是实现非渐变切换的必要技巧。
? 进阶：灰度弱化 + 渐变高亮
若需更精细的视觉层次（例如弱化低值区、对高值区施加渐变强调），可扩展 colorscale：
const colorscale = [ [0.0, 'rgba(169,169,169,0.3)'], // 浅灰半透明，弱化背景 [breakpoint, 'rgba(169,169,169,0.3)'], [breakpoint, 'rgb(220,170,132)'], // 阈值起点：暖橙色过渡 [1.0, 'rgb(178,10,28)'] // 高值终点：深红色强化 ];
此方案既保持低值区“存在感降低”，又通过色彩饱和度与明度变化引导视线至高值区域，符合数据可视化最佳实践。
⚠️ 注意事项与最佳实践
- 务必设置 zmin 和 zmax：确保 color mapping 基于你预设的理论范围（而非数据实际 min/max），否则 breakpoint 计算失效；
- 避免浮点精度陷阱：threshold / max 应确保结果在 [0,1] 内；若 threshold > max，需做 Math.min(breakpoint, 1) 保护；
- 色标可读性：启用 showscale: true 并配合 colorbar.title 标注阈值位置（如 "Threshold = 5"）；
- 性能考量：该方法纯客户端渲染，无额外计算开销，适用于万级单元格规模；
- 无障碍提示：可通过 hovertemplate 添加阈值状态说明，例如 hovertemplate: 'Value: %{z}<br>%{z}>5? %{z > 5}'。
通过精准控制 colorscale 的断点逻辑，你无需修改原始数据、不依赖事件监听，即可在 Plotly 热力图中实现高效、声明式、可复用的阈值高亮效果——让关键信号从噪声中自然浮现。
