本文详解如何通过复用 Plotly 内置绘图工具（如 drawcircle）并结合 plotly_click 事件，在热力图上实现精准的单像素点击标记（类似地图“钉针”），支持动态添加/删除标注、坐标与数值显示，并规避 drawcircle 模式下事件失效问题。
本文详解如何通过复用 plotly 内置绘图工具（如 `drawcircle`）并结合 `plotly_click` 事件，在热力图上实现精准的单像素点击标记（类似地图“钉针”），支持动态添加/删除标注、坐标与数值显示，并规避 `drawcircle` 模式下事件失效问题。
在 Plotly 热力图交互中，矩形框选（select2d）已原生支持，但单点精确定位与可视化标记（如高亮某像素、添加带信息的“红钉”）需开发者自行扩展。关键挑战在于：当用户启用 drawcircle 等绘图模式时，plotly_click 事件被拦截，无法捕获初始点击位置；而 plotly_selected 仅返回选区范围，不提供精确像素坐标。
解决方案的核心思路是：不依赖绘图模式的事件流，而是将“标记”行为绑定到全局点击事件，并通过 dragmode 状态智能判断当前是否处于“标记意图”。我们复用 drawcircle 按钮作为视觉提示（用户点击该图标即进入“Pin 模式”），但实际逻辑完全绕过其绘图逻辑，转而监听 plotly_click 并仅在 dragmode === 'select' 时触发标注——因为 drawcircle 激活后，Plotly 会将 dragmode 切换为 'drawcircle'；而我们将 drawcircle 按钮映射为 'select' 模式（语义上更契合“选择单点”），从而既保留 UI 一致性，又恢复事件响应能力。
以下为完整可运行实现：
<script src="https://cdn.plot.ly/plotly-2.16.2.min.js"></script> <div id="plot" style="width: 600px; height: 500px;"></div>
const z = Array.from({ length: 50 }, () =>
Array.from({ length: 50 }, () => Math.floor(Math.random() * 255))
);
const plot = document.querySelector("#plot");
const data = [{
type: "heatmap",
z: z,
colorscale: "Viridis"
}];
const layout = {
yaxis: { scaleanchor: "x", autorange: true },
xaxis: { autorange: true },
margin: { t: 40, b: 40, l: 40, r: 40 }
};
// 关键配置：将 drawcircle 按钮重映射为 select 模式（非真实绘图）
const config = {
modeBarButtons: [
["zoom2d"],
["zoomIn2d"],
["zoomOut2d"],
["autoScale2d"],
["select2d"],
// 替换原 drawcircle 为自定义 select 按钮（视觉相同，行为不同）
[{
name: "pin_pixel",
icon: Plotly.Icons.drawcircle,
click: () => {
Plotly.relayout(plot, "dragmode", "select"); // 强制设为 select 模式
}
}]
],
displaylogo: false,
displayModeBar: true,
modeBarButtonsToAdd: []
};
Plotly.newPlot("plot", data, layout, config);
// 主交互逻辑：仅在 dragmode === 'select' 时响应点击（即 Pin 模式激活）
plot.on("plotly_click", function(data) {
if (data?.points?.length && plot._fullLayout.dragmode === "select") {
const point = data.points[0];
// 将数据坐标转换为布局坐标（用于 annotation 定位）
const xLayout = point.xaxis.d2l(point.x);
const yLayout = point.yaxis.d2l(point.y);
// 构建标注对象：模拟“地图钉针”效果
const newAnnotation = {
x: xLayout,
y: yLayout,
xref: "x",
yref: "y",
text: `<b>Pixel [${point.x}, ${point.y}]</b><br>Value: <b>${point.z}</b>`,
font: { size: 12, color: "#333" },
bgcolor: "rgba(255, 255, 255, 0.95)",
bordercolor: "#e0312f",
borderwidth: 2,
borderpad: 6,
showarrow: true,
arrowhead: 6,
arrowsize: 1,
arrowwidth: 2,
ax: 0,
ay: -50,
opacity: 0.95
};
const annotations = plot._fullLayout.annotations || [];
const existingIndex = annotations.findIndex(
ann => ann.x === xLayout && ann.y === yLayout
);
// 点击已存在标注则删除（Toggle 行为）
if (existingIndex !== -1) {
Plotly.relayout("plot", `annotations[${existingIndex}]`, "remove");
return;
}
// 添加新标注（追加至末尾）
const newIndex = annotations.length;
Plotly.relayout("plot", `annotations[${newIndex}]`, newAnnotation);
}
});
// 支持点击标注直接删除（增强用户体验）
plot.on("plotly_clickannotation", function(event, data) {
Plotly.relayout("plot", `annotations[${data.index}]`, "remove");
});✅ 关键要点说明：
- 模式映射技巧：通过自定义 modeBarButtons 中的 click 回调，将 drawcircle 图标绑定为 dragmode = 'select'，既复用 UI 元素，又规避原生绘图模式对 plotly_click 的屏蔽。
- 坐标转换必要性：point.x/point.y 是数据索引（整数），需经 xaxis.d2l() 转为布局坐标系中的像素位置，确保标注精准覆盖目标像素中心。
- 防重复与 Toggle 机制：检查新点击位置是否已有标注，存在则移除，实现“点击标记/再点击取消”的自然交互。
- 标注样式优化：使用 showarrow: true + arrowhead: 6 模拟“钉针”视觉，bgcolor/bordercolor 突出信息，ay: -50 控制标签悬浮高度，避免遮挡热力图。
⚠️ 注意事项：
- 此方案要求 Plotly.js ≥ v2.12（推荐 v2.16+），低版本可能存在 d2l 方法兼容性问题；
- 若热力图启用了 zsmooth: 'best' 或插值，point.x/point.y 仍返回原始整数索引，不影响定位准确性；
- 如需支持多点标记且禁止覆盖，可移除重复检测逻辑，并改用唯一 ID 管理标注数组；
- 移动端需额外测试触摸事件兼容性，建议增加 plotly_hover 辅助提示。
通过上述实现，你无需引入第三方库，即可在 Plotly 热力图中构建专业级的单像素探查工作流——无论是调试数据异常点、标注 ROI，还是构建交互式分析面板，该“Pin”功能都提供了简洁、可靠、符合用户直觉的底层支持。
