圖表 - 工具提示

工具提示在圖表項目上提供額外資料。

在所有圖表組件中，您可以使用 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 和類別的完整參考。