通用配置

为了更好地使用 Ant Design Charts 进行数据可视化，我们需要了解 Ant Design Charts 图表的组成以及相关概念。

图表组件

下面是一个基本的 Ant Design Charts 图表，图表由 组件（Component） 和 标记（Mark） 组成。

需要特别注意的是，Ant Design Charts 5.0 中不再需要单独配置标注（Annotation），标注也是一种标记，或者说某些标记也也可以用来做标注，比如 Text，Image， Line 等标记。

标题 title

用于一句话概要说明图表要展示的数据，图表的标题是比较常用的组件，支持标题和副标题，以及他们的样式和位置设置。

查看 Title 教程获取更多信息。

坐标轴 axis

绘制坐标轴，目前支持直角坐标系坐标轴与极坐标系坐标轴。

每个坐标轴由坐标轴线（line）、刻度（tick）、刻度值（label）、标题（title）以及网格线（grid）组成。

查看 Axis 教程获取更多信息。

图例 legend

绘制图例，Ant Design Charts 提供了两种图例类型：分类图例（Category Legend）和连续图例（Continuous Legend），分别用于展示分类数据和连续数据。

查看 Legend 教程获取更多信息。

滚动条 scrollbar

滚动条（scrollbar）是一个交互组件，当显示区域大小不足以容纳全部信息时，可以将超出部分隐藏，并通过滚动条的垂直或横向滑动来显示出被隐藏部分。

内容是否超出显示区域取决于内容的多少以及显示区域的尺寸，当需要显示的内容在纵向方向上超过显示区域的大小时，应当使用垂直滚动条以控制显示的部分，横向滚动条同理。

查看 Scrollbar 教程获取更多信息。

缩略轴 slider

缩略轴（slider）是一种辅助看数据的组件，它将大量数据浓缩到一个轴上，既可以缩小宏观看数据全貌，又可以放大微观看数据的片段，同时还可以拖拽观察数据在一定区间内的演变。

缩略轴是值域数据的浓缩，它跟位置通道 x, y 对应的比例尺的类型息息相关。一般来说时间类型上使用缩略轴的频率高，连续轴使用缩略轴频次低、分类轴几乎不会使用到缩略轴。

查看 Slider 教程获取更多信息。

当鼠标悬停在某个点上时，会以提示框的形式显示当前点对应的数据的信息，比如该点的值，数据单位等。数据提示框内提示的信息还可以通过格式化函数动态指定。

查看 Tooltip 教程获取更多信息。

数据标签 label

Ant Design Charts 中数据标签（Label）是给图表添加标注的手段之一。

查看 Label 教程获取更多信息。

图表布局

使用方式

不管是单视图图表还是多视图图表，布局信息（图表宽高等）都可以在选项顶层进行指定。

const markLevel = {
  width: 640,
  height: 180,
  margin: 10,
};

const viewLevel = {
  type: 'view',
  width: 640,
  height: 180,
  margin: 10,
  // ...
};

const compositionLevel = {
  type: 'spaceFlex',
  width: 640,
  height: 180,
  margin: 10,
};

同时，也可以在初始化 Chart 对象的时候指定：

也可以通过 node.attr 指定：

{
  "attr": {
    "margin": 20,
    "padding": 10
  }
}

视图模型

在 Ant Design Charts 中，视图模型 用于定义图表视图的划分方式，根据划分生成的不同区域可以绘制不同的内容，并通过相应选项进行配置。可以将视图简单理解为一个独立的图表。Ant Design Charts 的视图模型结构如下：

视图区域（View Area）：表示图表的整体视图区域。在设置图表的宽度和高度时，生效的范围即为视图区域的宽度和高度。视图区域与绘制区域之间的部分称为 外边距范围，该区域的大小可通过配置 margin 属性进行调整，通常用于设置固定组件（如坐标轴、图例等）与边界的距离。
绘制区域（Plot Area）：表示图表的绘制区域。绘制区域与主区域之间的部分称为 内边距范围，该区域的大小可通过配置 padding 属性进行调整，通常用于绘制图表组件，例如title、legend、axis等。
主区域（Main Area）：表示图表内容绘制的主要区域。主区域与内容区域之间的部分称为 呼吸范围，该区域的大小可通过配置 inset 属性进行调整，用于制造组件和标记（图形元素）的间距，从而防止重叠，对于散点图尤其有用。
内容区域（Content Area）：表示标记绘制的内容区域。主要用于绘制标记（图形元素）。

其中内容区域的大小由以下的公式得到：

const contentWidth = width - paddingLeft - paddingRight - marginLeft - marginRight - insetLeft - insetRight;

const contentHeight = height - paddingTop - paddingBottom - marginTop - marginBottom - insetTop - insetBottom;

布局算法

Ant Design Charts 在内部自己实现了一套布局算法，负责协调外边距（ margin ）、内边距（ padding ）、呼吸范围宽度（ inset ）等布局参数的计算，确保坐标轴、图例等组件在图表容器中合理布局。

动态计算

也许你曾经有过疑惑，为什么在配置里手动声明 padding 为 0，图表的 x 轴显示不全了。要回答这个问题，需要深入探究 Ant Design Charts 布局算法里动态计算的部分。

在 Ant Design Charts 的布局算法中，首先会获取所有传入的 padding、margin、inset属性，如果没有设置，padding（包括 paddingTop、paddingLeft 等）会被默认赋值为 auto，margin 会被默认赋值为 16，而 inset 会被默认赋值为 0。接下来将图表组件按照位置进行分组，方便后续布局计算。

以 position = 'top' 为例，如果配置了明确的 paddingTop 时，不会触发动态计算 paddingTop 的逻辑，此时对于未定义 size 的组件，使用内部定义的默认尺寸 defaultSize；对于分组（group）组件，递归执行上述操作，然后取最大的子组件尺寸作为父组件的尺寸；如果组件中包括坐标轴（axis）组件且未显式设置 labelAutoHide，设置 labelAutoHide 为 true，自动隐藏坐标轴标签以避免溢出。

如果没有配置 paddingTop，则会触发动态计算的逻辑，根据组件的实际尺寸累加边距（crossPadding 默认为 12），得出最后的实际paddingTop 大小。

要回答最初的问题：在 Ant Design Charts 中，内边距范围（ padding ）用于为图表组件预留展示空间。如果手动将 padding 设置为 0 ，会关闭内部的自适应计算逻辑，从而可能导致图表组件显示不完整。因此，当需要个性化配置时，应确保为组件预留足够的空间；否则，建议使用默认的自适应逻辑来避免显示问题。

防挤压机制

Ant Design Charts 内部对于图表显示区域设置了一个兜底机制，当视图中存在标记元素（如line、interval等），触发防挤压机制，来确保图表的主区域（Main Area）最小占比 1/4 。以水平方向为例，假设绘制区域的大小为 plotWidth，如果 plotWidth 减去动态计算后的左内边距 pl0 和右内边距 pr0 后小于 plotWidth * 1/4 时，会优先保证主区域大小为 plotWidth * 1/4，将内边距等比例缩小，当用户指定 paddingLeft 时会动态计算 paddingRight 的大小，按比例分配剩余空间，尽量避免左右外边距同时设置为固定值，可能会导致自适应算法失效。垂直方向的计算规则同理。

配置项

属性	描述	类型	默认值
autoFit	开启后图表的宽高和容器保持一致	boolean	false
width	设置图表的宽度	number	`640`
height	设置图表的高度	number	`480`
viewStyle	设置图表的视图样式	viewStyle	详见 viewStyle
margin	设置外边距四个方向的值，优先级别比分别设置低	number	`16`
marginLeft	设置左外边距值	number	`16`
marginTop	设置上外边距值	number	`16`
marginRight	设置右外边距值	number	`16`
marginBottom	设置下外边距值	number	`16`
padding	设置内边距四个方向的值，优先级别比分别设置低	number	`auto`
paddingLeft	设置左内边距值	number	`auto`
paddingTop	设置上内边距值	number	`auto`
paddingRight	设置右内边距值	number	`auto`
paddingBottom	设置下内边距值	number	`auto`
inset	设置呼吸范围四个方向的值，优先级别比分别设置低	number	`0`
insetLeft	设置左呼吸范围宽度	number	`0`
insetTop	设置上呼吸范围宽度	number	`0`
insetRight	设置右呼吸范围宽度	number	`0`
insetBottom	设置下呼吸范围宽度	number	`0`

autoFit

如果希望图表的宽高和容器保持一致，那么可以将 options.autoFit 设置为 true，其优先级比指定宽高高。

viewStyle

配置图表的视图样式。

属性	描述	类型	默认值
view	配置视图区域的样式	view	详见 view
plot	配置绘制区域的样式	plot	详见 plot
main	配置主区域的样式	main	详见 main
content	配置内容区域的样式	content	详见 content

view

配置图表的视图区域的样式。

属性	描述	类型	默认值
viewRadius	图表的视图区域的四个圆角半径大小	number	`0`
viewFill	图表的视图区域填充颜色	string	-
viewFillOpacity	图表的视图区域填充透明度	number	-
viewStroke	图表的视图区域描边颜色	string	-
viewStrokeOpacity	图表的视图区域描边透明度	number	-
viewLineWidth	图表的视图区域描边宽度	number	-
viewLineDash	图表的视图区域描边虚线配置	[number,number]	-
viewOpacity	图表的视图区域整体透明度	number	-
viewShadowColor	图表的视图区域阴影颜色	string	-
viewShadowBlur	图表的视图区域阴影模糊系数	number	-
viewShadowOffsetX	图表的视图区域阴影水平偏移	number	-
viewShadowOffsetY	图表的视图区域阴影垂直偏移	number	-
viewCursor	图表的视图区域鼠标样式	string	`default`

plot

配置图表的绘制区域的样式。

属性	描述	类型	默认值
plotRadius	图表的绘制区域的四个圆角半径大小	number	`0`
plotFill	图表的绘制区域填充颜色	string	-
plotFillOpacity	图表的绘制区域填充透明度	number	-
plotStroke	图表的绘制区域描边颜色	string	-
plotStrokeOpacity	图表的绘制区域描边透明度	number	-
plotLineWidth	图表的绘制区域描边宽度	number	-
plotLineDash	图表的绘制区域描边虚线配置	[number,number]	-
plotOpacity	图表的绘制区域整体透明度	number	-
plotShadowColor	图表的绘制区域阴影颜色	string	-
plotShadowBlur	图表的绘制区域阴影模糊系数	number	-
plotShadowOffsetX	图表的绘制区域阴影水平偏移	number	-
plotShadowOffsetY	图表的绘制区域阴影垂直偏移	number	-
plotCursor	图表的绘制区域鼠标样式	string	`default`

main

配置图表的主区域的样式。

属性	描述	类型	默认值
mainRadius	图表的主区域的四个圆角半径大小	number	`0`
mainFill	图表的主区域填充颜色	string	-
mainFillOpacity	图表的主区域填充透明度	number	-
mainStroke	图表的主区域描边颜色	string	-
mainStrokeOpacity	图表的主区域描边透明度	number	-
mainLineWidth	图表的主区域描边宽度	number	-
mainLineDash	图表的主区域描边虚线配置	[number,number]	-
mainOpacity	图表的主区域整体透明度	number	-
mainShadowColor	图表的主区域阴影颜色	string	-
mainShadowBlur	图表的主区域阴影模糊系数	number	-
mainShadowOffsetX	图表的主区域阴影水平偏移	number	-
mainShadowOffsetY	图表的主区域阴影垂直偏移	number	-
mainCursor	图表的主区域鼠标样式	string	`default`

content

配置图表的内容区域的样式。

属性	描述	类型	默认值
contentRadius	图表的内容区域的四个圆角半径大小	number	`0`
contentFill	图表的内容区域填充颜色	string	-
contentFillOpacity	图表的内容区域填充透明度	number	-
contentStroke	图表的内容区域描边颜色	string	-
contentStrokeOpacity	图表的内容区域描边透明度	number	-
contentLineWidth	图表的内容区域描边宽度	number	-
contentLineDash	图表的内容区域描边虚线配置	[number,number]	-
contentOpacity	图表的内容区域整体透明度	number	-
contentShadowColor	图表的内容区域阴影颜色	string	-
contentShadowBlur	图表的内容区域阴影模糊系数	number	-
contentShadowOffsetX	图表的内容区域阴影水平偏移	number	-
contentShadowOffsetY	图表的内容区域阴影垂直偏移	number	-
contentCursor	图表的内容区域鼠标样式	string	`default`

