提示信息（Tooltip）

概述

Tooltip 是图表交互的核心组件之一，用于动态展示数据点的详细信息，帮助用户快速理解图表中特定区域的数值、分类或其他维度信息。它能够在鼠标悬停、点击或移动到图表中的某个元素（如柱状图中的柱子、折线图中的数据点）时，动态显示相关的数据信息。

• 显示详细信息：Tooltip 可以显示有关数据点的详细信息，例如具体数值、百分比或其他相关属性。这有助于用户更深入地了解数据。
• 提高可读性：在复杂的可视化中，Tooltip 可以帮助用户更容易地识别和理解数据点。例如，在散点图中，当数据点密集时，Tooltip 可以显示特定点的详细信息，而无需将鼠标悬停在每个点上。
• 增强交互性：Tooltip 可以增强可视化的交互性。用户可以通过悬停或点击数据点来查看更多信息，这使得可视化更加动态和有趣。
• 突出显示关键信息：Tooltip 可以用来突出显示关键信息。例如，在时间序列图中，您可以使用 Tooltip 显示特定时间点的重要事件或突变。
• 支持多种触发方式：可以通过鼠标悬停（hover）、点击（click）、触摸（touch）等事件触发显示。

构成元素

使用方式

chart.options({
  type: 'interval',
  tooltip: {
    title: 'name', // 标题
    items: ['genre'], // 数据项
  },
});

并且结合 view.interaction.tooltip 去配置提示信息的渲染和额外配置。

chart.options({
  type: 'view',
  interaction: {
    tooltip: { series: true },
  },
});

当该视图中只有一个标记的时候，通过 mark.interaction.tooltip 配置提示信息的渲染和额外配置也是可以的。

chart.options({
  type: 'line',
  interaction: {
    tooltip: { series: true },
  },
});

如果希望不展示该 tooltip 的提示信息，可以通过下面的配置关闭。

chart.options({
  type: 'interval',
  tooltip: false,
});

如果希望图表没有提示信息交互，可以通过 chart.interaction 实现。

chart.options({
  type: 'view',
  interaction: { tooltip: false },
});

尝试一下

import { Chart } from '@antv/g2';

const chart = new Chart({
  container: 'container',
});

chart.options({
  type: 'line',
  data: {
    type: 'fetch',
    value: 'https://assets.antv.antgroup.com/g2/indices.json',
  },
  transform: [{ type: 'normalizeY', basis: 'first', groupBy: 'color' }],
  encode: { x: (d) => new Date(d.Date), y: 'Close', color: 'Symbol' },
  axis: { y: { title: '↑ Change in price (%)' } },
  tooltip: {
    title: (d) => new Date(d.Date).toUTCString(),
    items: [
      (d, i, data, column) => ({
        name: 'Close',
        value: column.y.value[i].toFixed(1),
      }),
    ],
  },
  labels: [{ text: 'Symbol', selector: 'last', fontSize: 10 }],
});

chart.render();

配置项

配置项分为两个部分

• tooltip 是 G2 中用于展示数据点的详细信息的一个 UI 组件。当用户将鼠标悬停在图表的某个数据点上时，tooltip 会显示该数据点的相关信息，比如坐标值、度量值等。

• interaction.tooltip 是 G2 的交互机制的一部分，属于 interaction（交互）模块。它是一种内置的交互行为，用于增强工具提示的功能，特别是在某些特定的交互场景下（如动态显示或隐藏工具提示）。

tooltip 和 interaction.tooltip 中的 tooltip 是两个不同维度的配置，但容易混淆。以下是它们的核心区别:

tooltip

title

title是一个用于显示当前悬停数据点的 主标题 的字段，通常用于表示数据点所属的分类或上下文信息。

title可以直接写入一个固定显示的字符串，或者一个方法从data中动态获取标题

chart.options({
  type: 'interval',
  tooltip: {
    title: (d) => (d.sold > 150 ? 'high' : 'low'), // 设置 title
  },
});

在不需要自定义 title 的时候，可以直接声明 tooltip 为一个数组，此时的 title 将会使用默认配置：

