图表 - 工具提示

工具提示在图表项上提供额外的数据。

在所有图表组件中，您可以使用 tooltip={{...}} 传递 props 给工具提示。如果您正在使用组合，您可以添加 <ChartsTooltip /> 组件并直接传递 props。

工具提示触发器

工具提示可以通过两种事件触发

'item'—当用户鼠标悬停在图表上的某个项目上时，工具提示将显示有关此特定项目的数据。
'axis'—用户的鼠标位置与 x 轴的值相关联。工具提示将显示有关此特定 x 值处所有系列的数据。
'none'—禁用工具提示。

<BarChart {...barChartsParams} tooltip={{ trigger: 'axis' }} />
<BarChart {...barChartsParams} tooltip={{ trigger: 'item' }} />

<BarChart {...barChartsParams} tooltip={{ trigger: 'axis' }} />
<BarChart {...barChartsParams} tooltip={{ trigger: 'item' }} />

按 Enter 开始编辑

自定义

格式化

由于系列的 valueFormatter 属性，可以修改工具提示中呈现的数据格式。当工具提示由 'axis' 触发时，同样可以应用于 x 值。

这是一个演示，其中

时间轴的格式设置为仅显示年份
数值的格式设置为美元。

<LineChart
  {...lineChartsParams}
  xAxis={[{ data: years, scaleType: 'time', valueFormatter: yearFormatter }]}
  series={lineChartsParams.series.map((series) => ({
    ...series,
    valueFormatter: (v) => (v === null ? '' : currencyFormatter(v)),
  }))}
/>

<LineChart
  {...lineChartsParams}
  xAxis={[{ data: years, scaleType: 'time', valueFormatter: yearFormatter }]}
  series={lineChartsParams.series.map((series) => ({
    ...series,
    valueFormatter: (v) => (v === null ? '' : currencyFormatter(v)),
  }))}
/>

按 Enter 开始编辑

高级格式化

系列 valueFormatter 将上下文作为其第二个参数提供，其中包含一个 dataIndex 属性，您可以使用它来计算其他与数据相关的值。

在下面的演示中，您可以注意到我们使用 dataIndex 在工具提示中添加每个团队的排名。

<PieChart
  series={[
    {
      data: data.map((d) => ({ label: d.team, id: d.team, value: d.points })),
      valueFormatter: (v, { dataIndex }) => {
        const { rank } = data[dataIndex];
        return `has ${v.value} points and is ranked ${rank}.`;
      },
    },
  ]}
  {...otherProps}
/>

<PieChart
  series={[
    {
      data: data.map((d) => ({ label: d.team, id: d.team, value: d.points })),
      valueFormatter: (v, { dataIndex }) => {
        const { rank } = data[dataIndex];
        return `has ${v.value} points and is ranked ${rank}.`;
      },
    },
  ]}
  {...otherProps}
/>

按 Enter 开始编辑

坐标轴格式化器

要修改数据在坐标轴中的显示方式，请使用 valueFormatter 属性。

它的第二个参数是一个上下文，提供一个 location 属性，其值为 'tick' 或 'tooltip'。

在此演示中，您可以看到

国家/地区轴仅显示国家/地区代码
标签显示注释数据 Country: name (code)

<BarChart
  xAxis={[
    {
      scaleType: 'band',
      dataKey: 'code',
      valueFormatter: (code, context) =>
        context.location === 'tick'
          ? code
          : `Country: ${dataset.find((d) => d.code === code)?.name} (${code})`,
    },
  ]}
  {...chartParams}
/>

<BarChart
  xAxis={[
    {
      scaleType: 'band',
      dataKey: 'code',
      valueFormatter: (code, context) =>
        context.location === 'tick'
          ? code
          : `Country: ${dataset.find((d) => d.code === code)?.name} (${code})`,
    },
  ]}
  {...chartParams}
/>

按 Enter 开始编辑

标签格式化

工具提示内的标签文本也可以通过为系列的 label 属性提供函数来有条件地格式化。

<LineChart
  // ...
  series={[
    {
      data: [ ... ],
      label: (location) => location === 'tooltip' ? 'BR' : 'Brazil'
    }
  ]}
/>

隐藏值

您可以使用 xAxis props 中的 hideTooltip 隐藏轴值。它将从工具提示中删除显示 x 轴值的标题。

<LineChart
  // ...
  xAxis={[{ data: [ ... ], hideTooltip: true }]}
/>

覆盖内容

要修改工具提示内容，请使用 slots.itemContent 或 slots.axisContent。第一个在工具提示触发器设置为 "item" 时呈现。第二个在触发器设置为 "axis" 时呈现。

// With single component
<LineChart
  slots={{
    itemContent: CustomItemTooltip
  }}
/>

// With composition
<ChartContainer>
  // ...
  <Tooltip
    trigger='item'
    slots={{
      itemContent: CustomItemTooltip
    }}
  />
</ChartContainer>

组合

如果您正在使用组合，默认情况下，坐标轴将监听鼠标事件以获取其当前的 x/y 值。如果您不需要它，您可以使用 disableAxisListener prop 禁用这些监听器。

如果您正在使用轴高亮或您有一个由轴触发的工具提示，则需要这些监听器。

<ChartContainer {...} disableAxisListener>
  {/* ... */}
</ChartContainer>

覆盖内容

项目工具提示

您可以使用 useItemTooltip 创建自己的工具提示。此 Hook 返回有关用户当前正在交互的项目的信息。它包含

identifier：标识项目的对象。通常包含其系列类型、系列 ID 和数据索引。
color：用于显示项目的颜色。这包括颜色映射的影响。
label、value、formattedValue：为简化工具提示创建而计算的值。

要跟踪鼠标位置，您可以使用 useMouseTracker，或借助 useSvgRef 跟踪 SVG 上的事件。

轴工具提示

与上一节类似，您可以使用 useAxisTooltip 创建自己的工具提示。此 Hook 返回有关用户当前正在交互的轴以及相关系列的信息。它包含

identifier：标识轴的对象。通常包含其系列类型、系列 ID 和数据索引。
color：用于显示项目的颜色。这包括颜色映射的影响。
label、value、formattedValue：为简化工具提示创建而计算的值。

要跟踪鼠标位置，您可以使用 useMouseTracker，或借助 useSvgRef 跟踪 SVG 上的事件。

此演示展示了如何使用额外的 Hook（例如 useXAxis 或 useDrawingArea）来自定义工具提示位置的示例。

鼠标位置图表顶部条形图顶部

API

请参阅下面的文档，以获得此处提到的组件的所有可用 props 和类的完整参考。