在配置视图样式的时候，不是以对象的形式来配置，而是以 view、plot、main、content前缀加属性的方式来配置。

({
  viewStyle: {
    // 配置图表的视图区域的样式
    viewFill: '#DCEEFE',
    viewRadius: 50,

    // 配置图表的绘制区域的样式
    plotFill: '#fff',
    plotFillOpacity: 0.45,
    plotStroke: 'yellow',
    plotLineWidth: 4,

    // 配置图表的主区域的样式
    mainFill: 'l(270) 0:#ffffff 0.5:#7ec2f3 1:#1890ff',
    mainFillOpacity: 0.75,

    // 配置图表的内容区域的样式
    contentFill: 'l(90) 0:#ffadad 0.5:#ffd6a5 1:#fdffb6',
    contentShadowColor: '#5d5d5d',
    contentShadowBlur: 40,
    contentShadowOffsetX: 5,
    contentShadowOffsetY: 5,
  },
});

坐标轴

概述

Ant Design Charts 中 Axis（坐标轴） 就像是图表的 "尺子"，用于建立数据与视觉位置的映射关系，并通过刻度、标签、网格线等元素帮助用户直观理解数据的分布与比例。它能帮你快速看懂图形的位置和数值大小。

简单来说，坐标轴可以帮助我们把数据数字和图表上的位置对应起来，让图表更容易理解。

举个例子：在柱状图中，横轴通常表示时间，纵轴表示销售额，这样你就能一眼看出 "3 月卖了 200 万，4 月涨到 300 万"

坐标轴使用方式示意图

构成元素

使用方式

通过前面的概述内容，相信你对坐标轴已经有了一个清晰的认识。那么具体该如何使用呢？接下来，我将手把手教你如何配置坐标轴。

配置坐标轴其实就像搭积木，只需记住一个简单的核心口诀："用 axis 属性，按方向配置，哪里需要改哪里改。"

第一步：启用坐标轴（默认已开启）

Ant Design Charts 会根据你的数据类型自动生成坐标轴，不需要任何配置就能看到基础坐标轴

启用坐标轴（默认已开启）

第二步：按方向单独配置

配置 x（水平方向）坐标轴

{
  "axis": {
    "x": {}
  }
}

配置 y（垂直方向）坐标轴

{
  "axis": {
    "y": {}
  }
}

配置层级

坐标轴可以在 Mark 层级配置。在 Ant Design Charts 中每个标记（Mark）都有自己的坐标轴。如果标记对应比例尺是同步的，那么坐标轴也会合并。

({
  axis: {
    x: { labelFormatter: '%0' },
    y: { tickCount: 5 },
  },
});

坐标轴也可以在 View 层级配置。坐标轴具有传递性。视图上声明的坐标轴会传递给 children 声明的标记，如果该标记有对应通道的坐标轴，就合并；否则不影响。

({
  axis: {
    x: { labelFormatter: '%0' },
    y: { tickCount: 5 },
  },
});

隐藏坐标轴

隐藏每个通道的坐标轴：

坐标轴隐藏演示

隐藏 x 坐标轴：

({
  axis: { x: false }, // 隐藏 x 水平方向坐标轴
});

隐藏 y 坐标轴：

({
  axis: { y: false }, // 隐藏 y 垂直方向坐标轴
});

隐藏多个坐标轴

({
  axis: false,
});

配置项

每个坐标轴由标题（title）、轴线（line）、刻度（tick）、刻度值（label）以及网格线（grid）组成。

属性	描述	类型	默认值
title	设置坐标轴的标题文本及其样式	title	-
line	设置坐标轴线的显示及其样式	line	-
tick	设置坐标轴刻度线的显示及其样式	tick	-
label	设置坐标轴刻度值的显示及其样式	label	-
grid	设置坐标轴网格线的显示及其样式	grid	-
animate	设置坐标轴动画效果	`boolean` \| animate	-
position	设置坐标轴的位置	`left` \| `right` \| `top` \| `bottom`	`x: bottom` \| `y: left`

title

属性	描述	类型	默认值
title	关闭标题或设置标题内容	`false`\|`string` \| `number` \| `DisplayObject`	-
titleSpacing	标题到坐标轴的距离	`number` \| `(datum, index, data) => number`	10
titlePosition	标题相对坐标轴的位置，支持首字母简写形式，如`'top'`简写为`'t'`	`'top'`\|`'bottom'`\|`'left'`\|`'right'`	`'lb'`
titleFontSize	标题文字大小	`number` \| `(datum, index, data) => number`	-
titleFontWeight	标题的字体粗细	`string` \| `(datum, index, data) => string`	-
titleFontFamily	标题文字字体	`number` \| `(datum, index, data) => number`	-
titleStroke	标题字体颜色	`string` \| `(datum, index, data) => string`	-
titleStrokeOpacity	标题透明度	`number` \| `(datum, index, data) => number`	-
titleTextBaseline	标题垂直基线	`string` \| `(datum, index, data) => string`	`middle`
titleFillOpacity	标题填充透明度	`number` \| `(datum, index, data) => number`	1
titleStroke	标题描边颜色	`string` \| `(datum, index, data) => string`	`transparent`
titleStrokeOpacity	标题描边透明度	`number` \| `(datum, index, data) => number`	1
titleLineHeight	标题行高	`number` \| `(datum, index, data) => number`	1
titleLineWidth	标题描边宽度	`number` \| `(datum, index, data) => number`	0
titleLineDash	标题虚线样式	`number[]` \| `(datum, index, data) => number[]`	[]
titleOpacity	标题整体透明度	`number` \| `(datum, index, data) => number`	1
titleShadowColor	标题阴影颜色	`string` \| `(datum, index, data) => string`	`transparent`
titleShadowBlur	标题阴影模糊度	`number` \| `(datum, index, data) => number`	0
titleShadowOffsetX	标题阴影 X 偏移	`number` \| `(datum, index, data) => number`	0
titleShadowOffsetY	标题阴影 Y 偏移	`number` \| `(datum, index, data) => number`	0
titleCursor	标题鼠标样式	`string` \| `(datum, index, data) => string`	`default`

配置方式

({
  // 配置坐标轴
  axis: {
    // 配置 y 轴
    y: {
      // 这部分是轴标题的配置
      title: 'Frequency', // 设置 y 轴标题
      titleSpacing: 30, // 设置 y 轴标题与轴线之间的间距
      titleFill: 'steelblue', // 设置 y 轴标题的颜色
    },
    // 配置 x 轴
    x: {
      // 这部分是轴标题的配置
      title: 'Letter', // 设置 x 轴标题
    },
  },
});

line

属性	描述	类型	默认值
line	是否显示轴线	`boolean`	false
arrow	是否显示箭头	`boolean`	true
lineExtension	轴线两侧的延长线	`[number, number]`	-
lineArrow	定义轴线箭头形状，默认为箭头形状	`DisplayObject`	-
lineArrowOffset	箭头偏移长度	`number`	15
lineArrowSize	箭头尺寸	`number`	-
lineLineWidth	轴线宽度	`number` \| `(datum, index, data) => number`	-
lineLineDash	轴线描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0, 0]的效果为没有描边。	`[number,number]`	-
lineOpacity	轴线整体透明度	`number`	1
lineStroke	轴线描边色	`string`	-
lineStrokeOpacity	轴线描边色透明度	`number`	-

配置方式

({
  axis: {
    x: {
      line: true, // 是否显示轴线
      arrow: true, // 是否显示箭头
      lineArrowOffset: 10, // 箭头偏移长度
      lineArrowSize: 30, // 箭头尺寸
      lineLineWidth: 10, // 轴线宽度
    },
    y: {
      line: true, // 是否显示轴线
      arrow: true, // 是否显示箭头
      lineArrowOffset: 10, // 箭头偏移长度
      lineArrowSize: 30, // 箭头尺寸
      lineLineWidth: 10, // 轴线宽度
    },
  },
});

tick

属性	描述	类型	默认值
tick	是否显示刻度	`boolean`	true
tickFilter	刻度线过滤	`(datum, index, data)=>boolean`	-
tickFormatter	刻度线格式化，可用于自定义刻度样式，回调函数中会额外返回该刻度的方向	`DisplayObject` \| `(datum, index, data, Vector)=> DisplayObject`	-
tickDirection	刻度朝向，为 `positive` 时，位于侧轴方向（即主轴顺时针 90 度方向）, 为 `negative` 时，刻度位于侧轴负方向	`'positive'` \| `'negative'`	`positive`
tickLength	刻度线长度	`number`\|`(datum, index, data)=>number`	15
tickLineWidth	刻度线宽度	`number` \| `(datum, index, data, Vector)=>number`	-
tickLineDash	刻度线描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0, 0]的效果为没有描边。	`[number,number]` \| `(datum, index, data, Vector)=>[number,number]`	-
tickStroke	刻度线颜色	`string` \| `(datum, index, data, Vector)=>string`	-
tickStrokeOpacity	刻度线透明度	`number` \| `(datum, index, data, Vector)=>number`	-

({
  // 配置坐标轴
  axis: {
    y: {
      tickLength: 20, // 设置 y 轴刻度线的长度
      tickFilter: (_, i) => i % 3 !== 0, // 过滤 y 轴刻度线，只显示每隔 3 个刻度线
    },
  },
});

label

属性	描述	类型	默认值
label	是否显示刻度值	`boolean`	-
labelFontSize	刻度值文字大小	`number` \| `(datum, index, data)=>number`	-
labelOpacity	刻度值透明度	`number` \| `(datum, index, data)=>number`	-
labelFontWeight	刻度值字体粗细	`number` \|`(datum, index, data)=>number`	-
labelFontFamily	刻度值文字字体	`string` \| `(datum, index, data)=>string`	-
labelAlign	刻度值对齐方式 - 'horizontal' 始终保持水平 - 'parallel' 平行于坐标轴 - 'perpendicular' 垂直于坐标轴	`'horizontal'` \| `'parallel'` \| `'perpendicular'`	`parallel`
labelFilter	刻度值过滤	`(datum, index, data)=> boolean`	-
labelFormatter	刻度值线格式化	`DisplayObject` \| `(datum, index, data, Vector)=> DisplayObject`	-
transform	刻度值转换，避免文本之间发生重叠。当前支持超长文本缩略、重叠刻度值隐藏、自动旋转	`Transform[]`	-
labelAutoHide	自动隐藏重叠的刻度值，设置 size 值的时候生效	`boolean` \| `HideOverlapCfg`	-
labelAutoRotate	自动旋转刻度，设置 size 值的时候生效值	`boolean` \| `RotateOverlapCfg`	-
labelAutoEllipsis	自动缩略刻度值，设置 size 值的时候生效	`boolean` \| `EllipsisOverlapCfg`	-
labelAutoWrap	自动换行刻度值，设置 size 值的时候是生效	`boolean` \| `WrapOverlapCfg`	-
labelDirection	刻度值位于轴线的位置，参考`tickDirection`	`'positive'` \| `'negative'`	`positive`
labelSpacing	刻度值到其对应刻度的间距	`number`	0
labelLineWidth	刻度值宽度	`number` \|`(datum, index, data)=>number`	-
labelLineDash	刻度值描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0, 0]的效果为没有描边。	`[number,number]` \| `(datum, index, data)=>[number, number]`	-
labelFill	刻度值字体颜色	`string` \| `(datum, index, data)=>string`	-
labelFillOpacity	刻度值文本透明度	`number` \| `(datum, index, data)=>number`	-
labelStroke	刻度值文本描边颜色	`string` \| `(datum, index, data)=>string`	-
labelStrokeOpacity	刻度值文本描边透明度	`number` \| `(datum, index, data)=>number`	-

labelFormatter 视觉通道用于调整标签的格式。

{
  "axis": {
    "y": {
      "title": "销售额"
    },
    "x": {
      "title": "月份",
      "labelFontSize": 12
    }
  }
}

transform 为了避免刻度标签重叠或超出显示范围，系统提供了多种优化方式，包括缩略、旋转、隐藏和换行。这些功能可通过两种方式配置：

transform 数组（多策略组合）
labelAutoXXX 系列属性（单策略快捷配置）推荐

两者的核心功能完全一致，区别在于使用场景和配置方式。

transform 数组（多策略组合）

{
  "axis": {
    "y": {
      "title": "y 轴标题"
    },
    "x": {
      "title": "x 轴标题",
      "labelFontSize": 12,
      "transform": [
        {
          "suffix": "..",
          "minLength": 8,
          "maxLength": 12
        },
        {
          "wordWrapWidth": 80,
          "maxLines": 2,
          "recoverWhenFailed": true
        },
        {
          "optionalAngles": [
            0,
            45,
            90
          ],
          "recoverWhenFailed": true
        },
        {
          "keepHeader": true,
          "keepTail": true
        }
      ]
    }
  }
}