chart.options({
  type: 'interval',
  tooltip: ['genre', 'sold'],
});

其中完整的 title 结构如下：

• 字段

它们的值（value）可以通过来自原始数据，通过字符串或者 title.field 指定。

chart.options({
  tooltip: {
    title: 'sold',
    items: ['genre'],
  },
});

// 等价于
chart.options({
  tooltip: {
    title: { field: 'sold' },
    items: [{ field: 'genre' }],
  },
});

• 通道

它们的值（value）可以来自通道值，通过 title.channel 指定，常常用于使用 mark.transform 生成新通道的图表。

chart.options({
  tooltip: {
    title: { channel: 'x' },
    items: [{ channel: 'y' }],
  },
});

• 格式化

可以通过 title.valueFormatter 去指定 title 值（value）的展示，title.valueFormatter 可以是一个函数，也可以一个 d3-format 支持的字符串。

chart.options({
  tooltip: {
    title: { field: 'sold', valueFormatter: (sold) => sold.toUpperCase() },
    items: [{ channel: 'y', valueFormatter: '.0%' }],
  },
});

• 个性化配置

当然对于 title 还提供了回调去获得最大的个性化配置能力。

chart.options({
  tooltip: {
    title: (datum, index, data, column) => ({
      value: `<span style="color: #00ff00; font-style: italic;">${datum.letter}</span>`,
      custom: '...',
    }),
    items: [
      (datum, index, data, column) => ({
        color: datum.sold > 150 ? 'red' : 'blue', // 指定 item 的颜色
        name: index === 0 ? datum.genre : `${datum.genre} ${data[index].genre}`, // 指定 item 的名字
        value: column.y.value[index], // 使用 y 通道的值
        custom: '...',
      }),
    ],
  },
});

items 返回值可用作 interaction.tooltip.render 的入参，您可以设置一些自定义参数。详见自定义渲染内容

复合图形配置

复合图形在配置tooltip.title 时需要分别配置节点与弦

({
  tooltip: {
    nodeTitle: (d) => d.key,
    linkTitle: (d) => 'link',
  },
});

items

items 是 tooltip 配置中的一个关键属性，items 是一个数组，表示工具提示中每一项的内容。每一项通常对应于一个数据字段或一个图形元素（例如柱状图的一根柱子、折线图的一个点等）。通过自定义 items，可以灵活地控制工具提示的显示内容，包括名称、值、颜色等信息。

其中完整的 title 结构如下：

items 的 value、channel、valueFormatter属性的配置方式与title一致，详细配置请参考title

名称

通过name可以便捷的修改tooltip中item的名字，通过channel来匹配图标中对应的条目。

chart.options({
  tooltip: {
    items: [
      { name: '张三', channel: 'y1' },
      { name: '李四', channel: 'y2' },
    ],
  },
});

颜色

tooltip会自动根据图标内容分配tooltip item的颜色，但是实际应用中，可能需要根据一些规则来指定某些颜色，此时就可以通过color属性来配置。通过channel来匹配图标中对应的条目。

chart.options({
  tooltip: {
    items: [
      { color: 'pink', channel: 'y1' },
      { color: '#f00', channel: 'y2' },
    ],
  },
});

复合图形配置

复合图形在配置tooltip.items 时需要分别配置节点与弦

({
  tooltip: {
    nodeItems: [
      (datum, index, data, column) => {
        return {
          color: 'red', // 指定 item 的颜色
          name: '节点', // 指定 item 的名字
          value: d.key, // 使用 y 通道的值
          content: '节点自定义属性',
        };
      },
    ],
    linkItems: [
      (datum, index, data, column) => {
        return {
          color: 'red', // 指定 item 的颜色
          name: '连接线', // 指定 item 的名字
          value: `${d.source.key}-${d.target.key}`, // 使用 y 通道的值
          content: '连接线自定义属性',
        };
      },
    ],
  },
});

interaction.tooltip

crosshairs

crosshairs 是提示框（Tooltip）的辅助线功能，用于在图表中标记当前数据点的精确位置，主要用于连续图形，例如折线图、面积图。通常以横向或纵向的参考线形式呈现，帮助用户更直观地定位数据。

