怎么在 Plotly.js 中实现缩放、悬停提示及点击事件交互

一、Plotly.js 交互运行机制与准备工作

Plotly.js 建立在 D3.js 与 WebGL 之上，其交互设计遵循“配置声明 + 事件总线驱动”的思想。与其他底层可视化库不同，Plotly.js 在默认状态下就内置了丰富的交互能力（如框选缩放、平移模式工具栏以及自动悬停点位浮层）。然而在实际业务中，开发者往往需要精细控制哪些轴允许缩放、展示包含丰富业务维度的个性化 Hover 标签，或者在用户单击某个数据拐点时联动外部组件展示明细。

要实现这些扩展交互，核心在于理解 Plotly.js 的 DOM 节点不仅是一个绘图容器，更是一个标准的事件分发器（基于 Node.js 风格的 EventEmitter）。通过 Plotly.newPlot 完成初次渲染后，该 DOM 对象会暴露 on、once 和 removeAllListeners 等方法，供业务代码注册特定事件钩子。

在网页中引入 Plotly.js 可以通过官方 CDN 引入完整版，也可以使用 npm 包管理引入。一个基础的 HTML 挂载容器与脚本骨架如下：

<!-- 引入 Plotly.js 核心库 -->
<div id="myPlot" style="width: 100%; height: 500px;"></div>
<script src="https://cdn.plot.ly/plotly-2.35.2.min.js"></script>

<script>
  const gd = document.getElementById('myPlot');
  // 后续交互配置与事件监听均绑定至此 gd 对象
</script>

二、实现缩放（Zoom）与平移（Pan）精细控制

Plotly.js 在笛卡尔坐标系下默认提供基于矩形框选的缩放能力（Drag-to-Zoom）。用户按住鼠标左键在绘图区域拖动即可拉出矩形，松开鼠标后视图将自动裁切放大至所选区域；双击绘图区则自动重置回原始范围。如果希望根据业务场景调整缩放行为，可以通过 layout、config 以及编程式 API 进行定制。

1. 交互模式与轴向锁定

默认拖拽行为通过 layout.dragmode 指定，常用值包括：

• 'zoom'：默认模式，矩形框选缩放。
• 'pan'：抓手平移模式，按住鼠标拖拽整体图表。
• 'select' / 'lasso'：套索选择点，常用于多点框选统计。
• false：禁用绘图区域的一切拖拽交互。

在时序图或多指标监控看板中，通常只允许横向（时间轴）缩放，而禁止纵向（数值轴）缩放以防基准线失真。此时可以在轴属性中设置 fixedrange: true 来冻结特定轴：

const layout = {
  title: '销售走势分析图',
  dragmode: 'zoom', // 默认框选缩放
  xaxis: {
    title: '日期',
    fixedrange: false // 允许 X 轴被框选缩放
  },
  yaxis: {
    title: '成交金额 (万元)',
    fixedrange: true  // 锁定 Y 轴范围，禁止纵向拉伸
  }
};

// 在 config 中开启滚轮缩放与模式工具条配置
const config = {
  scrollZoom: true,        // 开启鼠标滚轮缩放
  displayModeBar: true,    // 保持右上角 ModeBar 常显
  responsive: true        // 窗口大小变化时自适应重绘
};

2. 编程式缩放与监听缩放事件

除了用户手动拖拽缩放外，业务前端还可以通过按钮快捷缩放（例如“查看近7天”、“查看近1月”），这可以通过 Plotly.relayout 函数实现：

// 编程式将 X 轴范围缩放至指定区间
Plotly.relayout(gd, {
  'xaxis.range': ['2026-10-01', '2026-10-15']
});

// 编程式恢复自适应范围（相当于用户双击画布）
Plotly.relayout(gd, {
  'xaxis.autorange': true,
  'yaxis.autorange': true
});

当用户在图表上完成缩放或平移操作后，Plotly 会向容器节点分发 plotly_relayout 事件。通过监听此事件，可以获取缩放后的确切坐标范围，进而实现服务端局部明细数据的按需加载（防全量大数据打垮内存）：

gd.on('plotly_relayout', function(eventData) {
  // 用户框选缩放后返回的数据格式：
  if (eventData['xaxis.range[0]'] && eventData['xaxis.range[1]']) {
    const xMin = eventData['xaxis.range[0]'];
    const xMax = eventData['xaxis.range[1]'];
    console.log(`当前可视 X 轴视窗已改变: ${xMin} 至 ${xMax}`);
    // 可在此处发起异步请求请求更高采样率的数据
  } else if (eventData['xaxis.autorange']) {
    console.log('视图已双击重置为完整全局范围');
  }
});

三、定制悬停提示（Hover Tooltips）

悬停提示（Hover）是用户了解数据详情的第一触点。Plotly.js 提供了非常成熟的模板系统（hovertemplate）与多点聚合机制（hovermode），避免生硬的默认文本。

