Annotations

2 min read

🏷️ Annotation,as an auxiliary element of the chart, it is mainly used to identify additional mark notes on the plot.

🎨 Go to AntV 设计 | 标注 Annotation of 墨者学院 to learn more about Design guide

Types of annotations

annotation

G2Plot 提供了以下图形标注类型:

类型描述预览用法
arc辅助弧线,只在极坐标系下生效。常用于绘制仪表盘。image.png{ type: 'arc' } 
image辅助图片,在图表上添加辅助图片。image.png{ type: 'image' }
line辅助线(可带文本),例如表示平均值或者预期分布的直线。image.png{ type: 'line' }
text辅助文本,指定位置添加文本说明。image.png{ type: 'text' }
region辅助框,框选一段图区,设置背景、边框等。image.png{ type: 'region' }
regionFilter区域着色,将图表中位于矩形选区中的图形元素提取出来,重新着色。image.png{ type: 'regionFilter' }
dataMarker特殊数据点标注,多用于折线图和面积图。image.png{ type: 'dataMarker' }
dataRegion特殊数据区间标注,多用于折线图和面积图。image.png{ type: 'dataRegion' }
html自定义 HTML 标注,新增 🆕 。-{ type: 'html' }
shape自定义 shape 标注,新增 🆕 。-{ type: 'shape' }

Usage

annotations is an array type, and multiple annotations can be set.

annotations: [
  {
    type: 'text',
    position: ['median', 'median'],
    content: 'Content',
    style: {
      fill: 'red',
    },
  },
];

Details of configuration:

Annotations are array types and can be set multiple times.

annotations: [
  {
    type: 'text',
    position: ['median', 'median'],
    content: '辅助文本',
    style: {
      fill: 'red',
    },
  },
];

💠 Text Annotation

type
optional string

需要指定 type: 'text', 标识为:辅助文本,在指定位置添加文本说明。

position
required [string, string] | Datum | ((xScale, yScales) => [string, string])

文本标注位置。

Example

x
optional number

文本标注位置 x,需要搭配 y 属性配置。不建议使用,建议使用 position

y
optional number

文本标注位置 y,需要搭配 x 属性配置。不建议使用,建议使用 position

content
optional string

Text annotations 的文本标注内容。

rotate
optional number

文本的旋转角度,弧度制。顺时针旋转。

offsetX
optional number

文本在 x 轴方向的偏移量。

offsetY
optional number

文本在 y 轴方向的偏移量。

style
optional object

文本标注样式,参考绘图属性

background
optional object

文字包围盒样式设置。

参数名类型描述
styleobject文本背景的样式, 参考绘图属性
paddingnumber | number[]文本背景周围的留白
maxLength
optional number

文文本的最大长度。

autoEllipsis
optional boolean

超出 maxLength 是否自动省略。

ellipsisPosition
optional head | middle | tail

文本截断的位置。

isVertical
optional boolean

文本在二维坐标系的显示位置,是沿着 x 轴显示 还是沿着 y 轴显示。

💠 Line Annotation

type
optional string

需要指定 type: 'line', 标识为:辅助线(可带文本),例如表示平均值或者预期分布的直线。

start
optional AnnotationPosition

起始位置,一般用于 line、region 等。

AnnotationPosition 类型定义如下:

type AnnotationPositionCallback = (
  xScales: Scale[] | Record<string, Scale>,
  yScales: Scale[] | Record<string, Scale>
) => [number | string, number | string];

// types of annotation
type AnnotationPosition =
  | [number | string, number | string]
  | Record<string, number | string>
  | AnnotationPositionCallback;

除了指定原始数据之外,还可以使用预设定数据点,如:

  • 'min': 最小值,minimum value.
  • 'max': 最大值,maximum value.
  • 'mean': 平均值,average value.
  • 'median': 中位值,median value.
  • 'start': 即 0.
  • 'end': 即 1.

Example

end
optional AnnotationPosition

结束位置,一般用于 line、region 等。具体配置属性参考: start

style
optional object

辅助线样式属性,参考绘图属性

text
optional LineAnnotationTextCfg

辅助线上的文本设置。

LineAnnotationTextCfg 类型定义如下:

type LineAnnotationTextCfg = {
  /** 文本内容*/
  content?: string;
  /** 自动旋转,沿着线的方向,默认 true */
  autoRotate?: boolean;
  /** 文本的偏移 x */
  offsetX?: number;
  /** 文本的偏移 y */
  offsetY?: number;
  /** 字体样式,参考绘图属性 */
  style?: object;
};

Example

top
optional boolean

指定 annotation 是否绘制在 canvas 最上层,默认为 false, 即绘制在最下层。

offsetX
optional number

x 轴方向的偏移量。

offsetY
optional number

y 轴方向的偏移量。

animate
optional boolean

是否进行动画。

animateOption
optional object

动画参数配置,当且仅当 animate 属性为 true,即动画开启时生效。,参考动画参数配置

💠 Arc Annotation

type
optional string

