Sunburst

5 min read

Plot Container

width

optional number default: 400

Set the width of the chart.

height

optional number default: 400

Set the height of the chart.

autoFit

optional boolean default: true

Whether the chart automatically adjusts to fit the container. If it is set to true, width and height configuration would fail.

padding

optional number[] | number | 'auto'

Set padding value of the canvas. You can also use auto.

appendPadding

optional number[] | number

Extra appendPadding value.

renderer

optional string default: canvas

Set the render way to canvas or svg.

pixelRatio

optional number default: window.devicePixelRatio

Set the pixel ratio of the chart.

limitInPlot

optional boolean

Whether clip the Geometry beyond the coordinate system。

supportCSSTransform

optional boolean

支持 CSS transform,开启后图表的交互以及事件将在页面设置了 css transform 属性时生效,默认关闭。

useDeferredLabel

optional boolean|number

开启后 label 渲染会在浏览器空闲时机执行。可制定具体 number 数值,来限定 timeout 时间 (建议开启时,指定 timeout 时间)

locale

optional string

Specify the locale. There are two built-in locales: 'zh-CN' and 'en-US'. Or you can use G2Plot.registerLocale to register a new locale. Go src/locales/en_US.ts to see the format.

Data Mapping

data

required object

Configure the chart data source. 旭日图的数据格式要求为:

type Node = { name: string; value?: number; children: Node[]; }

示例:

{
  name: 'root',
  children: [
    { name: 'type1', value: 1 },
    { name: 'type2', value: 3, children: [{ name: 'type2-1', value: 2 }] }
  ]
}

meta

optional object

Configure the meta of each data field of the chart in global, to define the type and presentation of data. Configuration of the meta will affect the text content of all components.

PropertiesTypeDescription
aliasstringalias of the data field
formatterfunctioncallback function to format all values of the data field
valuesstring[]enumerate all the values of the data field
rangenumber[]mapping range of the data field, default: [0,1]

See also the Meta Options to learn more about configuration of meta.

Built-in fields of Sunburst:

| Field key | Description of field | Type of value | | --- | --- | --- | |Sunburst.SUNBURST_PATH_FIELD| Path of current node, up the tree to the least common ancestor, and back down to the given node |string | |Sunburst.SUNBURST_ANCESTOR_FIELD| Ancestor node of current node | string | |Sunburst.NODE_ANCESTORS_FIELD| Ancestor nodes of current node |object[] | |nodeIndex| Index of nodes at the same level |number | | childNodeCount | Counts of current node's childNodes |number | |depth| |number | |height| | number |

这些字段可以在元数据中获取(tooltip、style 回调中使用).

可以通过下面的方式来设置字段的元信息:

meta: {
  [Sunburst.SUNBURST_PATH_FIELD]: {
    alias: '节点路径',
    formatter: (v) => `🌞 ${v}`,
  },
  [Sunburst.SUNBURST_ANCESTOR_FIELD]: {
    alias: '祖先节点',
  },
  depth: {
    alias: '节点层级',
  },
},

colorField

optional string

Color mapping field.

颜色映射字段。默认为:Sunburst.SUNBURST_ANCESTOR_FIELD,即节点的祖先节点,颜色透明度逐渐减小(可以通过 sunburstStyle 回调来控制填充透明度)

rawFields

optional string[]

额外的原始字段。配置之后,可以在 tooltip,sunburstStyle 等回调函数的 datum 参数中,获取到更多额外的原始数据。

Geometry Style

hierarchyConfig ✨

optional object

Hierarchy configuration, such as' size ', 'padding', etc., refer to D3-Hierarchy for detailed configuration.

支持配置属性:

PropertiesTypeDescription
fieldstring数据节点权重映射字段,默认为:value. 当你的节点数据格式不是:{ name: 'xx', value: 'xx' }, 可以通过该字段来指定,详细见: 图表示例
activeDepthnumber默认展示的层级深度。默认空,代表全部展示。 取值范围为: [1, ∞),详细见:图表示例
paddingnumber|number[]默认:0。参考:d3-hierarchy#partition_padding
sizenumber[]默认:[1, 1]。参考:d3-hierarchy#partition_size
roundboolean默认:false。参考:d3-hierarchy#partition_round
sortFunction数据节点排序方式,默认:降序。参考: d3-hierarchy#node_sort
ignoreParentValueboolean是否忽略 parentValue, 默认:true。 当设置为 true 时,父节点的权重由子元素决定