另外，通过前缀crosshairsX 和 crosshairsY 设置样式的优先级比 crosshairs高，会覆盖后者。

chart.options({
  interaction: {
    legendFilter: false,
    elementPointMove: true,
    tooltip: {
      crosshairs: true, // 启用十字辅助线
      crosshairsStroke: 'red', // 辅助线颜色为红色
      crosshairsYStroke: 'yellow', // 垂直方向辅助线颜色单独设置为黄色
      crosshairsLineDash: [4, 4], // 辅助线为虚线样式
      markerType: 'hollow', // 提示框标记点为空心
    },
  },
});

marker

chart.options({
  interaction: {
    tooltip: {
      marker: true,
      markerType: 'hollow', // 提示框标记点为空心
      markerStroke: 'yellow',
      markerLineWidth: 2,
      markerLineDash: [4, 4],
    },
  },
});

设置样式

tooltip 的 cssStyle 配置项允许通过 CSS 样式直接自定义提示框的外观， 可快速实现提示框的视觉定制，适配不同主题或交互场景需求。

import { Chart } from '@antv/g2';

const chart = new Chart({
  container: 'container',
});

chart.options({
  type: 'interval',
  data: {
    type: 'fetch',
    value:
      'https://gw.alipayobjects.com/os/bmw-prod/f129b517-158d-41a9-83a3-3294d639b39e.csv',
    format: 'csv',
  },
  encode: {
    x: 'state',
    y: 'population',
    color: 'age',
  },
  transform: [
    { type: 'sortX', by: 'y', reverse: true, reducer: 'sum', slice: 6 },
    { type: 'dodgeX' },
  ],
  legend: false,
  interaction: {
    tooltip: {
      shared: true,
      mount: 'body',
      css: {
        '.g2-tooltip': {
          background: '#eee',
          'border-radius': ' 0.25em !important',
        },
        '.g2-tooltip-title': {
          'font-size': '20px',
          'font-weight': 'bold',
          'padding-bottom': '0.25em',
        },
        '.g2-tooltip-list-item': {
          background: '#ccc',
          padding: '0.25em',
          margin: '0.25em',
          'border-radius': '0.25em',
        },
        '.g2-tooltip-list-item-name-label': {
          'font-weight': 'bold',
          'font-size': '16px',
        },
        'g2-tooltip-list-item-marker': {
          'border-radius': '0.25em',
          width: '15px',
          height: '15px',
        },
        '.g2-tooltip-list-item-value': {
          'font-weight': 'bold',
          'font-size': '16px',
        },
      },
    },
  },
});

chart.render();

尝试一下

import { Chart } from '@antv/g2';

const chart = new Chart({
  container: 'container',
});

chart.options({
  type: 'interval',
  data: {
    type: 'fetch',
    value:
      'https://gw.alipayobjects.com/os/bmw-prod/f129b517-158d-41a9-83a3-3294d639b39e.csv',
    format: 'csv',
  },
  transform: [{ type: 'sortX', by: 'y', reverse: true, slice: 6 }, { type: 'dodgeX' }],
  encode: { x: 'state', y: 'population', color: 'age' },
  scale: { y: { nice: true } },
  axis: { y: { labelFormatter: '~s' } },
  interaction: {
    tooltip: {
      shared: true,
      css: {
        '.g2-tooltip': {
          background: '#eee',
          'border-radius': ' 0.25em !important',
        },
        '.g2-tooltip-title': {
          'font-size': '20px',
          'font-weight': 'bold',
          'padding-bottom': '0.25em',
        },
        '.g2-tooltip-list-item': {
          background: '#ccc',
          padding: '0.25em',
          margin: '0.25em',
          'border-radius': '0.25em',
        },
        '.g2-tooltip-list-item-name-label': {
          'font-weight': 'bold',
          'font-size': '16px',
        },
        'g2-tooltip-list-item-marker': {
          'border-radius': '0.25em',
          width: '15px',
          height: '15px',
        },
        '.g2-tooltip-list-item-value': {
          'font-weight': 'bold',
          'font-size': '16px',
        },
      },
    },
  },
});

