ECharts 中 tooltip.formatter 的 params 参数详解与自定义提示框实现

最新推荐文章于 2025-08-11 23:19:59 发布

原创最新推荐文章于 2025-08-11 23:19:59 发布 · 806 阅读

10 ·

CC 4.0 BY-SA版权

文章标签：

#echarts #前端 #javascript

在 ECharts 的 tooltip.formatter 函数中，params 对象包含了当前鼠标 hover 到的数据点的详细信息，这些信息可用于自定义提示框的显示内容。以下是 params 各属性的具体含义：

一、params参数详解

$vars: ['seriesName', 'name', 'value']
表示当前 tooltip 中可直接使用的变量列表。在字符串模板模式下（如 '{seriesName}: {value}'），可通过这些变量名直接引用对应的值。
轴相关属性
- axisDim: "x"：当前关联的轴维度（x 或 y），这里表示关联 x 轴。
- axisId: "\u0000series\u00000\u00000"：轴的唯一标识 ID（内部自动生成，通常无需关注）。
- axisIndex: 0：轴的索引（从 0 开始），这里表示第 1 个 x 轴。
- axisType: "xAxis.category"：轴的类型，xAxis.category 表示 x 轴是类目轴（用于显示分类数据，如“1月”“2月”）。
- axisValue: "1月"：当前鼠标 hover 位置对应的轴上的值（x 轴的类目值）。
- axisValueLabel: "1月"：轴值的显示标签（通常与 axisValue 一致，用于展示）。
样式相关属性
- borderColor: undefined：数据项的边框颜色（未定义时使用默认样式）。
- color: "#5470c6"：当前数据系列的主题色（如柱状图的柱子颜色、折线图的线条颜色）。
- marker: "<span ...></span>"：数据项的标记元素（HTML 片段），通常是一个与系列同色的小方块，用于在 tooltip 中显示图例标记。
组件与系列相关属性
- componentIndex: 0：当前组件在所有组件中的索引（这里指系列组件的索引）。
- componentSubType: "bar"：组件的子类型（即图表类型），这里是柱状图（bar）。
- componentType: "series"：组件类型，series 表示这是数据系列组件（承载具体数据的核心组件）。
- seriesId: "\u0000缴纳\u00000"：系列的唯一标识 ID（内部生成，包含系列名称“缴纳”）。
- seriesIndex: 0：当前系列在 option.series 数组中的索引（0 表示第一个系列）。
- seriesName: "缴纳"：当前系列的名称（对应 series.name 配置，用于区分不同数据系列）。
- seriesType: "bar"：系列的类型（与 componentSubType 一致，这里是柱状图）。
数据相关属性
- data: -50：当前数据点的原始数据值（未经过格式化处理的原始值）。
- dataIndex: 0：当前数据点在系列数据中的索引（0 表示系列中的第一个数据）。
- dataType: undefined：数据类型（未定义时为默认类型，特殊场景下可能有值，如时间序列）。
- dimensionNames: ['x', 'y']：数据的维度名称，x 对应 x 轴维度，y 对应 y 轴维度。
- encode: {x: Array(1), y: Array(1)}：数据编码规则，说明原始数据的哪个维度对应到 x 轴、哪个维度对应到 y 轴（用于映射数据与坐标轴的关系）。
- name: "1月"：当前数据点的名称（通常与 x 轴类目值一致，即 axisValue）。
- value: -50：当前数据点的数值（与 data 一致，可直接用于显示）。

这些属性共同描述了鼠标 hover 位置的数据上下文，通过组合这些属性，可灵活定制 tooltip 的显示内容（例如：{seriesName}在{name}的值为{value}）。

在 ECharts 中，当我们需要为单系列数据添加额外的提示信息（如气温、降雨量等不在主数据中的内容）时，可以通过 dataIndex 实现。核心思路是：创建一个与数据系列长度相同的额外信息数组，利用 dataIndex 作为索引，在 tooltip 中关联对应位置的额外信息。

二、通过 dataIndex 关联额外信息，从而实现自定义提示框

这里以单系列数据举例，对于多系列数据可以通过二维数组[seriesIndex][dataIndex]的方式来关联数据

准备主数据和额外信息数组
- 主数据：即系列的 data 数组（如每月的某个核心指标）。
- 额外信息数组：创建一个与主数据长度相同的数组，存储每个数据点对应的额外信息（如气温、降雨量）。
在 tooltip 中通过 dataIndex 关联额外信息
- 在 tooltip.formatter 函数中，通过 params.dataIndex 获取当前数据点在数组中的索引。
- 使用该索引从额外信息数组中取出对应的数据，拼接到提示框中。

示例代码

假设我们有一个月度数据的柱状图，主数据是“每月平均湿度”，额外信息是“每月平均气温”和“每月降雨量”，实现如下：

// 1. 主数据（每月平均湿度）
const mainData = [60, 65, 70, 75, 80, 85, 82, 78, 72, 68, 63, 58];

// 2. 额外信息数组（与主数据长度一致，索引对应）
const extraInfo = [
  { temp: 15, rainfall: 50 },   // 1月：气温15℃，降雨量50mm
  { temp: 18, rainfall: 60 },   // 2月
  { temp: 22, rainfall: 80 },   // 3月
  { temp: 26, rainfall: 120 },  // 4月
  { temp: 29, rainfall: 180 },  // 5月
  { temp: 32, rainfall: 200 },  // 6月
  { temp: 34, rainfall: 160 },  // 7月
  { temp: 33, rainfall: 140 },  // 8月
  { temp: 28, rainfall: 90 },   // 9月
  { temp: 23, rainfall: 70 },   // 10月
  { temp: 19, rainfall: 60 },   // 11月
  { temp: 16, rainfall: 55 }    // 12月
];

// 3. ECharts 配置
const option = {
  xAxis: {
    type: 'category',
    data: ['1月', '2月', '3月', '4月', '5月', '6月', '7月', '8月', '9月', '10月', '11月', '12月']
  },
  yAxis: {
    type: 'value',
    name: '平均湿度(%)'
  },
  series: [
    {
      name: '月度湿度',
      type: 'bar',
      data: mainData  // 主数据
    }
  ],
  tooltip: {
    // 4. 自定义提示框内容，通过 dataIndex 关联额外信息
    formatter: function(params) {
      // params.dataIndex 是当前数据点在数组中的索引（0-11）
      const index = params.dataIndex;
      // 从额外信息数组中获取对应的数据
      const info = extraInfo[index];
      
      // 拼接提示内容（包含主数据和额外信息）
      return `
        <div>
          <p>${params.name} 数据</p>
          <p>${params.seriesName}: ${params.value}%</p>
          <p>平均气温: ${info.temp}℃</p>
          <p>降雨量: ${info.rainfall}mm</p>
        </div>
      `;
    }
  }
};

关键逻辑说明

额外信息数组与主数据的关联：extraInfo 数组的长度必须与 mainData 一致，且索引一一对应（如 extraInfo[0] 对应 1月的数据）。
dataIndex 的作用：params.dataIndex 会返回当前鼠标悬停的数据点在 series.data 中的索引（从 0 开始），利用这个索引可以精准定位到 extraInfo 中对应的额外信息。
灵活扩展：除了气温、降雨量，还可以在 extraInfo 中存储任何需要展示的信息（如风速、空气质量等），只需在 formatter 中读取即可。