radius

optional string default: 0.85

Radius, 0~1 of the value.

innerRadius

optional number default: 0

Inner radius, 0~1 of the value.

color

optional string | string[] | Function

Configure the color. If there is no colorField configured, set one single color. Otherwise you can set a series of colors, or you can use callback function.

Default: The color board of the theme.

// set one single color
{
  color: '#a8ddb5'
}
// set a series of colors
{
  colorField: 'type', // or seriesField in some cases
  color: ['#d62728', '#2ca02c', '#000000'],
}
// Function
{
  colorField: 'type', // or seriesField in some cases
  color: ({ type }) => {
    if(type === 'male'){
      return 'red';
    }
    return 'yellow';
  }
}

pattern ✨

optional object | Function

Set the pattern style of the geometries.

  • PatternOption: consists of type and cfg, type includes: dot, line, square, cfg is optional.
  • Features: pattern will override the style of geometry (such as pieStyle, columnStyle, etc.).
  • Usage: You can set a uniform pattern style for all geometries of the chart by using configuration (PatternOption) or CanvasPattern object, and a callback is provided to set the pattern for each geometry. In addition, we provide getCanvasPattern function, pass in the PatternOption to create the pattern to modify the Legend stylesDemo

The type of pattern is defined as follows:

PatternAttr =
  | CanvasPattern
  | PatternOption
  | ((datum: Datum, color: string /** inherit color */) => PatternOption | CanvasPattern);

Usage:

// set a uniform pattern style for all geometries
{
   pattern: {
    type: 'dot',
    cfg: {
      size: 4,
      padding: 4,
      rotation: 0,
      fill: '#FFF',
      isStagger: true,
    },
  },
}
// set the pattern for each geometry
{
  pattern: ({type}, color) =>{
    if(type ==='分类一') {
      return { 
        type: 'dot',
        cfg: {
          backgroundColor: color, // inherit color
        }
      }
    } else if(type ==='分类二') {
      return {
         type: 'square',
         cfg: {
           backgroundColor: 'pink', // custom color
         }
       }
    } else if(type ==='分类三') {
      return { 
        type: 'line' 
      }
    }
  },
}

Common configuration(cfg) for all types of pattern:

AttributeTypeDescription
backgroundColorstringBackground color of the pattern
fillstringFill color of the symbol in pattern
fillOpacitynumberTransparency of the symbol in pattern
strokestringStroke color of the symbol in pattern
strokeOpacitynumberStroke opacity of the symbol in pattern
lineWidthnumberThe thickness of the symbol's stroke
opacitynumberOverall transparency of the pattern
rotationnumberRotation angle of the pattern

Additional configuration for dotPattern

AttributeTypeDescription
sizenumberThe size of the dot, default: 6
paddingnumberThe distance between dots, default: 2
isStaggerbooleanStaggered dots. default: true

Additional configuration for linePattern

AttributeTypeDescription
spacingnumberThe distance between the two lines, default: 5

Additional configuration for squarePattern

AttributeTypeDescription
sizenumberThe size of the square, default: 6
paddingnumberThe distance between squares, default:1
isStaggerbooleanStaggered squares. default:true

sunburstStyle

optional object

Sunburst graphic style. 旭日图默认随着层级增加,而逐渐减小填充透明度,可以通过 sunburstStyle 回调来控制填充透明度,详细见:图表示例

Default configuration:

PropertiesTypeDescription
fillstringFill color
strokestringStroke color
lineWidthnumberLine width
lineDashnumberThe dotted lines show
opacitynumberTransparency
fillOpacitynumberFill transparency
strokeOpacitynumberStroke transparency
// Specified directly
{
  sunburstStyle: {
    fill: 'red',
    stroke: 'yellow',
    opacity: 0.8
  },
}
// Function
{
  sunburstStyle: (datum) => {
    if (datum.value === 0.5) {
      return {
        fill: 'green',
        stroke: 'yellow',
        opacity: 0.8,
      }
    }
    return {
      fill: 'red',
      stroke: 'yellow',
      opacity: 0.8,
    }
  }
}

reflect

optional x | y

Radial type, not recommended in special cases. 在旭日图中,不可使用 reflect: 'x' 进行 x 轴反转,使用 reflect: 'y' 进行 y 轴反转后,祖先节点在最外层,从外至内依次:父节点 - 孩子节点 - 孙子节点