chart.render();

自定义渲染内容

有时候内置的 Tooltip 无法满足需求，这时候可以通过 mark.interaction.tooltip.render 或者 view.interaction.tooltip.render 的 render 函数来渲染自定义的提示。

该 render 函数接受事件对象 event 和提示数据 tooltipData，返回一个 string 或者 DOM 对象。其中 event 是 @antv/g 抛出的鼠标对象，tooltipData 是通过 mark.tooltip 声明的 title 和 items 数据。如果返回值是一个 string，那么会作为 tooltip 容器的 innerHTML，否则会挂载该返回值。一个提示的 render 函数的定义大概如下：

function render(event, tooltipData) {
  const { title, items } = tooltipData;
  return `<div></div>`;
}

下面是一个简单的例子：

import { Chart } from '@antv/g2';

const chart = new Chart({
  container: 'container',
});

chart.options({
  type: 'interval',
  data: {
    type: 'fetch',
    value:
      'https://gw.alipayobjects.com/os/bmw-prod/fb9db6b7-23a5-4c23-bbef-c54a55fee580.csv',
  },
  transform: [{ type: 'sortX', by: 'y', reverse: true }],
  encode: { x: 'letter', y: 'frequency' },
  interaction: {
    tooltip: {
      // render 回调方法返回一个innerHTML 或者 DOM
      render: (event, { title, items }) => `<div>
      <h3 style="padding:0;margin:0">${title}</h3>
      <ul>${items.map(
        (d) =>
          `<li><span style="color: ${d.color}">${d.name}</span> ${d.value}</li>`,
      )}</ul>
      </div>`,
    },
  },
});

chart.render();

事件

chart.on() 方法将指定的监听器注册到 chart 上，当该对象触发指定的事件时，指定的回调函数就会被执行。

以下是如何配置配置 tooltip 显示隐藏事件的示例：

chart.on('tooltip:show', (event) => {
  console.log(event.data.data);
});

chart.on('tooltip:hide', () => {
  console.log('hide');
});

尝试一下

/**
 * A recreation of this demo: https://vega.github.io/vega-lite/examples/layer_histogram_global_mean.html
 */
import { Chart } from '@antv/g2';

const chart = new Chart({
  container: 'container',
  autoFit: true,
});

chart.options({
  data: {
    type: 'fetch',
    value: 'https://assets.antv.antgroup.com/g2/movies.json',
    transform: [
      {
        type: 'filter',
        callback: (d) => d['IMDB Rating'] > 0,
      },
    ],
  },
  type: 'view',
  children: [
    {
      type: 'rect',
      transform: [{ type: 'binX', y: 'count', thresholds: 9 }],
      encode: { x: 'IMDB Rating' },
      scale: { y: { domainMax: 1000 } },
      style: { inset: 1 },
    },
    {
      type: 'lineX',
      transform: [{ type: 'groupColor', x: 'mean' }], // groupColor 为分组并对指定的通道进行聚合，可以理解为把数据通过 x 通道的数据 取平均值(mean) 变更为一条数据。
      encode: { x: 'IMDB Rating' },
      style: {
        stroke: '#F4664A',
        strokeOpacity: 1,
        lineWidth: 2,
        lineDash: [4, 4],
      },
    },
  ],
});

chart.render();

示例

title

mark.tooltip({
  title: 'name', // 字段
});

mark.tooltip({
  title: (d) => (d.value > 100 ? d.name : d.age), // transform
});

item

// 单个字段
mark.tooltip('a');
mark.tooltip({ field: 'a' });

// 单个通道
mark.tooltip({ channel: 'y' });

// transform
mark.tooltip((d) => (d.value > 100 ? d.name : d.age));

// 格式化
mark.tooltip({ channel: 'y', valueFormatter: (d) => d.toFixed(1) });

// d3-format 支持的字符
// https://github.com/d3/d3-format
mark.tooltip({ channel: 'y', valueFormatter: '~s' });

// 完整信息
mark.tooltip({ name: 'name', color: 'red', value: 'color' });