使用 labelAutoHide、labelAutoRotate、labelAutoEllipsis、labelAutoWrap、属性（需设置 size）

{
  "axis": {
    "y": {
      "title": "y 轴标题"
    },
    "x": {
      "title": "x 轴标题",
      "labelFontSize": 12,
      "size": 100,
      "labelAutoEllipsis": {
        "suffix": "..",
        "minLength": 8,
        "maxLength": 12
      },
      "labelAutoWrap": {
        "wordWrapWidth": 80,
        "maxLines": 2,
        "recoverWhenFailed": true
      },
      "labelAutoRotate": {
        "optionalAngles": [
          0,
          45,
          90
        ],
        "recoverWhenFailed": true
      },
      "labelAutoHide": {
        "keepHeader": true,
        "keepTail": true
      }
    }
  }
}

export interface Transform {
  /** 避免刻度值重叠时的额外边距 */
  margin?: number[];
}

export interface EllipsisOverlapCfg extends Transform {
  type: 'ellipsis';
  /** 缩略替换字符，默认为 ... */
  suffix?: string;
  /** 文本短于该长度时不再缩略 */
  minLength: string | number;
  /** 文本短于该长度时一定会进行缩略 */
  maxLength?: string | number;
  /** 每次缩略执行步长 */
  step?: string | number;
}

export interface RotateOverlapCfg extends Transform {
  type: 'rotate';
  /** 可选的旋转角度值 */
  optionalAngles: number[];
  /** 当旋转无法避免重叠时，是否恢复为默认旋转角度 */
  recoverWhenFailed?: boolean;
}

export interface HideOverlapCfg extends Transform {
  type: 'hide';
  /** 保证第一个刻度值不被隐藏 */
  keepHeader?: boolean;
  /** 保证最后一个刻度值不被隐藏 */
  keepTail?: boolean;
}

export interface WrapOverlapCfg extends Transform {
  type: 'wrap';
  /** 单行最大宽度 */
  wordWrapWidth?: number;
  /** 最大行数 */
  maxLines?: number;
  recoverWhenFailed?: boolean;
}

grid

在不同坐标系下网格线会具有不同的样式

场景标签	样式
`直角坐标系`
`极坐标系`
`极坐标系`
`极坐标系` `雷达图`

属性	描述	类型	默认值
grid	是否显示网格线	`boolean`	false
gridFilter	网格线过滤	`(datum, index, data)=> boolean`	-
gridLength	网格线长度。一般情况下，不需要用户配置。	`number` \| `(datum, index, data)=> number`	0
gridAreaFill	网格线区域颜色	`string` \| `string[]`\| `(datum, index, data)=> string`	-
gridLineWidth	网格线宽度	`number`	-
gridLineDash	网格线描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0, 0]的效果为没有描边。	`[number,number]`	-
gridStroke	网格线颜色	`string`	-
gridStrokeOpacity	网格线透明度	`number`	-

animate

支持设置更新时的动画效果

属性	描述	类型	默认值	必须
animate	是否开启动画	`boolean` \| `EffectTiming`	-

EffectTiming 支持配置的属性如下：

属性	描述	类型	默认值
delay	延迟执行时间 (ms)	`number`	-
duration	动画持续时间 (ms)	`number`	-
easing	动画的缓动函数	`Easing`	-
endDelay	延迟执行时间 (ms)	`number`	-
fill	动画处于非运行状态时的展示效果	`Fill`	-

事件

坐标轴(axis)组件本身没有专属的事件类型。

示例

{
  "marginTop": 40,
  "axis": {
    "x": {
      "position": "bottom",
      "title": "x 轴标题",
      "titleFontWeight": 500,
      "grid": true,
      "gridLineWidth": 2,
      "line": true,
      "lineLineWidth": 5,
      "lineStroke": "#f50",
      "tick": true,
      "tickLineWidth": 5,
      "tickLength": 10,
      "tickStroke": "#3366ff",
      "label": true,
      "labelFontSize": 12,
      "labelFill": "#009900",
      "labelFontWeight": 500
    },
    "y": {
      "position": "left",
      "title": "y 轴标题",
      "titleFontWeight": 500,
      "grid": true,
      "gridLineWidth": 2,
      "line": true,
      "lineLineWidth": 5,
      "lineStroke": "#f50",
      "tick": true,
      "tickLineWidth": 5,
      "tickLength": 10,
      "tickStroke": "#3366ff",
      "label": true,
      "labelFontSize": 12,
      "labelFill": "#009900",
      "labelFontWeight": 500
    }
  }
}

更多的案例，可以查看图表示例 - 坐标轴页面。

图例

概述

Ant Design Charts 中 图例（Legend） 是图表的辅助元素，使用颜色、大小、形状区分不同的数据类型，用于图表中数据的筛选。可以理解为是非空间通道（ color，opacity，size，shape）对应比例尺的可视化，Ant Design Charts 会根据设置图形属性映射以及数据的类型自动生成不同的图例，当一个变量对应了多个图形属性时，Ant Design Charts 会对图例进行合并，以达到精简的目的。

color，opacity，size，shape 这四个非空间通道如果判断接收的参数是数据源的字段时，会自动生成不同的图例：

视觉通道	解释
color	根据不同的颜色生成图例
opacity	根据不同的透明度生成图例
size	根据不同的大小生成图例
shape	根据不同的形状生成图例

构成元素

使用方式

配置图例有两种方式

第一种，传入 boolean 设置是否显示图例。

({
  legend: false; // 隐藏所有图例
})

({
  legend: {color: false}; // 隐藏 color 通道的图例
})

第二种，传入 legendOption 对图例进行整体配置。

({
  legend: {
    color: {},
    size: {},
  },
});

配置层级

图例可以在 Mark 层级配置。在 Ant Design Charts 中，每个标记（Mark）都有自己的图例。如果标记对应的比例尺是同步的，那么图例也会合并。

({
  legend: {
    color: {},
    size: {},
  },
});

图例也可以在 View 层级配置。图例具有传递性。视图上声明的图例会传递给 children 声明的标记，如果该标记有对应通道的图例，就合并；否则不影响。

({
  legend: {
    color: {},
    size: {},
  },
});

配置项

Ant Design Charts 中图例分为 连续图例 和 分类图例 两种，由于这两种图例的结构不同，所以配置项也存在差异。

有的配置项作用范围区分分类图例和连续图例：分类图例连续图例

属性	描述	类型	默认值
orientation	图例朝向，对于分类图例来说即滚动方向	`horizontal` \| `vertical`	`horizontal`
position	图例的位置	`top` \| `right` \| `left` \| `bottom`	`top`
layout	调整图例的 flex 布局方式	layout	详见layout
size	图例的尺寸	number	-
width	图例的宽度	number	-
crossPadding	图例到图表区域的距离	number	`12`
order	图例在布局的时候的排序	number	`1`
title	配置图例的标题	title	详见title
cols 分类图例	指定每行显示的图例项数量，为空时表示列数不受限制	number	-
colPadding 分类图例	指定图例项之间的横向间隔	number	`12`
rowPadding 分类图例	指定图例项之间的纵向间隔	number	`8`
maxRows 分类图例	指定图例最大行数	number	`3`
maxCols 分类图例	指定图例最大列数	number	`3`
itemMarker 分类图例	配置图例项的图标	itemMarker	详见itemMarker
itemLabel 分类图例	配置图例项的标签文字	itemLabel	详见itemLabel
itemValue 分类图例	配置图例项的值	itemValue	详见itemValue
itemBackground 分类图例	配置图例项的背景	itemBackground	详见itemBackground
itemWidth 分类图例	配置图例项的宽度	number	-
itemSpan 分类图例	配置图例项图标、标签和值的空间划分	number \| number[]	`[1, 1, 1]`
itemSpacing 分类图例	配置图例项图标、标签和值之间的间距	number \| number[]	`[8, 8]`
nav 分类图例	配置图例的分页器	nav	详见nav
color 连续图例	配置连续图例的色带颜色	string[] \| d3-interpolate	-
block 连续图例	连续图例是否按区间显示	boolean	false
type 连续图例	配置连续图例的类型	`size` \|`color`	`color`
ribbon 连续图例	配置连续图例的色带	ribbon	详见ribbon
handle 连续图例	配置连续图例的滑动手柄	handle	详见handle
label 连续图例	配置连续图例的标签/刻度值	label	详见label
indicator 连续图例	配置连续图例的指示器	indicator	详见indicator

orientation

optional horizontal | vertical

图例朝向，对于分类图例来说即滚动方向。默认为 horizontal。

position

optional "top" | "right" | "left" | "bottom"

图例的位置。默认为 top。

null;

layout

LegendLayoutCfg optional

Legend 组件支持调整其在画布中的位置，通过 layout 属性来设置。目前支持基本的 Flex 布局方式，支持的属性包括: justifyContent, alignItems, flexDirection。LegendLayoutCfg 配置如下：

属性	描述	类型	默认值
justifyContent	主轴对齐方式	`flex-start` \| `flex-end` \| `center`	`flex-start`
alignItems	交叉轴对齐	`flex-start` \| `flex-end` \| `center`	`flex-start`
flexDirection	主轴方向	`row` \| `column`	position 为`top`和`bottom`的时候为`row`，其他时候为`column`

通过配置图例的 position 和 layout ，我们可以很灵活地改变图例的位置。

({
  legend: {
    color: {
      position: 'right',
      layout: {
        justifyContent: 'center',
      },
    },
  },
});

size

number optional

Legend 组件的尺寸。影响组件在交叉轴上的大小，例如水平位置的图例，影响整体高度。手动配置会导致 Ant Design Charts 内部计算逻辑失效，需要自己配置 margin、padding、inset 等大小，详见图表布局。除非需要定制化的场景，否则不建议配置。

width

number optional

Legend 组件的宽度。

crossPadding

number optional

Legend 组件和图表的距离。默认为 12。

order

number optional

Legend 组件在布局的时候的排序。默认为 1。Ant Design Charts 内部的组件都有默认的排序大小，值越小越靠近图表区域，例如 Title 组件的默认排序是 2，就比默认排序为 1 的 Legend 组件更远离图表区域。

title

LegendTitleCfg optional

图例标题配置项。LegendTitleCfg 配置如下：

属性	描述	类型	默认值
title	关闭标题或设置标题内容	false \| string	连续图例为 true，分类图例为 false
titleSpacing	标题到内容区域的间距	number \| number[]	`4`
titleInset	标题文本内边距	number \| number[]	`0`
titlePosition	标题所处位置。可采用简写形式，如`i` 表示`inner`，如`lt` 表示`left-top`	`top` \| `bottom` \|`left` \|`right` \|`left-top` \|`left-bottom` \|`right-top` \|`right-bottom` \|`inner`	-
titleFontSize	标题文字大小	number \| (datum, index, data) => number	`12`
titleFontFamily	标题文字字体	string \| (datum, index, data) => string	-
titleFontWeight	标题字体粗细	number \| (datum, index, data) => number	`normal`
titleLineHeight	标题文字的行高	number \| (datum, index, data) => number	-
titleTextAlign	设置标题文本内容的当前对齐方式	`center` \| `end` \| `left` \| `right` \| `start`	`start`
titleTextBaseline	设置在绘制标题文本时使用的当前文本基线	`top` \| `middle` \| `bottom` \| `alphabetic` \| `hanging`	`bottom`
titleFill	标题字体颜色	string \| (datum, index, data) => string	`#1D2129`
titleFillOpacity	标题字体颜色透明度	number \| (datum, index, data) => number	`0.65`
titleStroke	标题字体描边颜色	string \| (datum, index, data) => string	-
titleStrokeOpacity	标题字体描边颜色透明度	number \| (datum, index, data) => number	-
titleLineWidth	标题字体描边的宽度	number \| (datum, index, data) => number	-
titleLineDash	标题字体描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
titleOpacity	标题文字的整体透明度	number \| (datum, index, data) => number	-
titleShadowColor	标题文字阴影颜色	string \| (datum, index, data) => string	-
titleShadowBlur	标题文字阴影的高斯模糊系数	number \| (datum, index, data) => number	-
titleShadowOffsetX	设置阴影距标题文字的水平距离	number \| (datum, index, data) => number	-
titleShadowOffsetY	设置阴影距标题文字的垂直距离	number \| (datum, index, data) => number	-
titleCursor	标题鼠标样式。同 css 的鼠标样式	string \| (datum, index, data) => string	`default`