需要指定 type: 'arc', 标识为:辅助弧线,只在极坐标系下生效。常用于绘制仪表盘。

start
optional AnnotationPosition

起始位置,一般用于 line、region 等。

AnnotationPosition 类型定义如下:

type AnnotationPositionCallback = (
  xScales: Scale[] | Record<string, Scale>,
  yScales: Scale[] | Record<string, Scale>
) => [number | string, number | string];

// types of annotation
type AnnotationPosition =
  | [number | string, number | string]
  | Record<string, number | string>
  | AnnotationPositionCallback;

除了指定原始数据之外,还可以使用预设定数据点,如:

  • 'min': 最小值,minimum value.
  • 'max': 最大值,maximum value.
  • 'mean': 平均值,average value.
  • 'median': 中位值,median value.
  • 'start': 即 0.
  • 'end': 即 1.

Example

end
optional AnnotationPosition

结束位置,一般用于 line、region 等。具体配置属性参考: start

style
optional object

辅助线样式属性,参考绘图属性

💠 Image Annotation

type
optional string

需要指定 type: 'image', 标识为:辅助图片,在图表上添加辅助图片。

src
optional string

图片路径,用于 image 中。

position
optional [string, string] | Datum | ((xScale, yScales) => [string, string])

图片标注位置。

Example

start
optional AnnotationPosition

起始位置,需搭配 end 使用,也可以直接只使用 position。具体配置属性参考 Line Annotation start 配置。

除了指定原始数据之外,还可以使用预设定数据点,如:

  • 'min': 最小值,minimum value.
  • 'max': 最大值,maximum value.
  • 'mean': 平均值,average value.
  • 'median': 中位值,median value.
  • 'start': 即 0.
  • 'end': 即 1.

Example

end
optional AnnotationPosition

结束位置,需搭配 start 使用,也可以直接只使用 position。具体配置属性参考: start

style
optional object

图片标注样式,可以设置图片标注的宽度和高度,如下:

annnotations: [{
  type: 'image',
  src: 'xxx',
  style: {
    width: 50,
    height: 50,
  }
}]
top
optional boolean

指定 annotation 是否绘制在 canvas 最上层,默认为 false, 即绘制在最下层。

offsetX
optional number

x 轴方向的偏移量。

offsetY
optional number

y 轴方向的偏移量。

animate
optional boolean

是否进行动画。

animateOption
optional object

动画参数配置,当且仅当 animate 属性为 true,即动画开启时生效。,参考动画参数配置

💠 Region Annotation

type
optional string

需要指定 type: 'region', 标识为:辅助框,框选一段图区,设置背景、边框等。

start
optional AnnotationPosition

起始位置,一般用于 line、region 等。

AnnotationPosition 类型定义如下:

type AnnotationPositionCallback = (
  xScales: Scale[] | Record<string, Scale>,
  yScales: Scale[] | Record<string, Scale>
) => [number | string, number | string];

// types of annotation
type AnnotationPosition =
  | [number | string, number | string]
  | Record<string, number | string>
  | AnnotationPositionCallback;

除了指定原始数据之外,还可以使用预设定数据点,如:

  • 'min': 最小值,minimum value.
  • 'max': 最大值,maximum value.
  • 'mean': 平均值,average value.
  • 'median': 中位值,median value.
  • 'start': 即 0.
  • 'end': 即 1.

Example

end
optional AnnotationPosition

结束位置,一般用于 line、region 等。具体配置属性参考: start

style
optional object

辅助线样式属性,参考绘图属性

top
optional boolean

指定 annotation 是否绘制在 canvas 最上层,默认为 false, 即绘制在最下层。

offsetX
optional number

x 轴方向的偏移量。

offsetY
optional number

y 轴方向的偏移量。

animate
optional boolean

是否进行动画。

animateOption
optional object

动画参数配置,当且仅当 animate 属性为 true,即动画开启时生效。,参考动画参数配置

💠 DataMarker Annotation

type
optional string

需要指定 type: 'dataMarker', 标识为:特殊数据点标注,多用于折线图和面积图。

position
required [string, string] | Datum | ((xScale, yScales) => [string, string])

DataMarker 标注位置,参考 Text Annotation 标注的 position 设置。

Example

point
optional null | DataMarkerPointCfg

point 设置。当设置为:null 时,不展示 point 点标识。

DataMarkerPointCfg 类型定义如下:

// 当前只支持对 point 的样式进行设置。
type DataMarkerPointCfg = {
  style?: ShapeAttrs;
}
line
optional null | DataMarkerLineCfg

line 设置。当设置为:null 时,不展示 line 标识。

DataMarkerLineCfg 类型定义如下:

// 当前只支持对 line 的样式以及长度进行设置。
type DataMarkerPointCfg = {
  style?: ShapeAttrs;
  length?: number;
}
text
optional null | AnnotationTextCfg

DataMareker 辅助标记上的文本设置。当设置为:null 时,不展示文本标识。

AnnotationTextCfg 类型定义如下:

// 当前只支持对 line 的样式以及长度进行设置。
type AnnotationTextCfg = {
  /** 文本内容*/
  content?: string;
  /** 自动旋转,沿着线的方向,默认 true */
  autoRotate?: boolean;
  /** 文本的偏移 x */
  offsetX?: number;
  /** 文本的偏移 y */
  offsetY?: number;
  /** 字体样式,参考绘图属性 */
  style?: object;
};
autoAdjust
optional boolean

文本超出绘制区域时,是否自动调节文本方向。

direction
optional upward | downward

朝向。

`markdown:docs/common/annotations/base-annotation.zh.md`

💠 DataRegion Annotation

type
optional string

需要指定 type: 'dataRegion', 标识为:特殊数据区间标注,多用于折线图和面积图。

position
required [string, string] | Datum | ((xScale, yScales) => [string, string])

DataMarker 标注位置,参考 Text Annotation 标注的 position 设置。

Example

lineLength
number optional default: 0

line 长度。

region
null | { style?: ShapeAttrs } optional default: 0

标注区间的配置。点击 ShapeAttrs 查看详细样式配置。

text
null | EnhancedTextCfg optional default: 0

文本的配置。

top
optional boolean

指定 annotation 是否绘制在 canvas 最上层,默认为 false, 即绘制在最下层。

offsetX
optional number

x 轴方向的偏移量。

offsetY
optional number

y 轴方向的偏移量。

animate
optional boolean

是否进行动画。

animateOption
optional object

动画参数配置,当且仅当 animate 属性为 true,即动画开启时生效。,参考动画参数配置

💠 Region Annotation

type
optional string

需要指定 type: 'regionFilter', 标识为:区域着色,将图表中位于矩形选区中的图形元素提取出来,重新着色。

start
optional AnnotationPosition

起始位置,一般用于 line、region 等。

AnnotationPosition 类型定义如下:

type AnnotationPositionCallback = (
  xScales: Scale[] | Record<string, Scale>,
  yScales: Scale[] | Record<string, Scale>
) => [number | string, number | string];

// types of annotation
type AnnotationPosition =
  | [number | string, number | string]
  | Record<string, number | string>
  | AnnotationPositionCallback;

除了指定原始数据之外,还可以使用预设定数据点,如:

  • 'min': 最小值,minimum value.
  • 'max': 最大值,maximum value.
  • 'mean': 平均值,average value.
  • 'median': 中位值,median value.
  • 'start': 即 0.
  • 'end': 即 1.

Example

end
optional AnnotationPosition

结束位置,一般用于 line、region 等。具体配置属性参考: start

style
optional object

辅助线样式属性,参考绘图属性

color
optional string

染色色值,一般用于 regionFilter。

apply
optional string[]

设定 regionFilter 只对特定 geometry 类型起作用,如 apply: ['area'],一般用于 regionFilter。

top
optional boolean

指定 annotation 是否绘制在 canvas 最上层,默认为 false, 即绘制在最下层。

offsetX
optional number

x 轴方向的偏移量。

offsetY
optional number

y 轴方向的偏移量。

animate
optional boolean

是否进行动画。

animateOption
optional object

动画参数配置,当且仅当 animate 属性为 true,即动画开启时生效。,参考动画参数配置

💠 Html Annotation

type
optional string

需要指定 type: 'html',。自定义任意 HTML 类型的图形标记,通过 option 中的 html 配置来在图表中使用 HTML DOM 元素来添加图形标记。option 配置如下:

container
string | HTMLElement optional

可选,自定义 HTML 图形标记的容器元素

html
string | HTMLElement | ((container: HTMLElement, view: View) => void | string | HTMLElement)

自定义的图形标记的 HTML 元素,可为 HTML DOM 字符串,或 HTML 元素,或 html 回调函数

alignX
'left' | 'middle' | 'right' optional default: 'left'

DOM 元素在 X 方向的对齐方式

alignY
'top' | 'middle' | 'bottom' optional default: 'top'

DOM 元素在 Y 方向的对齐方式

offsetX
number optional

X 方向的偏移

offsetY
number optional

Y 方向的偏移

💠 Shape Annotation

type
optional string

需要指定 type: 'shape',。自定义任意类型的图形标记,通过 option 中的 render 回调函数来在图表区域绘制自定义标记。option 配置如下:

render
( container: IGroup, view: View, helpers: { parsePosition: (position: [string | number, string | number] | Datum) => Point } ) => void

自定义标记的绘制 render 函数,其他 container 为标记绘制的父容器, view 为图形实例, helpers 为辅助函数,其他 parserPosition 可以用来计算数据点对应的坐标位置

top
optional boolean

指定 annotation 是否绘制在 canvas 最上层,默认为 false, 即绘制在最下层。

offsetX
optional number

x 轴方向的偏移量。

offsetY
optional number

y 轴方向的偏移量。

animate
optional boolean

是否进行动画。

animateOption
optional object

动画参数配置,当且仅当 animate 属性为 true,即动画开启时生效。,参考动画参数配置