Plot Components

label

PropertiesTypeDescription
typestringWhen a user uses a custom label type, need to declare the specific type, otherwise you will use the default label type rendering (pie chart label support inner | outer | spiders)
offsetnumberlabel offset
offsetXnumberThe offset distance of the label from the data point in the X direction
offsetYnumberThe offset distance of the label from the data point in the Y direction
contentstring | IGroup | IShape | GeometryLabelContentCallbackText content that is displayed, if not declared, is displayed according to the value of the first field participating in the mapping
styleShapeAttrsLabel text graphic property style
autoRotatestringWhether to rotate automatically, default true
rotatenumberText rotation angle, unit is radian, clockwise rotation
labelLinenull | boolean | LabelLineCfgUsed to set the style property of the text connector. NULL indicates that it is not displayed.
labelEmitbooleanOnly applies to text in polar coordinates, indicating whether the text is radially displayed according to the angle. True means on and false means off
layout'overlap' | 'fixedOverlap' | 'limitInShape'Text layout type, support a variety of layout function combination.
position'top' | 'bottom' | 'middle' | 'left' | 'right'Specifies the position of the current Label relative to the current graphic (💡 Attention: Only works for column plot and bar plot, which geometry is interval)
animateboolean | AnimateOptionAnimation configuration.
formatterFunctionFormat function
autoHidebooleanWhether to hide it automatically, default to false

Types of LabelLineCfg are as follow: (Go ShapeAttrs see more details about ShapeAttrs)

type LabelLineCfg = {
  style?: ShapeAttrs;
}

Example code:

{
  label: {
    style: {
      fill: 'red',
      opacity: 0.6,
      fontSize: 24
    }
  }
}

tooltip

fields
optional string[]

Specifies the fields to be displayed in the Tooltip. By default, different charts have different default field lists. Use with the 'formatter' configuration for more effect.

tooltip: {
  fields: ['x', 'y'],
}
formatter
optional Function

Formats the contents of the Tooltip Item (you can use customContent when content contains multiple tooltipItems).

tooltip: {
  formatter: (datum: Datum) => {
    return { name: datum.x, value: datum.y + '%' };
  },
}
follow
optional boolean default: true

Sets whether the Tooltip content box follows the mouse.

enterable
optional boolean default: false

Whether the tooltip allows mouse to slide in.

showTitle
optional boolean default: false

Whether show tooltip title.

title
optional string

Set the title content of the Tooltip: If the value is the name of the data field, the value for the field in the data is displayed, and if the field does not exist in the data, the title value is displayed directly.

position
optional top | bottom | left | right

Sets the fixed display location of the Tooltip relative to the data point.

shared
optional boolean

True means that all data corresponding to the current point is merged and displayed, while false means that only the data content closest to the current point is displayed.

showCrosshairs
optional boolean default: false

Whether show crosshairs。

crosshairs
optional object

Configure tooltip crosshairs to work if and only if 'showCrosshairs' is true.

PropertiesTypeDescription
type'x' | 'y' | 'xy'Crosshairs Type: 'X' represents the auxiliary line on the X axis, 'Y' on the Y axis
linelineStyleThe configuration item for line, see more ShapeAttrs
textTooltipCrosshairsText | TooltipCrosshairsTextCallbackText configuration of crosshairs pointer, support callback
textBackgroundtextBackgroundStyleGuideline text background configuration
followbooleanWhether the guide line follows the mouse. Default is false, that is, to locate the data point

TooltipCrosshairsText 类型定义如下:

/** 辅助线文本配置 */
type TooltipCrosshairsText = {
  /**
   * 文本位置,只支持 start, end
   * @type {string}
   */
  position?: string;
  /**
   * 文本内容
   */
  content?: string;
  /**
   * 距离线的距离
   * @type {number}
   */
  offset?: number;
  /**
    * 是否自动旋转
    * @type {boolean}
    */
  autoRotate?: boolean;
  /**
    * 文本的配置项
    * @type {ShapeAttrs}
    */
  style?: TextStyle;
}

其中,TextStyle 类型定义详见: 通用文本样式

TooltipCrosshairsTextCallback 类型定义如下:

/**
 * 辅助线文本回调函数
 * @param type 对应当前 crosshairs 的类型,值为 'x' 或者 'y'
 * @param defaultContent 对应当前 crosshairs 默认的文本内容
 * @param items 对应当前 tooltip 内容框中的数据
 * @param currentPoint 对应当前坐标点
 * @returns 返回当前 crosshairs 对应的辅助线文本配置
 */
type TooltipCrosshairsTextCallback = (type: string, defaultContent: any, items: any[], currentPoint: Point) => TooltipCrosshairsText;

TextBackgroundStyle

PropertiesTypeDescription
paddingnumber | number[]White space around the background of a text
styleshapeStyleThe configuration item for line, see more ShapeAttrs
showMarkers
optional boolean default: true

Whether to render TooltipMarkers.

marker
optional ShapeAttrs

TooltipMarker style configuration.

Please refer to the style configuration ShapeAttrs

showContent
optional boolean default: false

Whether to display the Tooltip content box.

container
optional string|HTMLElement

Custom tooltip container.

containerTpl
optional string

Templates used to specify the legend container must include the classes of each DOM node when customizing the template

itemTpl
optional string

The default template for each record, which must include the classes of each DOM node when customizing the template.

domStyles
optional TooltipDomStyles

The styles for each DOM.

dom-styles
/** Tooltip content box css style */
{
  domStyles: {
    'g2-tooltip'?: CSSProperties;
    'g2-tooltip-title'?: CSSProperties;
    'g2-tooltip-list'?: CSSProperties;
    'g2-tooltip-list-item'?: CSSProperties;
    'g2-tooltip-marker'?: CSSProperties;
    'g2-tooltip-value'?: CSSProperties;
    'g2-tooltip-name'?: CSSProperties;
  }
}
offset
optional number

Tooltip offset.

reversed
optional boolean

是否将 tooltip items 逆序.

showNil
optional boolean

是否显示空值的 tooltip 项

customItems ✨
optional Function

在 tooltip 渲染之前,对最终的 items 进行自定义处理(比如排序、过滤、格式化等)。

{
  tooltip: {
    customItems: (originalItems: TooltipItem[]) => {
      // process originalItems, 
      return originalItems;
    };
  }
}
customContent
optional Function

Support for custom templates. Live demo

{
  tooltip: {
    customContent: (title, data) => {
      return `<div>${title}</div>`;
    };
  }
}

annotations

详细配置见:各 Annotation 配置项说明。

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,即动画开启时生效。,参考动画参数配置

Plot Interactions

Built-in interactions of Sunburst are as follows:

InteractionDescriptionConfiguration
drill-down用于下钻交互,配置该交互后,点击可下钻。drilldown: { enabled: true }

drilldown

optional DrillDownCfg

下钻交互配置。

DrillDownCfg 类型定义如下:

属性类型描述
enabledboolean是否开启下钻交互,默认为:'false'
breadCrumbBreadCrumbCfg下钻交互的面包屑 UI 配置

BreadCrumbCfg 类型定义如下:

属性类型描述
positionstring位置。可选项:'top-left'
rootTextstring根节点的文案,默认:'Root'(中文:'初始')
dividerTextstring分割线,默认:'/'
textStyleShapeAttrs字体样式
activeTextStyleShapeAttrs激活字体样式

添加交互

// 开启「鼠标移入图表元素(柱状图的柱子、点图的点等)时触发 active」的交互
interactions: [{ type: 'element-active' }]

// 开启多个交互
interactions: [{ type: 'element-active' }, { type: 'brush' }]

配置交互

通过 cfg 可以对交互行为进行配置,详细参考 G2 | 修改交互的默认交互

// 修改 tooltip 触发事件
interactions: [
  { 
    type: 'tooltip',
    cfg: { start: [{ trigger: 'element:click', action: 'tooltip:show' }] } 
  }
]

移除交互

// 方式1: 关闭 tooltip 交互
interactions: [{ type: 'tooltip', enable: false }]

// 方式2:
plot.chart.removeInteraction('interaction-type');

使用示例:

// 移除 图例筛选 交互
plot.chart.removeInteraction('legend-filter');

Plot Event

On Plot, binding events are removed by ON and OFF method.

// Bind event
plot.on('eventName', callback);
// Bind event, only trigger one time
plot.once('eventName', callback);
// Remove event
plot.off('eventName', callback);

Composition: ${componentName}:${eventName}

Element refers to the type of element to bind to, for example elementlegend-itemaxis-labelmaskplotlegend-item-namereset-button etc.