在 Legend 组件中配置标题的时候，不是以对象的形式来配置，而是以 title前缀加属性的方式来配置。

({
  legend: {
    size: {
      title: '图例标题',
      titleSpacing: 0,
      titleInset: 0,
      titlePosition: 't',
      titleFontSize: 16,
      titleFontFamily: 'sans-serif',
      titleFontWeight: 500,
      titleLineHeight: 20,
      titleTextAlign: 'center',
      titleTextBaseline: 'middle',
      titleFill: '#000',
      titleFillOpacity: 0.9,
      titleStroke: '#DAF5EC',
      titleStrokeOpacity: 0.9,
      titleLineWidth: 2,
      titleLineDash: [4, 8],
      titleOpacity: 1,
      titleShadowColor: '#d3d3d3',
      titleShadowBlur: 10,
      titleShadowOffsetX: 10,
      titleShadowOffsetY: 10,
      titleCursor: 'pointer',
    },
  },
});

尝试一下:

cols

number optional

适用于分类图例。指定每行显示的图例项数量，为空时表示列数不受限制。

图例布局默认采用流式布局。

当指定 cols 之后会采用网格布局。

colPadding

number optional

适用于分类图例。指定图例项之间的横向间隔。默认为 12。

rowPadding

number optional

适用于分类图例。指定图例项之间的纵向间隔。默认为 8。

maxRows

number optional

适用于分类图例。指定图例最大行数。默认为 3。

maxCols

number optional

适用于分类图例。指定图例最大列数。默认为 3。

💡 maxRows 和 maxCols 是怎么作用于图例布局的？

maxRows 和 maxCols 用于限制图例布局的最大行数和列数。在代码中通过 getRows = (rows) => Math.min(rows, maxRows)和 getCols = (cols) => Math.min(cols, maxCols)实现行列数限制。

参数	垂直布局	水平布局
maxCols	限制列数，控制图例宽度	无直接影响（列数由 `cols` 参数指定）
maxRows	无直接影响（行数由高度自动计算）	限制行数，控制图例高度

潜在问题

垂直布局：若 maxCols 过小，可能导致单列行数超过 maxHeight，引发溢出。
水平布局：若 maxRows 过小，部分项可能被截断。

此时需要适当调整图表的 margin 和 padding，保证图例有足够的空间展示。

itemMarker

LegendItemMarkerCfg optional

适用于分类图例。配置图例项的图标。LegendItemMarkerCfg 配置如下：

属性	描述	类型	默认值
itemMarker	图例项图标	Symbols \|(datum, index, data)=>Symbols	`circle`
itemMarkerSize	图例项图标大小	number \| (datum, index, data) => number	`8`
itemMarkerFill	图例项图标填充色	string \| (datum, index, data) => string	-
itemMarkerFillOpacity	图例项图标填充透明度	number \| (datum, index, data) => number	`1`
itemMarkerStroke	图例项图标的描边	string \| (datum, index, data) => string	-
itemMarkerStrokeOpacity	图例项图标描边透明度	number \| (datum, index, data) => number	-
itemMarkerLineWidth	图例项图标描边的宽度	number \| (datum, index, data) => number	-
itemMarkerLineDash	图例项图标描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
itemMarkerOpacity	图例项图标的整体透明度	number \| (datum, index, data) => number	-
itemMarkerShadowColor	图例项图标阴影颜色	string \| (datum, index, data) => string	-
itemMarkerShadowBlur	图例项图标阴影的高斯模糊系数	number \| (datum, index, data) => number	-
itemMarkerShadowOffsetX	设置阴影距图例项图标的水平距离	number \| (datum, index, data) => number	-
itemMarkerShadowOffsetY	设置阴影距图例项图标的垂直距离	number \| (datum, index, data) => number	-
itemMarkerCursor	图例项图标鼠标样式。同 css 的鼠标样式。	string \| (datum, index, data) => string	`default`

Symbols 可选类型

属性	描述
bowtie	图形类型：蝴蝶结
cross	图形类型：十字
dash	图形类型：短横线
diamond	图形类型：菱形
dot	图形类型：点
hexagon	图形类型：六边形
hollowBowtie	图形类型：空心蝴蝶结
hollowDiamond	图形类型：空心菱形
hollowHexagon	图形类型：空心六边形
hollowPoint	图形类型：空心点
hollowSquare	图形类型：空心正方形
hollowTriangle	图形类型：空心三角形
hollowTriangleDown	图形类型：倒空心三角形
hv	样式类型：HV 路径
hvh	样式类型：HVH 路径
hyphen	图形类型：连字符
line	图形类型：直线
plus	图形类型：加号
point	图形类型：实心点
rect	图形类型：矩形
smooth	样式类型：平滑曲线
square	图形类型：正方形
tick	图形类型：刻度线
triangleDown	图形类型：倒三角形
triangle	图形类型：三角形
vh	样式类型：VH 路径
vhv	样式类型：VHV 路径

{
  "itemMarker": "bowtie",
  "scale": {
    "color": {
      "domain": [
        "a",
        "b"
      ],
      "range": [
        "steelblue",
        "orange"
      ]
    }
  }
}

在 Legend 组件中配置图例项图标的时候，不是以对象的形式来配置，而是以 itemMarker前缀加属性的方式来配置。

({
  legend: {
    color: {
      itemMarker: 'rect',
      itemMarkerSize: 20,
      itemMarkerFill: '#000',
      itemMarkerFillOpacity: 0.9,
      itemMarkerStroke: '#DAF5EC',
      itemMarkerStrokeOpacity: 0.9,
      itemMarkerLineWidth: 2,
      itemMarkerLineDash: [4, 8],
      itemMarkerOpacity: 1,
      itemMarkerShadowColor: '#d3d3d3',
      itemMarkerShadowBlur: 10,
      itemMarkerShadowOffsetX: 10,
      itemMarkerShadowOffsetY: 10,
      itemMarkerCursor: 'pointer',
    },
  },
});

itemLabel

LegendItemLabelCfg optional

适用于分类图例。配置图例项的标签。LegendItemLabelCfg 配置如下：

属性	描述	类型	默认值
itemLabelText	图例项标签内容	string \| (datum, index, data) => string	-
itemLabelFontSize	图例项标签文字大小	number \| (datum, index, data) => number	`12`
itemLabelFontFamily	图例项标签文字字体	string \| (datum, index, data) => string	-
itemLabelFontWeight	图例项标签字体粗细	number \| (datum, index, data) => number	`normal`
itemLabelLineHeight	图例项标签文字的行高	number \| (datum, index, data) => number	-
itemLabelTextAlign	设置图例项标签文本内容的当前对齐方式	`center` \| `end` \| `left` \| `right` \| `start`	`start`
itemLabelTextBaseline	设置在绘制图例项标签文本时使用的当前文本基线	`top` \| `middle` \| `bottom` \| `alphabetic` \| `hanging`	`bottom`
itemLabelFill	图例项标签字体颜色	string \| (datum, index, data) => string	`#1D2129`
itemLabelFillOpacity	图例项标签字体颜色透明度	number \| (datum, index, data) => number	`0.9`
itemLabelStroke	图例项标签字体描边颜色	string \| (datum, index, data) => string	-
itemLabelStrokeOpacity	图例项标签字体描边颜色透明度	number \| (datum, index, data) => number	-
itemLabelLineWidth	图例项标签字体描边的宽度	number \| (datum, index, data) => number	-
itemLabelLineDash	图例项标签字体描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (da tu m, index, data) => [number , number]	-
itemLabelOpacity	图例项标签文字的整体透明度	number \| (datum, index, data) => number	-
itemLabelShadowColor	图例项标签文字阴影颜色	string \| (datum, index, data) => string	-
itemLabelShadowBlur	图例项标签文字阴影的高斯模糊系数	number \| (datum, index, data) => number	-
itemLabelShadowOffsetX	设置阴影距图例项标签文字的水平距离	number \| (datum, index, data) => number	-
itemLabelShadowOffsetY	设置阴影距图例项标签文字的垂直距离	number \| (datum, index, data) => number	-
itemLabelCursor	图例项标签鼠标样式。同 css 的鼠标样式	string \| (datum, index, data) => string	`default`

在 Legend 组件中配置图例项标签的时候，不是以对象的形式来配置，而是以 itemLabel前缀加属性的方式来配置。

({
  legend: {
    color: {
      itemLabelText: '图例项标签',
      itemLabelFontSize: 16,
      itemLabelFontFamily: 'sans-serif',
      itemLabelFontWeight: 500,
      itemLabelLineHeight: 20,
      itemLabelTextAlign: 'center',
      itemLabelTextBaseline: 'middle',
      itemLabelFill: '#000',
      itemLabelFillOpacity: 0.9,
      itemLabelStroke: '#DAF5EC',
      itemLabelStrokeOpacity: 0.9,
      itemLabelLineWidth: 2,
      itemLabelLineDash: [4, 8],
      itemLabelOpacity: 1,
      itemLabelShadowColor: '#d3d3d3',
      itemLabelShadowBlur: 10,
      itemLabelShadowOffsetX: 10,
      itemLabelShadowOffsetY: 10,
      itemLabelCursor: 'pointer',
    },
  },
});

itemValue

LegendItemValueCfg optional

适用于分类图例。配置图例项的值。LegendItemValueCfg 配置如下：

属性	描述	类型	默认值
itemValueText	图例项值内容	string \| (datum, index, data) => string	-
itemValueFontSize	图例项值文字大小	number \| (datum, index, data) => number	`12`
itemValueFontFamily	图例项值文字字体	string \| (datum, index, data) => string	-
itemValueFontWeight	图例项值字体粗细	number \| (datum, index, data) => number	`normal`
itemValueLineHeight	图例项值文字的行高	number \| (datum, index, data) => number	-
itemValueTextAlign	设置图例项值文本内容的当前对齐方式	`center` \| `end` \| `left` \| `right` \| `start`	`start`
itemValueTextBaseline	设置在绘制图例项值文本时使用的当前文本基线	`top` \| `middle` \| `bottom` \| `alphabetic` \| `hanging`	`bottom`
itemValueFill	图例项值字体颜色	string \| (datum, index, data) => string	`#1D2129`
itemValueFillOpacity	图例项值字体颜色透明度	number \| (datum, index, data) => number	`0.65`
itemValueStroke	图例项值字体描边颜色	string \| (datum, index, data) => string	-
itemValueStrokeOpacity	图例项值字体描边颜色透明度	number \| (datum, index, data) => number	-
itemValueLineWidth	图例项值字体描边的宽度	number \| (datum, index, data) => number	-
itemValueLineDash	图例项值字体描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
itemValueOpacity	图例项值文字的整体透明度	number \| (datum, index, data) => number	-
itemValueShadowColor	图例项值文字阴影颜色	string \| (datum, index, data) => string	-
itemValueShadowBlur	图例项值文字阴影的高斯模糊系数	number \| (datum, index, data) => number	-
itemValueShadowOffsetX	设置阴影距图例项值文字的水平距离	number \| (datum, index, data) => number	-
itemValueShadowOffsetY	设置阴影距图例项值文字的垂直距离	number \| (datum, index, data) => number	-
itemValueCursor	图例项值鼠标样式。同 css 的鼠标样式	string \| (datum, index, data) => string	`default`

在 Legend 组件中配置图例项值的时候，不是以对象的形式来配置，而是以 itemValue前缀加属性的方式来配置。

({
  legend: {
    color: {
      itemValueText: '图例项值',
      itemValueFontSize: 16,
      itemValueFontFamily: 'sans-serif',
      itemValueFontWeight: 500,
      itemValueLineHeight: 20,
      itemValueTextAlign: 'center',
      itemValueTextBaseline: 'middle',
      itemValueFill: '#000',
      itemValueFillOpacity: 0.9,
      itemValueStroke: '#DAF5EC',
      itemValueStrokeOpacity: 0.9,
      itemValueLineWidth: 2,
      itemValueLineDash: [4, 8],
      itemValueOpacity: 1,
      itemValueShadowColor: '#d3d3d3',
      itemValueShadowBlur: 10,
      itemValueShadowOffsetX: 10,
      itemValueShadowOffsetY: 10,
      itemValueCursor: 'pointer',
    },
  },
});

itemBackground

LegendItemBackgroundCfg optional

适用于分类图例。配置图例项的背景。LegendItemBackgroundCfg 配置如下：