// 回调
mark.tooltip(
  (
    d, // 每一个数据项
    index, // 索引
    data, // 完整数据
    column, // 通道
  ) => ({
    value: `${column.y.value[index]} - ${column.y1.value[index]}`,
  }),
);

// 多个 item
mark.tooltip({ channel: 'y' }).tooltip({ channel: 'x' });

title + item

mark.tooltip({
  title: 'a',
  items: [{ channel: 'x' }, { channel: 'y' }],
});

过滤空值数据

当数据中存在 null 或 undefined 值时，可以通过 interaction.tooltip.filter 来过滤掉这些无效数据，避免在 tooltip 中显示。

import { Chart } from '@antv/g2';

const chart = new Chart({
  container: 'container',
});

chart.options({
  type: 'view',
  data: [
    { month: 'Jan', city: 'Tokyo', temperature: null },
    { month: 'Jan', city: 'London', temperature: 3.9 },
    { month: 'Feb', city: 'Tokyo', temperature: 8 },
    { month: 'Feb', city: 'London', temperature: 4.2 },
    { month: 'Mar', city: 'Tokyo', temperature: 9.5 },
    { month: 'Mar', city: 'London', temperature: 5.7 },
  ],
  encode: { x: 'month', y: 'temperature', color: 'city' },
  // 添加interaction配置来过滤null值
  interaction: {
    tooltip: {
      filter: (d) => d.value !== null && d.value !== undefined,
    },
  },
  children: [
    {
      type: 'line',
      encode: { shape: 'smooth' },
      tooltip: {
        items: [{ channel: 'y' }],
      },
    },
    { type: 'point', encode: { shape: 'point' }, tooltip: false },
  ],
});

chart.render();

更多过滤选项：

// 只过滤null值
filter: (d) => d.value !== null;

// 过滤null、undefined和空字符串
filter: (d) => d.value !== null && d.value !== undefined && d.value !== '';

// 过滤所有"假值"（null, undefined, 0, false, ''等）
filter: (d) => Boolean(d.value);

// 按name过滤特定字段（比如只过滤temperature字段的null值）
filter: (d) =>
  d.name !== 'temperature' || (d.value !== null && d.value !== undefined);

怎么将 data 中额外的数据作为自定义 render 函数的参数

render 函数提供了强大的个性化配置能力，通过对tooltip.render函数返回参数的配置，自定义interaction.tooltip.render的入参

chart.options({
  tooltip: {
    items: [
      (datum, index, data, column) => ({
        color: datum.sold > 150 ? 'red' : 'blue', // 指定 item 的颜色
        name: index === 0 ? datum.genre : `${datum.genre} ${data[index].genre}`, // 指定 item 的名字
        value: column.y.value[index], // 使用 y 通道的值
        custom1: '自定义参数1',
        custom2: '自定义参数2',
      }),
    ],
  },
  interaction: {
    tooltip: {
      // render 回调方法返回一个innerHTML 或者 DOM
      render: (event, { title, items }) => {
        return `<div>
          <h3 style="padding:0;margin:0">${title}</h3>
          <ul>${items.map(
            ({ color, name, value, custom1, custom2 }) => '...',
          )}</ul>
        </div>`;
      },
    },
  },
});

手动控制展示/隐藏

对于 Interval、Point 等非系列 Mark，控制展示的方式如下：

// 条形图、点图等
chart.options({
  type: 'interval',
  data: [
    { genre: 'Sports', sold: 275 },
    { genre: 'Strategy', sold: 115 },
    { genre: 'Action', sold: 120 },
    { genre: 'Shooter', sold: 350 },
    { genre: 'Other', sold: 150 },
  ],
  encode: { x: 'genre', y: 'sold', color: 'genre' },
});

chart.render().then((chart) =>
  chart.emit('tooltip:show', {
    offsetX: 10, // 相对于 plot 区域的位置
    offsetX: 20, // 相对于 plot 区域的位置
    data: {
      data: { genre: 'Sports' }, // 会找从原始数据里面找到匹配的数据
    },
  }),
);

对于 Line、Area 等系列 Mark，控制展示的方式如下：