1. 全局悬停聚合模式（hovermode）

在 layout.hovermode 中可以决定光标移入时如何触发浮层：

• 'closest'：只显示离光标几何距离最近的单个数据点的提示。散点图推荐此配置。
• 'x'（或 'x unified'）：多条折线对比时，显示所有在该 X 轴垂线上的点。'x unified' 会将多条曲线的数值合并在单个卡片中，体验极佳。
• false：全局关闭悬停提示。

2. 使用 hovertemplate 与 customdata 格式化内容

早期的 hoverinfo 只能简单拼接内置维度（如 'x+y+text'），而现代 Plotly.js 推荐使用 hovertemplate。它支持使用类似 d3-format 的语法占位符（如 %{y:.2f}），并通过 customdata 绑定任意业务元数据（例如订单编号、环比增幅、责任人等）：

const trace = {
  x: ['第1季度', '第2季度', '第3季度', '第4季度'],
  y: [45.2, 62.8, 85.4, 73.1],
  type: 'scatter',
  mode: 'lines+markers',
  name: '业务营收',
  // 注入额外的自定义多维数据
  customdata: [
    { growth: '+12%', target: '达标', manager: '张三' },
    { growth: '+18%', target: '达标', manager: '李四' },
    { growth: '+35%', target: '超额', manager: '王五' },
    { growth: '-5%',  target: '未达标', manager: '赵六' }
  ],
  // 使用 <extra></extra> 清除默认右侧的 trace 辅助标签
  hovertemplate: 
    '<b style="font-size:13px;">周期：%{x}</b><br>' +
    '营收数值：<b>%{y:.1f} 万元</b><br>' +
    '同比增速：%{customdata.growth}<br>' +
    '考核情况：%{customdata.target} (负责：%{customdata.manager})' +
    '<extra></extra>',
  hoverlabel: {
    bgcolor: '#17324D',      // 气泡背景深海蓝
    bordercolor: '#659B9B',  // 边框强调色灰青
    font: {
      family: 'PingFang SC, sans-serif',
      size: 12,
      color: '#FFFFFF'       // 文字颜色
    }
  }
};

四、实现点击事件（Click Event）与业务联动

点击事件是构建“下钻分析（Drill-down）”与“视图联动”的核心环节。在 Plotly 中，只需要监听图表 DOM 节点上的 plotly_click 事件，即可在回调中拿到被点击点位的全部上下文数据。

1. 捕获点击点位与提取 points 数组

当用户单击图表中的任意有效数据点时，Plotly 会将原生鼠标事件与图元拾取结果打包为 eventData 传入回调：

gd.on('plotly_click', function(eventData) {
  // 防御性判断是否拾取到了有效数据点
  if (!eventData || !eventData.points || eventData.points.length === 0) {
    return;
  }

  // 获取被点击的首个数据点（最靠近光标的点）
  const pt = eventData.points[0];
  
  const pointIdx = pt.pointIndex;      // 点在所属数组中的下标索引
  const curveIdx = pt.curveNumber;     // 所属 trace 的下标
  const xVal = pt.x;                   // 当前点的 X 轴数据
  const yVal = pt.y;                   // 当前点的 Y 轴数据
  const meta = pt.customdata;          // 绑定的业务自定义实体

  console.log(`用户点击了曲线 ${curveIdx} 的第 ${pointIdx} 项: (${xVal}, ${yVal})`, meta);

  // 触发业务层操作：例如打开抽屉侧边栏
  openDetailDrawer(meta);
});

2. 典型场景：点击动态高亮与样式响应

在点击点位后，如果想要让被点击的数据点在视觉上显著突出（例如其他点变浅灰、当前点变大并加上高亮颜色），可以调用 Plotly.restyle 动态更新 marker.color 与 marker.size 数组：

function highlightPoint(targetIdx, totalCount) {
  // 构造颜色数组与尺寸数组
  const colors = new Array(totalCount).fill('#CBD5E1');
  const sizes = new Array(totalCount).fill(8);

  // 目标选中项高亮
  colors[targetIdx] = '#17324D';
  sizes[targetIdx] = 14;

  Plotly.restyle(gd, {
    'marker.color': [colors],
    'marker.size': [sizes]
  }, [0]); // 第三个参数指定更新 trace[0]
}

五、交互功能开发标准实施流程

从零实现一个兼备专业视觉与丰富交互的 Plotly 图表，建议遵循以下四个标准实施阶段：

1. 基础挂载准备：确定宿主 DOM 元素宽高，准备规范的连续点集或离散分类数组，并注入 Plotly.js 运行环境。
2. 缩放与平移配置：在 layout 中明确默认 dragmode（如 'zoom' 或 'pan'），冻结不希望被放大的固定轴，并在 config 中配置鼠标滚轮响应。
3. 定制提示浮层：使用 customdata 打包额外业务维度，通过 hovertemplate 构建具有层级的信息文本，并统一 hoverlabel 的配色与圆角。
4. 事件总线绑定：调用 gd.on() 挂载 plotly_click 与 plotly_relayout 监听器，完成弹窗展示、外部表格过滤或跨图表联动。