属性	描述	类型	默认值
itemBackgroundRadius	图例项背景圆角	number \| (datum, index, data) => number	`0`
itemBackgroundFill	图例项背景填充色	string \| (datum, index, data) => string	`transparent`
itemBackgroundFillOpacity	图例项背景填充透明度	number \| (datum, index, data) => number	-
itemBackgroundStroke	图例项背景的描边	string \| (datum, index, data) => string	-
itemBackgroundStrokeOpacity	图例项背景描边透明度	number \| (datum, index, data) => number	-
itemBackgroundLineWidth	图例项背景描边的宽度	number \| (datum, index, data) => number	-
itemBackgroundLineDash	图例项背景描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
itemBackgroundOpacity	图例项背景的整体透明度	number \| (datum, index, data) => number	-
itemBackgroundShadowColor	图例项背景阴影颜色	string \| (datum, index, data) => string	-
itemBackgroundShadowBlur	图例项背景阴影的高斯模糊系数	number \| (datum, index, data) => number	-
itemBackgroundShadowOffsetX	设置阴影距图例项背景的水平距离	number \| (datum, index, data) => number	-
itemBackgroundShadowOffsetY	设置阴影距图例项背景的垂直距离	number \| (datum, index, data) => number	-
itemBackgroundCursor	图例项背景鼠标样式。同 css 的鼠标样式。	string \| (datum, index, data) => string	`default`

在 Legend 组件中配置图例项背景的时候，不是以对象的形式来配置，而是以 itemBackground前缀加属性的方式来配置。

({
  legend: {
    color: {
      itemBackgroundRadius: 50,
      itemBackgroundFill: '#000',
      itemBackgroundFillOpacity: 0.9,
      itemBackgroundStroke: '#DAF5EC',
      itemBackgroundStrokeOpacity: 0.9,
      itemBackgroundLineWidth: 2,
      itemBackgroundLineDash: [4, 8],
      itemBackgroundOpacity: 1,
      itemBackgroundShadowColor: '#d3d3d3',
      itemBackgroundShadowBlur: 10,
      itemBackgroundShadowOffsetX: 10,
      itemBackgroundShadowOffsetY: 10,
      itemBackgroundCursor: 'pointer',
    },
  },
});

接下来，试试结合 itemMarker、itemLabel、itemValue和itemBackground的各种属性，来配置一个自定义的图例吧：

itemWidth

number optional

适用于分类图例。配置图例项的宽度。

itemSpan

number|number[] optional

适用于分类图例。配置图例项图标、标签和值的空间划分。默认为[1, 1, 1]。

itemSpacing

number|number[] optional

适用于分类图例。配置图例项图标、标签和值之间的间距。默认为[8, 8]。

nav

LegendNavCfg optional

适用于分类图例。配置图例的分页器。在网格布局下，页面容量 = gridRow × gridCol，如果分类项数量超出此容量，则分页。在弹性布局下，页面容量动态计算，受容器宽度和高度限制。当分类项超过容器高度或宽度时，进行分页，展示分页器组件。LegendNavCfg 配置如下：

属性	描述	类型	默认值
navEffect	翻页显示效果	参见 Web Animations API	`linear`
navDuration	单次翻页动效时长	number	`200`
navOrientation	翻页滚动方向 - 横向`horizontal` - 纵向`vertical`	`horizontal` \|`vertical`	`horizontal`
navDefaultPage	默认展示页数	number	`0`
navLoop	是否启用循环翻页	boolean	false
navPageWidth	分页器页宽	number	-
navPageHeight	分页器页高	number	-
navControllerPadding	分页器按钮与分页器数字的间隔	number \| number[]	`5`
navControllerSpacing	分页器按钮与页的间隔，可以用来配置分页器与图例的间隔	number \| number[]	`5`
navPageNumFontSize	分页器数字文字大小	number \| (datum, index, data) => number	`12`
navPageNumFontFamily	分页器数字文字字体	string \| (datum, index, data) => string	-
navPageNumFontWeight	分页器数字字体粗细	number \| (datum, index, data) => number	`normal`
navPageNumLineHeight	分页器数字文字的行高	number \| (datum, index, data) => number	-
navPageNumTextAlign	设置分页器数字文本内容的当前对齐方式	`center` \| `end` \| `left` \| `right` \| `start`	`start`
navPageNumTextBaseline	设置在绘制分页器数字文本时使用的当前文本基线	`top` \| `middle` \| `bottom` \| `alphabetic` \| `hanging`	`bottom`
navPageNumFill	分页器数字字体颜色	string \| (datum, index, data) => string	`#1D2129`
navPageNumFillOpacity	分页器数字字体颜色透明度	number \| (datum, index, data) => number	`0.45`
navPageNumStroke	分页器数字字体描边颜色	string \| (datum, index, data) => string	-
navPageNumStrokeOpacity	分页器数字字体描边颜色透明度	number \| (datum, index, data) => number	-
navPageNumLineWidth	分页器数字字体描边的宽度	number \| (datum, index, data) => number	-
navPageNumLineDash	分页器数字字体描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
navPageNumOpacity	分页器数字文字的整体透明度	number \| (datum, index, data) => number	-
navPageNumShadowColor	分页器数字文字阴影颜色	string \| (datum, index, data) => string	-
navPageNumShadowBlur	分页器数字文字阴影的高斯模糊系数	number \| (datum, index, data) => number	-
navPageNumShadowOffsetX	设置阴影距分页器数字文字的水平距离	number \| (datum, index, data) => number	-
navPageNumShadowOffsetY	设置阴影距分页器数字文字的垂直距离	number \| (datum, index, data) => number	-
navPageNumCursor	分页器数字鼠标样式。同 css 的鼠标样式	string \| (datum, index, data) => string	`default`
navButtonSize	分页器按钮尺寸	number \| (datum, index, data) => number	-
navButtonFill	分页器按钮填充色	string \| (datum, index, data) => string	`#1D2129`
navButtonFillOpacity	分页器按钮填充透明度	number \| (datum, index, data) => number	`0.65`
navButtonStroke	分页器按钮的描边	string \| (datum, index, data) => string	-
navButtonStrokeOpacity	分页器按钮描边透明度	number \| (datum, index, data) => number	-
navButtonLineWidth	分页器按钮描边的宽度	number \| (datum, index, data) => number	-
navButtonLineDash	分页器按钮描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
navButtonOpacity	分页器按钮的整体透明度	number \| (datum, index, data) => number	-
navButtonShadowColor	分页器按钮阴影颜色	string \| (datum, index, data) => string	-
navButtonShadowBlur	分页器按钮阴影的高斯模糊系数	number \| (datum, index, data) => number	-
navButtonShadowOffsetX	设置阴影距分页器按钮的水平距离	number \| (datum, index, data) => number	-
navButtonShadowOffsetY	设置阴影距分页器按钮的垂直距离	number \| (datum, index, data) => number	-
navButtonCursor	分页器按钮鼠标样式。同 css 的鼠标样式。	string \| (datum, index, data) => string	`default`
navFormatter	页码文本格式化	(current: number, total: number) => string	-

在 Legend 组件中配置分页器属性的时候，不是以对象的形式来配置，而是以 nav前缀加属性的方式来配置。

({
  legend: {
    color: {
      navEffect: 'cubic-bezier',
      navDuration: 400,
      navOrientation: 'vertical',
      navDefaultPage: 1,
      navLoop: true,
      navPageWidth: 10,
      navPageHeight: 10,
      navControllerPadding: 10,
      navControllerSpacing: 10,

      //配置navPageNum的绘图属性
      navPageNumFontSize: 16,
      navPageNumFontFamily: 'sans-serif',
      navPageNumFontWeight: 500,
      navPageNumLineHeight: 20,
      navPageNumTextAlign: 'center',
      navPageNumTextBaseline: 'middle',
      navPageNumFill: '#000',
      navPageNumFillOpacity: 0.9,
      navPageNumStroke: '#DAF5EC',
      navPageNumStrokeOpacity: 0.9,
      navPageNumLineWidth: 2,
      navPageNumLineDash: [4, 8],
      navPageNumOpacity: 1,
      navPageNumShadowColor: '#d3d3d3',
      navPageNumShadowBlur: 10,
      navPageNumShadowOffsetX: 10,
      navPageNumShadowOffsetY: 10,
      navPageNumCursor: 'pointer',

      // 配置navButton的绘图属性
      navButtonFill: '#000',
      navButtonFillOpacity: 0.9,
      navButtonStroke: '#DAF5EC',
      navButtonStrokeOpacity: 0.9,
      navButtonLineWidth: 2,
      navButtonLineDash: [4, 8],
      navButtonOpacity: 1,
      navButtonShadowColor: '#d3d3d3',
      navButtonShadowBlur: 10,
      navButtonShadowOffsetX: 10,
      navButtonShadowOffsetY: 10,
      navButtonCursor: 'pointer',
    },
  },
});

color

string[] | d3-interpolate optional

适用于连续图例。配置连续图例的色带颜色，为数组时会从中按序取色。

block

boolean optional

适用于连续图例。连续图例是否按区间显示。默认为 false。

type

size | color optional

适用于连续图例。配置连续图例的类型。默认为 color。

结合 block 和 type 属性可以配置不同样式的连续图例。连续数据的图例具有 4 种样式，分别为：

连续表示 默认
范围表示 block=true
尺寸表示 type='size'
尺寸、范围表示 type='size' block=true

ribbon

LegendRibbonCfg optional

适用于连续图例。配置连续图例的色带。LegendRibbonCfg 配置如下：

属性	描述	类型	默认值
ribbonSize	色带大小	number \| (datum, index, data) => number	`12`
ribbonFill	色带填充色	string \| (datum, index, data) => string	`#aaa`
ribbonFillOpacity	色带填充透明度	number \| (datum, index, data) => number	-
ribbonStroke	色带的描边	string \| (datum, index, data) => string	-
ribbonStrokeOpacity	色带描边透明度	number \| (datum, index, data) => number	-
ribbonLineWidth	色带描边的宽度	number \| (datum, index, data) => number	-
ribbonLineDash	色带描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
ribbonOpacity	色带的整体透明度	number \| (datum, index, data) => number	-
ribbonShadowColor	色带阴影颜色	string \| (datum, index, data) => string	-
ribbonShadowBlur	色带阴影的高斯模糊系数	number \| (datum, index, data) => number	-
ribbonShadowOffsetX	设置阴影距色带的水平距离	number \| (datum, index, data) => number	-
ribbonShadowOffsetY	设置阴影距色带的垂直距离	number \| (datum, index, data) => number	-
ribbonCursor	色带鼠标样式。同 css 的鼠标样式。	string \| (datum, index, data) => string	`default`

在 Legend 组件中配置色带的时候，不是以对象的形式来配置，而是以 ribbon前缀加属性的方式来配置。

({
  legend: {
    color: {
      ribbonSize: 20,
      ribbonFill: '#000',
      ribbonFillOpacity: 0.9,
      ribbonStroke: '#DAF5EC',
      ribbonStrokeOpacity: 0.9,
      ribbonLineWidth: 2,
      ribbonLineDash: [4, 8],
      ribbonOpacity: 1,
      ribbonShadowColor: '#d3d3d3',
      ribbonShadowBlur: 10,
      ribbonShadowOffsetX: 10,
      ribbonShadowOffsetY: 10,
      ribbonCursor: 'pointer',
    },
  },
});

handle

LegendHandleCfg optional

滑动窗口标记了当前的值选取范围，通过与滑动窗口交互能够对视图中的值范围进行选择。

适用于连续图例。配置连续图例的滑动手柄。 LegendHandleCfg 配置如下：