Events correspond to DOM common events, for example clickmousedownmouseupdblclickmouseentermouseoutmouseovermousemovemouseleavecontextmenu etc. And support mobile events: touchstarttouchmovetouchend

// Plot adds click events to the entire chart area
plot.on('plot:click', (...args) => {
  console.log(...args);
});

// Element to add a click event, element represents the graphic elements, graphical elements, please see: https://g2.antv.vision/en/docs/manual/concepts/element
plot.on('element:click', (...args) => {
  console.log(...args);
});

// Legend adds click events
plot.on('legend-item:click', (...args) => {
  console.log(...args);
});

// Legend name adds click event
plot.on('legend-item-name:click', (...args) => {
  console.log(...args);
});

// 给 tooltip 添加点击事件
plot.on('tooltip:show', (...args) => {
  console.log(...args);
});

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

plot.on('tooltip:change', (...args) => {
  console.log(...args);
});

// Label adds click events
plot.on('label:click', (...args) => {
  console.log(...args);
});

// Mask adds click events
plot.on('mask:click', (...args) => {
  console.log(...args);
});

// Axis-label adds click events
plot.on('axis-label:click', (...args) => {
  console.log(...args);
});

// Add click events to the annotation
plot.on('annotation:click', (...args) => {
  console.log(...args);
});

Plot Method

render()

Render the chart.

update()

optional

Update chart configuration and overwrite it without comparing difference.

Example:

plot.update({
  ...currentConfig,
  legend: false,
});

Plot Theme

Recommend to use 💄 ThemeSet to customize your theme configurations online.

Built-in Theme

Built-in defaults: 'default' and 'dark'

{
  theme: 'default', // 'dark',
}

Theme attributes

In addition to using the built-in 'default' and 'dark' themes, you can also modify some of the theme content by setting the theme properties.

The following table lists the specific properties on the configuration items that make up the topic:

PropertiesTypeDescription
defaultColorstringTheme color
paddingnumbernumber[]
fontFamilystringChart font
colors10string[]Category color palette, used when the number of categories is less than 10
colors20string[]Category color palette, used when the number of categories is greater than 10
columnWidthRationumberGeneral histogram width ratio, 0-1 range of values
maxColumnWidthnumberMaximum width of histogram, pixel value
minColumnWidthnumberMinimum width of histogram, pixel value
roseWidthRationumberRose width ratio, 0-1 range of value
multiplePieWidthRationumberMultilayer pie and loop ratio, 0-1 range values
geometriesobjectConfigure the style of each shape for each Geometry, including the default style and the style for each state
componentsobjectConfigure theme samples for axes, legends, tooltips, and annotations
labelsobjectConfigure the theme style of the label under Geometry
innerLabelsobjectConfigure Geometry to display the Labels theme style inside the graph
pieLabelsobjectConfigure the theme style of pie chart labels

usage:

{
  theme: {
    colors10: [
      '#FF6B3B',
      '#626681',
      '#FFC100',
      '#9FB40F',
      '#76523B',
      '#DAD5B5',
      '#0E8E89',
      '#E19348',
      '#F383A2',
      '#247FEA',
    ];
  }
}

Theme attributes (StyleSheet)

除了以上介绍的主题属性之外,还可以传入主题样式表来自定义主题。如果你需要对全局主题进行配置的话,对样式风格进行切换,比如更改颜色、字体大小、边框粗细等

usage:

{
  theme: {
    styleSheet: {
      fontFamily: 'Avenir';
    }
  }
}

支持的样式表属性:

PropertiesTypeDescription
backgroundColorstringBackground color
brandColorstringBrand color,默认取 10 色分类颜色色板的第一个颜色
paletteQualitative10stringQualitative palette,分类个数小于 10 时使用
paletteQualitative20stringQualitative palette,分类个数大于 10 时使用
paletteSemanticRedstringSemantic red
paletteSemanticGreenstringSemantic green
paletteSemanticYellowstringSemantic yellow
fontFamilystringfontFamily

Update theme

usage:

// example 1:
plot.update({ theme: 'dark' });

// example 2:
plot.update({ theme: { defaultColor: '#FF6B3B' } });

Custom theme

In addition, G2 provides a custom topic mechanism to define a new topic structure, allowing users to switch and define chart topics. Go G2 | Custom theme for more details.

🌰 Customize theme DEMO