Tooltip 提示信息——VisActor/VChart 教程文档

Tooltip 提示信息是我们在使用 VChart 图表时，用以显示在图表不同元素上的附加信息，通过鼠标悬停操作展示出来。本教程主要讲解提示信息组件的相关概念以及组成，关于组件更加详细的配置及示例，详见配置项文档及示例页面。

在 VChart 图表中，Tooltip 提示信息主要由两部分组成：

标题（title）：显示当前鼠标悬停的数据分类或其他相关信息。
内容（content）：显示当前鼠标悬停的详细数据及其属性信息。

在 VChart 上我们根据 tooltip 的显示数据提供了两种类型的 tooltip，分别为图元 tooltip（'mark'）和维度项 tooltip（'dimension'）。其中图元（'mark'）指的是单独某一个数据对应的图形（如下图中堆积柱图中的一个小方块）。'dimension' 指的是当前鼠标所在区域的维度值（如 x 值）对应的一组数据（如下图中堆积柱图中堆叠在一起的一组数据）:

样式配置

通过 tooltip.style 属性，我们可以对 tooltip 进行样式配置。下面的代码示例展示了常见的 tooltip 面板的样式配置，如调整背景色、圆角、边框阴影等配置。

tooltip: {
    style: {
      panel: {
        /** 背景色 */
        backgroundColor: 'rgba(24,144,255, 0.1)',
        /** tooltip边框 */
        border: {
          color: '#6690F2',
          width: 2,
          /** 圆角 */
          radius: 4
        },
        /** tooltip阴影 */
        shadow: {
          blur: 10,
          spread: 2,
          color: '#6690F2'
        }
      }
    }
  }

格式化

标题格式化

有时我们需要对 Tooltip 的标题进行特定的显示格式，此时我们可以通过在对应类型的 tooltip 下的 title.value 属性进行配置，如果配置该属性为字符串，则显示为对应的常量文本。也可配置为函数回调：(datum: Datum) => string; 其中 datum 为 tooltip 当前行所默认对应的数据项。

标题格式化示例：

{
  tooltip: {
    // 配置 mark 图元的标题内容
    mark: {
      title: {
        value: '标题'
      }
    },
    // 配置 dimension 维度项的标题内容
    dimension: {
      title: {
        value: datum => datum.value
      }
    },
  }
}

2. 内容格式化

除了标题，我们同样也可以对 Tooltip 的内容进行格式化处理。与标题格式化类似，我们可以通过在对应类型的 tooltip 下的 content 属性进行配置，Tooltip 的每一条 content 由如下部分组成：

shape：数据项图形。
key：数据项名称。
value：数据项值。

当我们需要对内容进行格式化时，可以通过配置 key, value 属性进行，如果配置为字符串，则显示为对应的常量文本。也可配置为函数回调，也可配置为函数回调：(datum: Datum) => string; 其中 datum 为 tooltip 当前行所默认对应的数据项。

内容格式化示例：

{
  tooltip: {
    // 配置 mark 图元的内容
    mark: {
      content: {
        key: '数值',
        value: datum => datum.value
      }
    },
    // 配置 dimension 维度项的内容
    dimension: {
      content: {
        key: datum => datum.type,
        value: datum => datum.value
      }
    },
  }
}

自定义

当配置项无法满足 tooltip 的展示需求时，我们还提供了自定义 tooltip 的能力。可以通过配置 TooltipHandler 来覆盖默认 tooltip 展示逻辑。具体可以阅读 VChart 实例方法 setTooltipHandler 的使用。

  /**
   * 自定义 TooltipHandler。
   * @param tooltipHandler
   */
  setTooltipHandler: (tooltipHandler: ITooltipHandler) => void;

注意：

当给图表设置了自定义TooltipHandler后，内置的 tooltip 将不再起作用。
VChart 不感知、不托管自定义 tooltip 的渲染，请按照需要自行实现 tooltip 渲染，包括处理原始数据、tooltip 内容设计，以及根据项目环境创建组件并设置样式。
当图表删除时会调用当前TooltipHandler的release函数，请按照需要删除。
由于自定义TooltipHandler会覆盖内置 tooltip 逻辑，图表spec中的部分 tooltip 配置项便不再起作用。但以下配置项作用于所有自定义TooltipHandler：
- tooltip.visible
- tooltip.activeType
- tooltip.trigger
- tooltip.triggerOff

ITooltipHandler接口定义如下：

interface ITooltipHandler {
  /** 显示 tooltip，可以选择返回是否遇到异常 */
  showTooltip: (
    activeType: TooltipActiveType,
    data: TooltipData,
    params: TooltipHandlerParams
  ) => TooltipResult | null | undefined;

  /** 隐藏 tooltip */
  hideTooltip: (params: TooltipHandlerParams) => void;

  /** 释放 tooltip */
  release: () => void;
}

其中ITooltipHandler.showTooltip有三个参数，意义分别为：

activeType: 透出本次触发的 tooltip 类型，值为'mark'或'dimension'
data: 透出本次触发的 tooltip 原始数据
params: 透出本次触发的 tooltip 的鼠标事件

data参数的类型为TooltipData，类型定义为：

type TooltipData = IDimensionInfo[] | IDimensionData[];

如果用户触发了 mark tooltip，TooltipData 便为 IDimensionData[] 类型。IDimensionData的类型定义为：

interface IDimensionData {
  /** 图元上的原始数据（考虑到有多个图元的情况，实际为数组类型） */
  datum: Datum[];
  /** 图元所在的系列实例 */
  series: ISeries;
}

而如果用户触发了 dimension tooltip，TooltipData 便为 IDimensionInfo[] 类型。IDimensionInfo承载了鼠标所在整个维度项的信息，类型定义为：

interface IDimensionInfo {
  /** 维度项索引 */
  index?: number;
  /** 维度项标题 */
  value: string;
  /** 维度项所在轴 */
  axis?: AxisComponent;
  /** 维度项对应数据 */
  data: IDimensionData[];
}

用户可以选择使ITooltipHandler.showTooltip方法返回一个状态TooltipResult，用来表示 tooltip 是否成功显示（如果不返回，则默认当做成功）。这个返回值和缓存策略有关。TooltipResult是个枚举类型，定义为：

enum TooltipResult {
  /** tooltip 显示成功 */
  success = 0,
  /** tooltip 未成功显示 */
  failed = 1
}

ITooltipHandler.showTooltip方法的最后一个参数为params，其类型定义为：

type TooltipHandlerParams = (BaseEventParams | DimensionEventParams) & {
  changePositionOnly?: boolean;
};

其中暴露了一个很有用的参数：changePositionOnly，代表这个 tooltip 是否仅仅是上一个 tooltip 挪用了下位置，而数据相同。这个参数将帮助用户对 tooltip 渲染进行优化。

示例：在控制台打出用户鼠标 hover 的维度项标题、以及系列图元的填充颜色：

vchart.setTooltipHandler({
  showTooltip: (activeType, data, params) => {
    if (params.changePositionOnly) {
      return;
    }
    if (activeType === 'dimension' && data?.length) {
      console.log(data[0].value);
    } else if (activeType === 'mark') {
      const { datum, series } = data[0];
      const color = series.getSeriesStyle(datum[0])('fill');
      console.log(color);
    }
  }
});

也可参考另一个示例：