属性	描述	类型	默认值
handle	是否显示滑动手柄	boolean	true
handleLabel	是否显示滑动手柄标签	boolean	false
slidable	窗口是否可以滑动	boolean	true
range	滑动窗口默认选择范围	[number, number]	`[min, max]`
step	单次滑动步长	number	`1`
handleLabelFontSize	手柄标签文字大小	number \| (datum, index, data) => number	`12`
handleLabelFontFamily	手柄标签文字字体	string \| (datum, index, data) => string	-
handleLabelFontWeight	手柄标签字体粗细	number \| (datum, index, data) => number	`normal`
handleLabelLineHeight	手柄标签文字的行高	number \| (datum, index, data) => number	-
handleLabelTextAlign	设置手柄标签文本内容的当前对齐方式	`center` \| `end` \| `left` \| `right` \| `start`	`start`
handleLabelTextBaseline	设置在绘制手柄标签文本时使用的当前文本基线	`top` \| `middle` \| `bottom` \| `alphabetic` \| `hanging`	`bottom`
handleLabelFill	手柄标签字体颜色	string \| (datum, index, data) => string	`#1D2129`
handleLabelFillOpacity	手柄标签字体颜色透明度	number \| (datum, index, data) => number	`0.45`
handleLabelStroke	手柄标签字体描边颜色	string \| (datum, index, data) => string	-
handleLabelStrokeOpacity	手柄标签字体描边颜色透明度	number \| (datum, index, data) => number	-
handleLabelLineWidth	手柄标签字体描边的宽度	number \| (datum, index, data) => number	-
handleLabelLineDash	手柄标签字体描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
handleLabelOpacity	手柄标签文字的整体透明度	number \| (datum, index, data) => number	-
handleLabelShadowColor	手柄标签文字阴影颜色	string \| (datum, index, data) => string	-
handleLabelShadowBlur	手柄标签文字阴影的高斯模糊系数	number \| (datum, index, data) => number	-
handleLabelShadowOffsetX	设置阴影距手柄标签文字的水平距离	number \| (datum, index, data) => number	-
handleLabelShadowOffsetY	设置阴影距手柄标签文字的垂直距离	number \| (datum, index, data) => number	-
handleLabelCursor	手柄标签鼠标样式。同 css 的鼠标样式	string \| (datum, index, data) => string	`default`
handleIconSize	手柄图标尺寸色	number \| (datum, index, data) => number	-
handleIconFill	手柄图标填充色	string \| (datum, index, data) => string	`#1D2129`
handleIconFillOpacity	手柄图标填充透明度	number \| (datum, index, data) => number	`0.65`
handleIconStroke	手柄图标的描边	string \| (datum, index, data) => string	-
handleIconStrokeOpacity	手柄图标描边透明度	number \| (datum, index, data) => number	-
handleIconLineWidth	手柄图标描边的宽度	number \| (datum, index, data) => number	-
handleIconLineDash	手柄图标描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
handleIconOpacity	手柄图标的整体透明度	number \| (datum, index, data) => number	-
handleIconShadowColor	手柄图标阴影颜色	string \| (datum, index, data) => string	-
handleIconShadowBlur	手柄图标阴影的高斯模糊系数	number \| (datum, index, data) => number	-
handleIconShadowOffsetX	设置阴影距手柄图标的水平距离	number \| (datum, index, data) => number	-
handleIconShadowOffsetY	设置阴影距手柄图标的垂直距离	number \| (datum, index, data) => number	-
handleIconCursor	手柄图标鼠标样式。同 css 的鼠标样式。	string \| (datum, index, data) => string	`default`

在 Legend 组件中配置连续图例滑动手柄属性的时候，不是以对象的形式来配置，而是以 handle前缀加属性的方式来配置。

({
  legend: {
    color: {
      handle: true,
      handleLabel: true,
      slidable: true,
      range: [0, 1],
      step: 1,
      //配置handleLabel的绘图属性
      handleLabelFontSize: 16,
      handleLabelFontFamily: 'sans-serif',
      handleLabelFontWeight: 500,
      handleLabelLineHeight: 20,
      handleLabelTextAlign: 'center',
      handleLabelTextBaseline: 'middle',
      handleLabelFill: '#000',
      handleLabelFillOpacity: 0.9,
      handleLabelStroke: '#DAF5EC',
      handleLabelStrokeOpacity: 0.9,
      handleLabelLineWidth: 2,
      handleLabelLineDash: [4, 8],
      handleLabelOpacity: 1,
      handleLabelShadowColor: '#d3d3d3',
      handleLabelShadowBlur: 10,
      handleLabelShadowOffsetX: 10,
      handleLabelShadowOffsetY: 10,
      handleLabelCursor: 'pointer',

      handleIconSize: 50,
      // 配置handleIcon的绘图属性
      handleIconFill: '#000',
      handleIconFillOpacity: 0.9,
      handleIconStroke: '#DAF5EC',
      handleIconStrokeOpacity: 0.9,
      handleIconLineWidth: 2,
      handleIconLineDash: [4, 8],
      handleIconOpacity: 1,
      handleIconShadowColor: '#d3d3d3',
      handleIconShadowBlur: 10,
      handleIconShadowOffsetX: 10,
      handleIconShadowOffsetY: 10,
      handleIconCursor: 'pointer',
    },
  },
});

label

LegendLabelCfg optional

适用于连续图例。配置连续图例的标签/刻度值。 LegendLabelCfg 配置如下：

属性	描述	类型	默认值
label	是否显示连续图例的刻度值	boolean	true
labelFormatter	连续图例的刻度值格式化	(datum, index, data)=>string	-
labelFilter	连续图例的刻度值过滤	(datum, index, data)=>boolean	-
labelDirection	连续图例的刻度值位于色带的位置，参考 `axis direction`	`positive` \| `negative`	`positive`
labelSpacing	连续图例的刻度值到色带的间距	number	`3`
labelAlign	连续图例的刻度值对齐位置 - `'value'` 对齐到刻度 - `'range'` 对齐到范围	`value` \| `range`	`value`
labelFontSize	连续图例刻度值文字大小	number \| (datum, index, data) => number	`12`
labelFontFamily	连续图例刻度值文字字体	string \| (datum, index, data) => string	-
labelFontWeight	连续图例刻度值字体粗细	number \| (datum, index, data) => number	`normal`
labelLineHeight	连续图例刻度值文字的行高	number \| (datum, index, data) => number	-
labelTextAlign	设置连续图例刻度值文本内容的当前对齐方式	`center` \| `end` \| `left` \| `right` \| `start`	`start`
labelTextBaseline	设置在绘制连续图例刻度值文本时使用的当前文本基线	`top` \| `middle` \| `bottom` \| `alphabetic` \| `hanging`	`bottom`
labelFill	连续图例刻度值字体颜色	string \| (datum, index, data) => string	`#1D2129`
labelFillOpacity	连续图例刻度值字体颜色透明度	number \| (datum, index, data) => number	`0.45`
labelStroke	连续图例刻度值字体描边颜色	string \| (datum, index, data) => string	-
labelStrokeOpacity	连续图例刻度值字体描边颜色透明度	number \| (datum, index, data) => number	-
labelLineWidth	连续图例刻度值字体描边的宽度	number \| (datum, index, data) => number	-
labelLineDash	连续图例刻度值字体描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
labelOpacity	连续图例刻度值文字的整体透明度	number \| (datum, index, data) => number	-
labelShadowColor	连续图例刻度值文字阴影颜色	string \| (datum, index, data) => string	-
labelShadowBlur	连续图例刻度值文字阴影的高斯模糊系数	number \| (datum, index, data) => number	-
labelShadowOffsetX	设置阴影距连续图例刻度值文字的水平距离	number \| (datum, index, data) => number	-
labelShadowOffsetY	设置阴影距连续图例刻度值文字的垂直距离	number \| (datum, index, data) => number	-
labelCursor	手柄标签鼠标样式。同 css 的鼠标样式	string \| (datum, index, data) => string	`default`

刻度值对齐方式

对齐到刻度

对齐到范围

在 Legend 组件中配置连续图例的标签/刻度值属性的时候，不是以对象的形式来配置，而是以 label前缀加属性的方式来配置。

({
  legend: {
    color: {
      label: true,
      labelFormatter: (d) => {},
      labelFilter: (datum, index, data) => {},
      labelDirection: 'positive',
      labelSpacing: 5,
      labelAlign: 'range',
      // 配置连续图例的刻度值label的绘图属性
      labelFontSize: 16,
      labelFontFamily: 'sans-serif',
      labelFontWeight: 500,
      labelLineHeight: 20,
      labelTextAlign: 'center',
      labelTextBaseline: 'middle',
      labelFill: '#000',
      labelFillOpacity: 0.9,
      labelStroke: '#DAF5EC',
      labelStrokeOpacity: 0.9,
      labelLineWidth: 2,
      labelLineDash: [4, 8],
      labelOpacity: 1,
      labelShadowColor: '#d3d3d3',
      labelShadowBlur: 10,
      labelShadowOffsetX: 10,
      labelShadowOffsetY: 10,
      labelCursor: 'pointer',
    },
  },
});

indicator

LegendIndicatorCfg optional

适用于连续图例。配置连续图例的指示器。指示器是在与连续图例交互过程中指示当前所在位置所表示值大小的提示组件。

LegendIndicatorCfg 配置如下：

属性	描述	类型	默认值
indicator	是否显示连续图例的刻值指示器	boolean	false
indicatorFormatter	值指示器格式化	(datum, index, data)=>string	-
indicatorLabelFontSize	值指示器文字大小	number \| (datum, index, data) => number	-
indicatorLabelFontFamily	值指示器文字字体	string \| (datum, index, data) => string	-
indicatorLabelFontWeight	值指示器字体粗细	number \| (datum, index, data) => number	-
indicatorLabelLineHeight	值指示器文字的行高	number \| (datum, index, data) => number	-
indicatorLabelTextAlign	设置值指示器文本内容的当前对齐方式	`center` \| `end` \| `left` \| `right` \| `start`	`start`
indicatorLabelTextBaseline	设置在绘制值指示器文本时使用的当前文本基线	`top` \| `middle` \| `bottom` \| `alphabetic` \| `hanging`	`bottom`
indicatorLabelFill	值指示器字体颜色	string \| (datum, index, data) => string	-
indicatorLabelFillOpacity	值指示器字体颜色透明度	number \| (datum, index, data) => number	-
indicatorLabelStroke	值指示器字体描边颜色	string \| (datum, index, data) => string	-
indicatorLabelStrokeOpacity	值指示器字体描边颜色透明度	number \| (datum, index, data) => number	-
indicatorLabelLineWidth	值指示器字体描边的宽度	number \| (datum, index, data) => number	-
indicatorLabelLineDash	值指示器字体描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
indicatorLabelOpacity	值指示器文字的整体透明度	number \| (datum, index, data) => number	-
indicatorLabelShadowColor	值指示器文字阴影颜色	string \| (datum, index, data) => string	-
indicatorLabelShadowBlur	值指示器文字阴影的高斯模糊系数	number \| (datum, index, data) => number	-
indicatorLabelShadowOffsetX	设置阴影距值指示器文字的水平距离	number \| (datum, index, data) => number	-
indicatorLabelShadowOffsetY	设置阴影距值指示器文字的垂直距离	number \| (datum, index, data) => number	-
indicatorLabelCursor	值指示器鼠标样式。同 css 的鼠标样式	string \| (datum, index, data) => string	`default`
indicatorBackgroundFill	值指示器背景填充色	string \| (datum, index, data) => string	-
indicatorBackgroundFillOpacity	值指示器背景填充透明度	number \| (datum, index, data) => number	-
indicatorBackgroundStroke	值指示器背景的描边	string \| (datum, index, data) => string	-
indicatorBackgroundStrokeOpacity	值指示器背景描边透明度	number \| (datum, index, data) => number	-
indicatorBackgroundLineWidth	值指示器背景描边的宽度	number \| (datum, index, data) => number	-
indicatorBackgroundLineDash	值指示器背景描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0,0]的效果为没有描边。	[number,number] \| (datum, index, data) => [number , number]	-
indicatorBackgroundOpacity	值指示器背景的整体透明度	number \| (datum, index, data) => number	-
indicatorBackgroundShadowColor	值指示器背景阴影颜色	string \| (datum, index, data) => string	-
indicatorBackgroundShadowBlur	值指示器背景阴影的高斯模糊系数	number \| (datum, index, data) => number	-
indicatorBackgroundShadowOffsetX	设置阴影距值指示器背景的水平距离	number \| (datum, index, data) => number	-
indicatorBackgroundShadowOffsetY	设置阴影距值指示器背景的垂直距离	number \| (datum, index, data) => number	-
indicatorBackgroundCursor	值指示器背景鼠标样式。同 css 的鼠标样式。	string \| (datum, index, data) => string	`default`

在 Legend 组件中配置值指示器属性的时候，不是以对象的形式来配置，而是以 indicator前缀加属性的方式来配置。

