本文详解如何通过 zmin/zmax 和自定义离散化 colorscale，在 Plotly.js 热力图中实现按数值区间（如 [-3, -0.1]→蓝、[-0.1, 0.1]→白、[0.1, 3]→红）精准着色，避免默认归一化导致的颜色错位。
本文详解如何通过 `zmin`/`zmax` 和自定义离散化 colorscale，在 plotly.js 热力图中实现按数值区间（如 [-3, -0.1]→蓝、[-0.1, 0.1]→白、[0.1, 3]→红）精准着色，避免默认归一化导致的颜色错位。
Plotly.js 的 colorscale 默认将数据的最小值和最大值分别映射到颜色比例尺的 0% 和 100%，而不会直接响应你指定的原始数据值（如 -3、-0.1、0.1、3）。你代码中使用的 [3, '#970300'] 这类写法，实际表示的是「该颜色应用于 z 值归一化后占比为 3% 的位置」——这正是问题根源：你误将原始数据值当作归一化坐标使用了。
要真正实现「值 ∈ [-3, -0.1] → 蓝色渐变；∈ [-0.1, 0.1] → 白色；∈ [0.1, 3] → 红色渐变」，关键在于两步：
✅ 第一步：显式固定数据范围 —— 设置 zmin 和 zmax
强制 Plotly 将 zmin 映射为 colorscale 的 0%，zmax 映射为 100%。这样，你后续定义的颜色断点就能基于真实数据值进行线性插值。
zmin: -3.0, // 数据最小基准值（对应 colorscale 0%） zmax: 3.0, // 数据最大基准值（对应 colorscale 100%） autocolorscale: false, // 必须禁用自动缩放，否则 zmin/zmax 无效
✅ 第二步：用归一化坐标定义 colorscale（推荐简洁写法）
既然 zmin=-3 → 0%，zmax=3 → 100%，那么任意原始值 v 对应的归一化位置为：
(v - zmin) / (zmax - zmin) = (v + 3) / 6
据此计算关键分界点的归一化坐标：
- -3.0 → 0.0
- -0.1 → (-0.1 + 3) / 6 ≈ 0.483
- 0.1 → (0.1 + 3) / 6 ≈ 0.517
- 3.0 → 1.0
于是可构建清晰、可维护的离散 colorscale：
colorscale: [ [0.0, '#000A63'], // z = -3.0 → 深蓝 [0.483, '#555EAD'], // z = -0.1 → 浅蓝（过渡终点） [0.483, '#FFFFFF'], // z = -0.1 → 白色（蓝色区结束，白色区开始） [0.517, '#FFFFFF'], // z = 0.1 → 白色（白色区结束） [0.517, '#AF0300'], // z = 0.1 → 浅红（红色区开始） [1.0, '#970300'] // z = 3.0 → 深红 ],
? 技巧：重复同一归一化坐标（如 [0.483, 'blue'] 和 [0.483, 'white']）可实现颜色突变（硬边界），避免平滑过渡。
✅ 完整可运行示例
const heatmapData = [{
z: total_L2FC,
x: indiv_name_list,
y: gene_list,
type: 'heatmap',
hovertemplate: 'Gene: %{y}<br>Individual: %{x}<br>log2FoldChange: %{z}<br>p-adj: %{customdata}<extra></extra>',
customdata: total_padj,
colorscale: [
[0.0, '#000A63'], // ≤ -3.0 → 深蓝
[0.483, '#555EAD'], // -0.1 → 浅蓝
[0.483, '#FFFFFF'], // -0.1 → 白色（突变起点）
[0.517, '#FFFFFF'], // 0.1 → 白色（突变终点）
[0.517, '#AF0300'], // 0.1 → 浅红
[1.0, '#970300'] // ≥ 3.0 → 深红
],
zmin: -3.0,
zmax: 3.0,
autocolorscale: false,
showscale: true,
colorbar: {
title: { text: 'log<sub>2</sub>FC', font: { size: 14 } }
}
}];
Plotly.newPlot('heatmap-container', heatmapData);⚠️ 注意事项
- 务必设置 autocolorscale: false：否则 zmin/zmax 将被忽略；
- colorscale 中的数值是归一化坐标（0–1），不是原始数据值：所有断点需按 (v - zmin) / (zmax - zmin) 手动换算；
- 若数据存在超出 [-3, 3] 的异常值，Plotly 会自动截断（clip）——值 < zmin 显示为 colorscale[0]，> zmax 显示为 colorscale[last]，符合你的需求（如 < -3 显示深蓝，> 3 显示深红）；
- 避免混用 colors 数组属性（你原代码中的 colors: ...map(...)）与 colorscale：二者冲突，colors 仅用于旧版或特殊场景，现代做法统一用 colorscale + zmin/zmax 控制。
通过这一组合策略，你就能彻底摆脱 Plotly 默认归一化的干扰，实现真正基于业务语义的数据区间着色——精准、可控、可复现。