chart.options({
  type: 'line',
  data: { type: 'fetch', value: 'data/aapl.csv' },
  encode: { x: 'date', y: 'close' },
});

// 根据数据拾取
chart.render((chart) =>
  chart.emit('tooltip:show', {
    data: {
      data: { x: new Date('2010-11-16') },
    },
  }),
);

// 根据像素拾取
chart.render((chart) =>
  chart.emit('tooltip:show', {
    offsetX: 200,
    offsetY: 200,
  }),
);

隐藏的方式如下：

chart.emit('tooltip:hide');

开始/禁止交互

chart.emit('tooltip:disable'); // 禁用 tooltip
chart.emit('tooltip:enable'); // 启用交互

设置十字辅助线

默认情况下，crosshairsY是开启的，crosshairsX是关闭的，所以如果要开启十字辅助线，有以下两种方式。

1. 设置crosshairs为true。

chart.options({
  interaction: {
    tooltip: {
      crosshairs: true, // 开启十字辅助线
      crosshairsXStroke: 'red', // 设置 X 轴辅助线颜色为'red'
      crosshairsYStroke: 'blue', // 设置 Y 轴辅助线颜色为'blue'
    },
  },
});

2. 设置crosshairsX为true。

chart.options({
  interaction: {
    tooltip: {
      crosshairsX: true, // 开启crosshairsX辅助线
      crosshairsXStroke: 'red', // 设置 X 轴辅助线颜色为'red'
      crosshairsYStroke: 'blue', // 设置 Y 轴辅助线颜色为'blue'
    },
  },
});

crosshairsX的优先级大于crosshairs的优先级。

设置提示点为空心圆

chart.options({
  interaction: {
    tooltip: {
      markerType: 'hollow', // 设置提示点的样式为空心圆
    },
  },
});

桑基图这种复合图形怎么使用 data 中的补充属性实现自定义 tooltip 的展示？

和一般Mark自定义tooltip交互的方法类似，先在图形的tooltip.render里返回自定义属性，然后在interaction.render里使用。

({
  type: 'sankey',
  data: {
    value: {
      nodes: [
        { id: 'a', key: '首页', des: '节点自定义属性' },
        { id: 'b', key: '页面1', des: '节点自定义属性' },
        { id: 'b_1', key: '页面1', des: '节点自定义属性' },
        { id: 'c', key: '页面2', des: '节点自定义属性' },
        { id: 'c_1', key: '页面2', des: '节点自定义属性' },
        { id: 'd', key: '页面3', des: '节点自定义属性' },
        { id: 'd_1', key: '页面3', des: '节点自定义属性' },
      ],
      links: [
        { source: 'a', target: 'b', value: 100 },
        { source: 'b', target: 'c', value: 80 },
        { source: 'b', target: 'd', value: 20 },
        { source: 'c', target: 'b_1', value: 80 },
        { source: 'b_1', target: 'c_1', value: 40 },
        { source: 'b_1', target: 'd_1', value: 40 },
      ],
    },
    transform: [
      {
        type: 'custom',
        callback: (data) => ({
          nodes: data.nodes,
          links: data.links,
        }),
      },
    ],
  },
  tooltip: {
    nodeItems: [
      (datum, index, data, column) => {
        return {
          content: d.des,
        };
        z;
      },
    ],
    linkItems: [
      (datum, index, data, column) => {
        return {
          color: 'red', // 指定 item 的颜色
          name: '连接线', // 指定 item 的名字
          value: `${d.source.key}-${d.target.key}`, // 使用 y 通道的值
          content: '连接线自定义属性',
        };
      },
    ],
  },
  layout: {
    nodeId: (d) => d.id,
    nodeAlign: 'center',
    nodePadding: 0.03,
    iterations: 25,
  },
  style: {
    labelSpacing: 3,
    labelFontWeight: 'bold',
    linkFillOpacity: 0.2,
    linkFill: '#3F96FF',
  },
  interaction: {
    tooltip: {
      render: (e, { items, title }) => {
        return `<div>${items[0].content}</div>`;
      },
    },
  },
});