({
  legend: {
    color: {
      indicator: 'true',
      indicatorFormatter: (d) => {},

      //配置indicatorLabel的绘图属性
      indicatorLabelFontSize: 16,
      indicatorLabelFontFamily: 'sans-serif',
      indicatorLabelFontWeight: 500,
      indicatorLabelLineHeight: 20,
      indicatorLabelTextAlign: 'center',
      indicatorLabelTextBaseline: 'middle',
      indicatorLabelFill: '#000',
      indicatorLabelFillOpacity: 0.9,
      indicatorLabelStroke: '#DAF5EC',
      indicatorLabelStrokeOpacity: 0.9,
      indicatorLabelLineWidth: 2,
      indicatorLabelLineDash: [4, 8],
      indicatorLabelOpacity: 1,
      indicatorLabelShadowColor: '#d3d3d3',
      indicatorLabelShadowBlur: 10,
      indicatorLabelShadowOffsetX: 10,
      indicatorLabelShadowOffsetY: 10,
      indicatorLabelCursor: 'pointer',

      // 配置indicatorBackground的绘图属性
      indicatorBackgroundFill: '#000',
      indicatorBackgroundFillOpacity: 0.9,
      indicatorBackgroundStroke: '#DAF5EC',
      indicatorBackgroundStrokeOpacity: 0.9,
      indicatorBackgroundLineWidth: 2,
      indicatorBackgroundLineDash: [4, 8],
      indicatorBackgroundOpacity: 1,
      indicatorBackgroundShadowColor: '#d3d3d3',
      indicatorBackgroundShadowBlur: 10,
      indicatorBackgroundShadowOffsetX: 10,
      indicatorBackgroundShadowOffsetY: 10,
      indicatorBackgroundCursor: 'pointer',
    },
  },
});

事件

图例组件对外暴露了一些特殊的事件，用于获取组件的交互信息。

事件类型	描述	类型
click 分类图例	点击图例项时触发	`(item:Selection)=>void`
mouseenter 分类图例	鼠标移入图例项时触发	`(item: Selection)=>void`
mouseleave 分类图例	鼠标移出图例项时触发	`(item:Selection)=>void`
valuechange 连续图例	滑动窗口选取范围改变时触发	`(range: [number, number])=>void`
indicate 连续图例	指示器值改变时触发	`(value: number, range: [number, number])=>void`

组件在图表渲染后才会出现，所以要在 afterrender 后挂载组件的事件，以下是一个例子：

chart.on('afterrender', () => {
  const { canvas } = chart.getContext();
  const { document } = canvas;
  document.querySelector('.component').addEventListener('valuechange', (range) => {});
});

chart.on('afterrender', () => {
  const { canvas } = chart.getContext();
  const { document } = canvas;
  document.querySelector('.component').addEventListener('valuechange', (range) => {});
});

chart.on('afterrender', () => {
  const { canvas } = chart.getContext();
  const { document } = canvas;
  document.querySelector('.component').addEventListener('valuechange', (range) => {});
});

示例

自定义图例项图标（itemMarker）

在具体开发过程中，内置的图例项图标可能无法满足你的要求，不用担心，Ant Design Charts 提供了强大的自定义功能。

自定义符号（Symbol）

每一个符号都可以自定义，主要分为三步：

定义符号路径。
注册符号。
使用符号。

首先我们来看看如何定义符号路径。一个符号路径是一个函数，该函数接受起始点的横向坐标 x、纵向坐标 y 和绘制半径，返回一个路径。

const triangle: SymbolFactor = (x, y, r) => {
  const diffY = r * Math.sin((1 / 3) * Math.PI);
  return [['M', x - r, y + diffY], ['L', x, y - diffY], ['L', x + r, y + diffY], ['Z']];
};

triangle.style = ['fill'];

import { type SymbolFactor } from '@antv/g2';

const triangle: SymbolFactor = (x, y, r) => {
  const diffY = r * Math.sin((1 / 3) * Math.PI);
  return [['M', x - r, y + diffY], ['L', x, y - diffY], ['L', x + r, y + diffY], ['Z']];
};
triangle.style = ['fill'];

接下来就是注册符号，通过调用 Ant Design Charts.register('symbol.${symbol}', Symbol) 来完成注册。其中 symbol 是符号的名字，Symbol 是定义好的符号路径。比如注册一个三角形的符号：

register('symbol.customTriangle', triangle);

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

register('symbol.customTriangle', triangle);

最后就是使用该符号了

'customTriangle';

使用图片

{
  "tooltip": false,
  "legend": {
    "color": {
      "itemMarkerSize": 40,
      "maxRows": 1
    }
  },
  "scale": {
    "y": {
      "nice": true
    }
  }
}

自定义图例（Legend）

Ant Design Charts 内置的图例是用 canvas 或者 svg 绘制的，如果希望能用 HTML 渲染图例，就可以按照如下几步自定义图例：

关闭内置图例并且渲染图表。
等待图表渲染完成，根据 scale 数据渲染 HTML 图例。
添加交互（如果需要）。

首先是关闭内置图例，同时渲染图表。

{
  "legend": false
}

然后是等待图表渲染完成，并且调用 legendColor 渲染 HTML 图例：

chart.render().then(legendColor);

在 legendColor 里我们首先需要把图例画出来，下面这个例子把图例画出来后，添加到了画布前面：

function legendColor(chart) {
  const node = chart.getContainer();
  const legend = document.createElement('div');
  node.insertBefore(legend, node.childNodes[0]);

  // ...
}

画出了图例之后，我们需要绘制图例项，这个数据从对应通道的比例尺获得：chart.getScale().color，并且通过 scale 的 domain 和 range 获得对应的名字和值。

function legendColor(chart) {
  // ...
  const scale = chart.getScale().color;
  const { domain } = scale.getOptions();
  const items = domain.map(() => {});
  // ...
}

function legendColor(chart) {
  // ...
  const scale = chart.getScale().color;
  const { domain } = scale.getOptions();
  const items = domain.map(() => {});
  // ...
}

绘制完图例项之后我们就应该给每个图例项通过 item.onclick 添加交互，收集当前选中的值，并且根据这个值去给图表的声明添加 Filter 转换，最后重新渲染图表。最后完整的实现如下：

滚动条

概述

Ant Design Charts 中 滚动条（Scrollbar） 可以用于过滤数据，可以和 x 或者 y 通道绑定的，滚动条默认都是关闭的。解决图表信息过于密集而无法完全展示的问题。

何时使用：内容是否超出显示区域取决于内容的多少以及显示区域的尺寸，当需要显示的内容在纵向方向上超过显示区域的大小时，应当使用垂直滚动条以控制显示的部分，横向滚动条同理。

{
  "autoFit": true,
  "scale": {
    "y": {
      "type": "log"
    }
  },
  "scrollbar": {
    "x": {
      "ratio": 0.2,
      "trackSize": 14,
      "trackFill": "#000",
      "trackFillOpacity": 1
    },
    "y": {
      "ratio": 0.5,
      "trackSize": 12,
      "value": 0.1,
      "trackFill": "#000",
      "trackFillOpacity": 1
    }
  }
}

构成元素

使用方式

滚动条可以在 Mark 层级配置。在 Ant Design Charts 中，每个标记（Mark）都有自己的滚动条。如果标记对应的比例尺是同步的，那么滚动条也会合并。

({
  scrollbar: {
    x: {}, // x轴滚动条
    y: {}, // y轴滚动条
  },
});

滚动条也可以在 View 层级配置。滚动条具有传递性。视图上声明的滚动条会传递给 children 声明的标记，如果该标记有对应通道的滚动条，就合并；否则不影响。

({
  scrollbar: {
    x: {},
    y: {},
  },
});

配置项

属性	描述	类型	默认值
ratio	滚动条的比例，为单页显示数据在总数据量上单比例	number	`0.5`
value	滚动条的起始位置, x轴默认值为 `0`, y轴默认为 `1`	[0, 1]
slidable	是否可以拖动	boolean	true
scrollable	是否支持滚轮滚动	boolean	true
position	滚动条相对图表方位	string	`bottom`
isRound	滚动条样式是否为圆角	boolean	true
style	滚动条样式配置，样式都可以直接在配置项中配置	style

{
  "autoFit": true,
  "transform": [
    {
      "type": "stackY"
    }
  ],
  "scrollbar": {
    "x": {
      "ratio": 0.2,
      "value": 0.1,
      "scrollable": true,
      "slidable": true,
      "isRound": true,
      "position": "top",
      "thumbFillOpacity": 0.2,
      "thumbFill": "#000",
      "thumbStroke": "#000",
      "trackFill": "#fa0",
      "trackStroke": "#f00",
      "trackLineWidth": 2,
      "trackFillOpacity": 1,
      "trackSize": 14,
      "trackLength": 300
    }
  }
}

style

style 滚动条样式配置，内部做了处理，可以直接在配置项配置样式。具体样式配置，可参考滚动条滑块(thumb)、滚动条滑轨(track)。

滚动条滑块(thumb)

属性	描述	类型	默认值
thumbFill	滚动条滑块填充色	string	`#000`
thumbFillOpacity	滚动条滑块填充色透明度	number	`0.15`
thumbStroke	滚动条滑块描边色	string	–
thumbLineWidth	滚动条滑块描边宽度	number	–
thumbStrokeOpacity	滚动条滑块描边色透明度	number	–

({
  scrollbar: {
    x: {
      thumbFill: '#1173a1',
      thumbFillOpacity: 1,
      thumbStroke: 'red',
      thumbLineWidth: 2,
      thumbStrokeOpacity: 0.9,
    },
    y: {},
  },
});

滚动条滑轨(track)

属性	描述	类型	默认值
trackSize	滚动条的轨道宽度	number	`10`
trackLength	滚动条的轨道长度	number
trackFill	滚动条轨道填充色	string	-
trackFillOpacity	滚动条轨道填充色透明度	number	`0`
trackLineWidth	滚动条轨道描边宽度	number	–
trackStroke	滚动条轨道描边色	string	–
trackStrokeOpacity	滚动条轨道描边色透明度	number	–

({
  scrollbar: {
    x: {
      trackSize: 20,
      trackLength: 300,
      trackFillOpacity: 1,
      trackFill: 'red',
      trackLineWidth: 2,
      trackStroke: 'red',
      trackStrokeOpacity: 0.4,
    },
    y: {},
  },
});

事件

属性	描述	类型
valuechange	发生滚动变化时触发，通过事件监听	`({detail: { oldValue: any; value: any }}) => void`

{
  "autoFit": true,
  "scale": {
    "y": {
      "type": "log"
    }
  },
  "scrollbar": {
    "x": true
  }
}

提示

概述

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

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

构成元素

使用方式

{
  "tooltip": {
    "title": "name",
    "items": [
      "genre"
    ]
  }
}

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

{
  "interaction": {
    "tooltip": {
      "series": true
    }
  }
}

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

{
  "interaction": {
    "tooltip": {
      "series": true
    }
  }
}

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

{
  "tooltip": false
}

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

{
  "interaction": {
    "tooltip": false
  }
}

尝试一下

配置项

配置项分为两个部分

tooltip 是 Ant Design Charts 中用于展示数据点的详细信息的一个 UI 组件。当用户将鼠标悬停在图表的某个数据点上时，tooltip 会显示该数据点的相关信息，比如坐标值、度量值等。
interaction.tooltip 是 Ant Design Charts 的交互机制的一部分，属于 interaction（交互）模块。它是一种内置的交互行为，用于增强工具提示的功能，特别是在某些特定的交互场景下（如动态显示或隐藏工具提示）。

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

特性	tooltip	interaction.tooltip
职责	定义工具提示的内容、样式和基本行为	定义工具提示在交互场景下的行为
配置方式	通过 chart.tooltip() 配置	通过 chart.interaction() 启用或自定义
作用范围	全局生效，影响整个图表	与特定交互行为绑定
典型用途	设置工具提示的字段、样式、内容等	控制工具提示的动态显示/隐藏或其他交互逻辑

tooltip

属性	描述	类型	适用于
title	设置`tooltip`的标题内容：如果值为数据字段名，则会展示数据中对应该字段的数值，如果数据中不存在该字段，将该值作为 title。详见title 配置	title
nodeTitle	设置复合图形`tooltip`标题的节点`title`属性	title	桑基图等复合图形
linkTitle	设置复合图形`tooltip`标题的弦`title`属性	title	桑基图等复合图形
items	指定`tooltip`中显示的字段，默认不同图表有不同的默认字段列表。配合 channel 配置一起使用，效果更佳。详见items 配置	items
nodeItems	设置复合图形`tooltip`标题的节点`items`属性	items	桑基图等复合图形
linkItems	设置复合图形`tooltip`标题的弦`items`属性	items	桑基图等复合图形

interaction.tooltip