六、综合实战示例：可直接复制运行的完整代码

下面是一个完整自包含的 HTML 演示示例。该示例综合实现了X轴自由缩放+Y轴锁定、带有业务指标的富文本悬停卡片以及点击点位后动态高亮并同步更新状态信息卡的完整联动闭环：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>Plotly.js 交互综合示例</title>
  <script src="https://cdn.plot.ly/plotly-2.35.2.min.js"></script>
  <style>
    body { font-family: sans-serif; background: #FAFBFD; padding: 20px; }
    .dashboard-wrap { max-width: 850px; margin: 0 auto; background: #fff; padding: 20px; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.05); }
    .info-bar { margin-top: 15px; padding: 12px; background: #F1F5F9; border-left: 4px solid #17324D; font-size: 14px; color: #334155; }
  </style>
</head>
<body>
  <div class="dashboard-wrap">
    <div id="chartContainer" style="width:100%; height:450px;"></div>
    <div id="infoPanel" class="info-bar">提示：尝试在图表内拉框缩放，悬停查看指标，或点击任意数据点以高亮联动。</div>
  </div>

  <script>
    const gd = document.getElementById('chartContainer');
    const infoPanel = document.getElementById('infoPanel');

    const rawX = ['1月', '2月', '3月', '4月', '5月', '6月'];
    const rawY = [120, 190, 150, 280, 220, 340];
    const rawMeta = [
      { orderCount: 1420, status: '平稳' },
      { orderCount: 2150, status: '冲高' },
      { orderCount: 1800, status: '回调' },
      { orderCount: 3200, status: '促销' },
      { orderCount: 2550, status: '平稳' },
      { orderCount: 4100, status: '历史新高' }
    ];

    // 1. 数据 Trace 配置
    const trace = {
      x: rawX,
      y: rawY,
      type: 'scatter',
      mode: 'lines+markers',
      line: { color: '#659B9B', width: 3 },
      marker: {
        size: [10, 10, 10, 10, 10, 10],
        color: ['#17324D', '#17324D', '#17324D', '#17324D', '#17324D', '#17324D']
      },
      customdata: rawMeta,
      hovertemplate: 
        '<b>时间：%{x}</b><br>' +
        '营收：%{y} 万元<br>' +
        '订单量：%{customdata.orderCount} 笔<br>' +
        '运营评估：%{customdata.status}<extra></extra>',
      hoverlabel: {
        bgcolor: '#17324D',
        bordercolor: '#659B9B',
        font: { color: '#FFFFFF', size: 12 }
      }
    };

    // 2. Layout 布局控制
    const layout = {
      title: { text: '上半年月度营收与订单交互走势', font: { size: 16 } },
      dragmode: 'zoom',
      hovermode: 'closest',
      xaxis: { fixedrange: false }, // X轴允许缩放
      yaxis: { fixedrange: true },  // Y轴锁定
      margin: { l: 50, r: 30, t: 50, b: 40 }
    };

    // 3. Config 选项
    const config = {
      scrollZoom: true,
      displayModeBar: true,
      responsive: true
    };

    // 4. 渲染图表
    Plotly.newPlot(gd, [trace], layout, config);

    // 5. 绑定点击事件
    gd.on('plotly_click', function(data) {
      if (!data || !data.points.length) return;
      const pt = data.points[0];
      const idx = pt.pointIndex;
      const meta = pt.customdata;

      // 更新外部状态面板
      infoPanel.innerHTML = 
        `<strong>已选定月份：</strong>${pt.x} | ` +
        `<strong>当月营收：</strong>${pt.y} 万元 | ` +
        `<strong>订单规模：</strong>${meta.orderCount} 笔 | ` +
        `<strong>状态：</strong><span style="color:#0284C7;">${meta.status}</span>`;

      // 动态改变点位尺寸与颜色实现高亮
      const newSizes = rawX.map((_, i) => i === idx ? 16 : 8);
      const newColors = rawX.map((_, i) => i === idx ? '#0284C7' : '#CBD5E1');

      Plotly.restyle(gd, {
        'marker.size': [newSizes],
        'marker.color': [newColors]
      }, [0]);
    });

    // 6. 绑定缩放事件
    gd.on('plotly_relayout', function(relayoutData) {
      if (relayoutData['xaxis.range[0]']) {
        infoPanel.innerHTML = 
          `视图已缩放：[${relayoutData['xaxis.range[0]']} ~ ${relayoutData['xaxis.range[1]']}]，双击图表可恢复全局。`;
      }
    });
  </script>
</body>
</html>

七、核心配置与交互特性对照总结

为了便于在实际项目中快速查阅与选型，下表及图示对三种交互特性的核心配置项、对应事件与典型应用模式进行了横向对比：