提示框(Tooltip)配置

提示框(Tooltip)配置

ECharts中的提示框(Tooltip)是数据可视化交互的核心组件之一，当用户悬停在图表元素上时显示详细数据信息。通过灵活配置tooltip可以实现丰富的数据展示效果，包括自定义内容格式、触发方式、样式调整等。

基础配置

最基本的tooltip配置只需要设置trigger属性即可启用：

option = {
  tooltip: {
    trigger: 'item' // 或 'axis'
  },
  series: [
    {
      type: 'bar',
      data: [5, 20, 36, 10, 10, 20]
    }
  ]
};

trigger参数有两个可选值：

• 'item'：数据项图形触发，主要在散点图、饼图等无类目轴的图表中使用
• 'axis'：坐标轴触发，主要在柱状图、折线图等使用类目轴的图表中使用

触发方式进阶

除了基本的触发方式，还可以通过triggerOn控制触发条件：

tooltip: {
  trigger: 'axis',
  triggerOn: 'click' // 可选'mouseover'|'click'|'none'
}

组合配置可以实现更复杂的交互逻辑：

tooltip: {
  trigger: 'axis',
  axisPointer: {
    type: 'cross', // 十字准星指示器
    label: {
      backgroundColor: '#6a7985'
    }
  },
  triggerOn: 'mousemove|click' // 鼠标移动或点击都触发
}

内容格式化

字符串模板

通过formatter属性可以自定义提示框内容：

tooltip: {
  formatter: '{a} <br/>{b}: {c} ({d}%)'
}

模板变量包括：

• {a}：系列名称
• {b}：数据名称
• {c}：数据值
• {d}：百分比（仅饼图有效）
• {@xxx}：数据维度值，如{@product}表示product维度的值

回调函数形式

对于更复杂的格式化需求，可以使用函数形式：

tooltip: {
  formatter: function(params) {
    return `
      <div style="font-weight:bold">${params[0].name}</div>
      <div>${params[0].seriesName}: ${params[0].value}</div>
      <div>占比: ${(params[0].percent || 0).toFixed(2)}%</div>
    `;
  }
}

多系列处理

当图表包含多个系列时，params是一个数组：

tooltip: {
  formatter: function(params) {
    let result = params[0].axisValue + '<br/>';
    params.forEach(item => {
      result += `${item.marker} ${item.seriesName}: ${item.value}<br/>`;
    });
    return result;
  }
}

样式定制

基础样式

可以通过textStyle配置文本样式：

tooltip: {
  backgroundColor: 'rgba(50,50,50,0.7)',
  borderColor: '#333',
  borderWidth: 1,
  textStyle: {
    color: '#fff',
    fontSize: 14,
    fontWeight: 'bold'
  },
  padding: [10, 15]
}

自定义DOM结构

使用renderMode: 'richText'可以启用富文本模式：

tooltip: {
  renderMode: 'richText',
  rich: {
    title: {
      color: '#eee',
      fontSize: 18,
      padding: [0, 0, 5, 0]
    },
    value: {
      color: '#4efd54',
      fontWeight: 'bold'
    }
  },
  formatter: function(params) {
    return `{title|${params[0].name}}\n{value|${params[0].value}}`;
  }
}

位置控制

固定位置

通过position属性可以固定提示框位置：

tooltip: {
  position: [10, 10] // 相对于容器左上角的坐标
}

动态定位

使用函数形式实现智能定位：

tooltip: {
  position: function(pos, params, dom, rect, size) {
    // pos是鼠标位置
    // size.viewSize是容器大小
    return [pos[0], pos[1]];
  }
}

高级功能

多级提示

在树图等复杂图表中可以实现多级提示：

tooltip: {
  formatter: function(info) {
    const treePathInfo = info.treePathInfo;
    let result = '';
    for (let i = 0; i < treePathInfo.length; i++) {
      result += `${'→'.repeat(i)} ${treePathInfo[i].name}<br/>`;
    }
    return result;
  }
}

异步回调

结合axisPointer实现动态数据加载：

tooltip: {
  axisPointer: {
    type: 'shadow',
    snap: true,
    z: 1,
    label: {
      show: true,
      formatter: function(params) {
        return '正在加载...';
      }
    },
    handle: {
      show: true,
      size: 45,
      margin: 30
    }
  },
  formatter: function(params, ticket, callback) {
    // 模拟异步请求
    setTimeout(function() {
      callback(ticket, '异步数据:' + params[0].value);
    }, 1000);
    return '加载中...';
  }
}

性能优化

对于大数据量场景，可以启用appendToBody避免频繁重排：

tooltip: {
  appendToBody: true,
  confine: false,
  transitionDuration: 0 // 禁用动画提升性能
}

特殊图表适配

地图提示框

地图图表需要特殊处理geo区域：

tooltip: {
  trigger: 'item',
  formatter: function(params) {
    if (params.data) {
      return `${params.name}<br/>数据值: ${params.value[2]}`;
    }
    return params.name;
  }
}

日历图提示

日历图需要处理日期格式：

tooltip: {
  position: 'top',
  formatter: function(params) {
    const date = new Date(params.value[0]);
    return `${date.getFullYear()}-${date.getMonth()+1}-${date.getDate()}<br/>
            热度: ${params.value[1]}`;
  }
}

移动端适配

针对移动设备需要调整交互方式：

tooltip: {
  show: true,
  trigger: 'item',
  alwaysShowContent: false,
  showDelay: 0,
  hideDelay: 100,
  enterable: true,
  confine: true,
  extraCssText: 'max-width: 80%;' // 限制最大宽度
}

主题集成

与ECharts主题系统结合使用：

tooltip: {
  className: 'custom-tooltip-theme',
  textStyle: {
    fontFamily: 'Arial, sans-serif'
  }
}

对应的CSS样式：

.echarts-tooltip.custom-tooltip-theme {
  box-shadow: 0 0 10px rgba(0,0,0,0.3);
  border-radius: 4px;
}

动态更新

在数据更新时保持tooltip状态：

myChart.on('dataZoom', function() {
  const option = myChart.getOption();
  option.tooltip = {
    ...option.tooltip,
    backgroundColor: '#ff0' // 动态修改颜色
  };
  myChart.setOption(option);
});

无障碍访问

为提升可访问性可以添加ARIA属性：

tooltip: {
  aria: {
    show: true,
    description: '数据提示框，显示当前悬停项的详细信息'
  }
}