属性	描述	类型	默认值	适用于
body	是否展示 tooltip	`boolean`	`true`
bounding	控制`Tooltip`提示框的显示边界，超出会自动调整位置	`BBox`	图表区域大小
css	设置 tooltip 样式	css
crosshairs	配置是否显示 crosshairs，详见crosshairs 配置	`boolean`
crosshairsLineDash	配置`crosshairs`虚线的间隔	crosshairs 配置
crosshairsStroke	配置`crosshairs`显示的颜色	`string`
crosshairsStrokeWidth	配置`crosshairs`十字辅助线的线条宽度	`number`
crosshairsXStroke	配置`crosshairs`X 轴显示的颜色	`string`
crosshairsXLineDash	配置`crosshairs`X 轴虚线的间隔	crosshairs 配置
crosshairsXStroke	配置`crosshairs`X 轴显示的颜色	`string`
crosshairsXStrokeWidth	配置`crosshairs`X 轴十字辅助线的线条宽度	`number`
crosshairsYStroke	配置`crosshairs`Y 轴显示的颜色	`string`
crosshairsYLineDash	配置`crosshairs`Y 轴虚线的间隔	crosshairs 配置
crosshairsYStroke	配置`crosshairs`Y 轴显示的颜色	`string`
crosshairsYStrokeWidth	配置`crosshairs`Y 轴十字辅助线的线条宽度	`number`
disableNative	禁用 pointerover 和 pointerout 事件	`boolean`	`false`
enterable	tooltip 是否允许鼠标滑入	`boolean`	`false`
filter	item 筛选器	`(d: TooltipItemValue) => any`	-
groupName	是否使用 groupName	`boolean`	`true`
leading	是否在时间间隔开始的时候更新提示信息	`boolean`	`true`
marker	是否展示 marker	`boolean`	`true`
`marker${StyleAttrs}`	marker 的样式	`number \| string`	-
markerType	markerType 是提示框（Tooltip）配置项中的一个属性，用于控制提示框中标记点（Marker）的样式	`'hollow' \| undefined`	`undefined`
mount	指定提示框的挂载节点	`string` \| `HTMLElement`	图表容器
position	设置 tooltip 的固定展示位置，相对于数据点	`TooltipPosition`
offset	在位置方向上的偏移量	`[number, number]` `	[10, 10]
render	自定义渲染`tooltip`内容[render] (#自定义渲染内容)	`(event, options) => HTMLElement \| string`
series	是否是系列元素的 tooltip	`boolean`		多条折线、多组柱状图
shared	相同 x 的元素是否共享 tooltip	`boolean`	`false`
sort	item 排序器	`(d: TooltipItemValue) => any`	-
trailing	是否在时间间隔结束的时候更新提示信息	`boolean`	`false`
trailing	是否在时间间隔结束的时候更新提示信息	`boolean`	`false`
wait	提示信息更新的时间间隔，单位为毫秒	`number`	`50`

type TooltipPosition = 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';

type BBox = { x: number, y: number, width: number, height: number };

crosshairs

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

{
  "interaction": {
    "legendFilter": false,
    "elementPointMove": true,
    "tooltip": {
      "crosshairs": true,
      "crosshairsStroke": "red",
      "crosshairsLineDash": [
        4,
        4
      ],
      "markerType": "hollow"
    }
  }
}

title

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

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

{
  "tooltip": {}
}

在不需要设置 title 的时候，可以直接声明为一个数组：

{
  "tooltip": [
    "genre",
    "sold"
  ]
}

其中完整的 title 结构如下：

细分配置项名称	类型	功能描述
channel	`string`	定义生成 title 的通道
field	`string`	定义生成 title 的的字段
value	`string`	title 的值
valueFormatter	`string` \| `Function`	格式化 title

字段

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

{
  "tooltip": {
    "title": "sold",
    "items": [
      "genre"
    ]
  }
}

{
  "tooltip": {
    "title": {
      "field": "sold"
    },
    "items": [
      {
        "field": "genre"
      }
    ]
  }
}

通道

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

{
  "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;">${d.letter}</span>`,
      custom: ...
    }),
    items: [
      (datum, index, data, column) => ({
        color: d.sold > 150 ? 'red' : 'blue', // 指定 item 的颜色
        name: index === 0 ? d.genre : `${d.genre} ${data[i].genre}`, // 指定 item 的名字
        value: column.y.value[i], // 使用 y 通道的值、
        custom: ...
      }),
    ],
  },
});

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

复合图形配置

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

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

items

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

其中完整的 title 结构如下：

细分配置项名称	类型	功能描述
color	`string`	marker 的颜色
field	`string`	定义生成 item 的的字段
name	`string`	item 的名字
value	`string`	item 的值
channel	`string`	定义生成 item 的值的通道
valueFormatter	`string` \| `Function`	格式化 item

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: '连接线自定义属性',
        };
      },
    ],
  },
});

设置样式

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

{
  "transform": [
    {
      "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"
        }
      }
    }
  }
}

尝试一下

自定义渲染内容

有时候内置的 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>`;
}

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

下面是一个简单的例子：

{
  "interaction": {
    "tooltip": {}
  }
}

获取自定义 render 参数

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

chart.options({
  tooltip: {
    items: [
      (datum, index, data, column) => ({
        color: d.sold > 150 ? 'red' : 'blue', // 指定 item 的颜色
        name: index === 0 ? d.genre : `${d.genre} ${data[i].genre}`, // 指定 item 的名字
        value: column.y.value[i], // 使用 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>`,
      }
    }
  }
});

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

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

({
  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: [
      {
        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>`;
      },
    },
  },
});

({
  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: [
      {
        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>`;
      },
    },
  },
});

({
  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: [
      {
        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>`;
      },
    },
  },
});

({
  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: [
      {
        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>`;
      },
    },
  },
});

({
  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: [
      {
        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>`;
      },
    },
  },
});

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

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

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

尝试一下

案例

title

{
  "tooltip": {
    "items": [
      {}
    ]
  }
}

item

null;

title + item

{
  "tooltip": {
    "items": [
      {
        "title": "a",
        "items": [
          {
            "channel": "x"
          },
          {
            "channel": "y"
          }
        ]
      }
    ]
  }
}

手动控制展示/隐藏

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

{
  "call": {}
}

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

隐藏的方式如下：

chart.emit('tooltip:hide');

开始/禁止交互

chart.emit('tooltip:disable');

chart.emit('tooltip:enable');

设置十字辅助线

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

设置crosshairs为true。

{
  "interaction": {
    "tooltip": {
      "crosshairs": true,
      "crosshairsXStroke": "red",
      "crosshairsYStroke": "blue"
    }
  }
}

设置crosshairsX为true。

{
  "interaction": {
    "tooltip": {
      "crosshairsX": true,
      "crosshairsXStroke": "red",
      "crosshairsYStroke": "blue"
    }
  }
}

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

设置提示点为空心圆

{
  "interaction": {
    "tooltip": {
      "markerType": "hollow"
    }
  }
}

数据标签

Label 是将图形的一些数据信息，比如值，名称等映射到图形的文本上的方法。使用方式如下:

开始使用

const config = {
  label: {
    text: 'people',
    position: 'outside',
    transform: [{ type: 'overlapDodgeY' }],
  }
}

选项（options）

Label 继承 G Text 所有属性样式配置，此外还有 position, selector, connector, background 和 transform 等更多配置。

属性	描述	类型	默认值
fontSize	文字大小	`number` \| `Function<number>`	-
fontFamily	文字字体	`string` \| `Function<string>`	-
fontWeight	字体粗细	`number` \| `Function<number>`	-
lineHeight	文字的行高	`number` \| `Function<number>`	-
textAlign	设置文本内容的当前对齐方式, 支持的属性：`center` \| `end` \| `left` \| `right` \| `start`，默认值为`start`	`string` \| `Function<string>`	-
textBaseline	设置在绘制文本时使用的当前文本基线, 支持的属性:`top` \| `middle` \| `bottom` \| `alphabetic` \| `hanging`。默认值为`bottom`	`string` \| `Function<string>`	-
fill	图形的填充色	`string` \| `Function<string>`	-
fillOpacity	图形的填充透明度	`number` \| `Function<number>`	-
stroke	图形的描边	`string` \| `Function<string>`	-
strokeOpacity	描边透明度	`number` \| `Function<number>`	-
lineWidth	图形描边的宽度	`number` \| `Function<number>`	-
lineDash	描边的虚线配置，第一个值为虚线每个分段的长度，第二个值为分段间隔的距离。lineDash 设为[0, 0]的效果为没有描边。	`[number,number]` \| `Function<[number, number]>`	-
opacity	图形的整体透明度	`number` \| `Function<number>`	-
shadowColor	图形阴影颜色	`string` \| `Function<string>`	-
shadowBlur	图形阴影的高斯模糊系数	`number` \| `Function<number>`	-
shadowOffsetX	设置阴影距图形的水平距离	`number` \| `Function<number>`	-
shadowOffsetY	设置阴影距图形的垂直距离	`number` \| `Function<number>`	-
cursor	鼠标样式。同 css 的鼠标样式，默认 'default'。	`string` \| `Function<string>`	'default'
position	标签位置配置	`string`	-
selector	标签选择器。mark 通过指定的通道分组，通过指定选择器可以针对序列进行过滤索引，从序列中提取单个或多个值。分组的默认通道是系列。	`string\|function`	-
connector	是否展示文本和目标点之间的连接线，默认不展示	`boolean`	-
background	是否展示文本背景框，默认不展示	`boolean`	-
transform	标签转换，主要用于调整标签 `(x,y)` 位置，标签偏移、对齐等属性以实现想要的标签效果，内置多种标签布局，同时也支持回调的方式处理	`array\|function`	-
formatter	标签文本格式化	`type Formatter = (text:string, datum: Datum, index:number, data: Data) => string`	-

标签连接线样式配置，格式为: connector${style}, 如: connectorStroke 代表连接线描边色。

参数	说明	类型	默认值
connectorStroke	连接线描边色	`string`	-
connectorLineWidth	连接线描边线宽	`number`	-
`connector${style}`	更多连接线样式配置，参考 `PathStyleProps` 属性值	-	-

标签文本背景框样式配置，格式为: background${style}, 如: backgroundFill 代表背景框填充色。

参数	说明	类型	默认值
backgroundFill	背景框填充色	`string`	-
backgroundRadius	背景框圆角半径	`number`	-
backgroundPadding	背景框内间距	`number[]`	-
`background${style}`	更多背景框样式配置，参考 `RectStyleProps` 属性值	-	-

数据标签支持使用 HTML 自定义标签，具体配置为：

参数	说明	类型	默认值
render	返回 HTML string 或者 HTMElement，使用 HTML 自定义复杂标签	`RenderFunc`	-

type RenderFunc = (text: string, datum: object, index: number) => String | HTMLElement;

FAQ

支持哪些 position？

在笛卡尔坐标系下，支持 9 种位置：'top', 'left', 'right', 'bottom', 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'inside'。非笛卡尔坐标系下，支持 'outside', 'inside' 两种。

此外，针对面积图提供特殊 area，见面积图特殊标签。针对 radial 类型的图标，增加了 spider、surround 两种类型。

position	用途	使用前	使用后
`spider`	调整标签沿坐标轴边沿两端对齐，适用于 polar 坐标系
`surround`	调整标签环形环绕做坐标系，适用于 polar 坐标系下的玫瑰图
`area`	将面积图的标签显示在面积区域中心，并设置一定的旋转角度

selector 如何使用？

selector 选择器可以对系列数据进行过滤索引。

通常适用于折线图、面积图等一个几何图形会对应一组数据的 mark

内置选择器有：'last', 'first'，同时也支持 function 回调的方式自定义，如下：

{
  selector: (data) => {
    if (data.length) {
      // 对于每个系列的数据，只保留索引等于 2 的标签
      return data.filter((d, index) => index === 2);
    }
    return data;
  };
}

详见选项

更多

通用配置

图表组件

标题 title

坐标轴 axis

图例 legend

滚动条 scrollbar

缩略轴 slider

提示信息 tooltip

数据标签 label

图表布局

使用方式

视图模型

布局算法

动态计算

防挤压机制

配置项

autoFit

viewStyle

view

plot

main

content

坐标轴

概述

构成元素

使用方式

配置层级

隐藏坐标轴

配置项

title

line

tick

label

grid

animate

事件

示例

图例

概述

构成元素

使用方式

配置层级

配置项

orientation

position

layout

size

width

crossPadding

order

title

cols

colPadding

rowPadding

maxRows

maxCols

itemMarker

Symbols 可选类型

itemLabel

itemValue

itemBackground

itemWidth

itemSpan

itemSpacing

nav

color

block

type

ribbon

handle

label

indicator

事件

示例

自定义图例项图标（itemMarker）

自定义符号（Symbol）

使用图片

自定义图例（Legend）

滚动条