Legend

4 min read

🏷️ Legend is an auxiliary component of a plot, which uses color, size, and shape mapping, to show the symbol, color, and name of different series. You can click legends to toggle displaying series in the plot.

🎨 Go to AntV Design | 图例 Legend of 墨者学院 to learn more about Design guide

Elements

legend

Usage

There are two ways to configure legends:

Method 1, pass in the 'false' setting to close the legend.

legend: false; // close legend

Method 2, pass in LegendCfg to configure the legend as a whole.

legend: {
  layout: 'horizontal',
  position: 'right'
}

Properties - LegendCfg

PropertiesTypeDescriptionApply to
layoutstringThe layout of the legend is optional:horizontal | vertical
titleobjectLegend title configuration is not displayed by default, reference title configuration
positionstringLegend position, reference  position configuration
offsetXnumberLegends offset in the x direction.
offsetYnumberLegends offset in the y direction.
backgroundobjectBackground box configuration item.reference  background configuration
flipPagebooleanWhether to page when there are too many legend items. Classification legend
pageNavigatorobjectConfigure the style of page navigator。 Classification legend
itemWidthnumber | nullThe width of the legend item, default to null (automatically computed). Classification legend
itemHeightnumber | nullThe height of the legend, default to null. Classification legend
itemNameobjectConfigure the legend item name text.reference  itemName configuration Classification legend
itemValueobjectConfiguration item of legend item Value added value.reference  itemValue configuration Classification legend
itemSpacingnumberControls the horizontal spacing of legend items Classification legend
labelobjectA configuration item for the text.reference label configuration Classification legend
markerobjectThe configuration of the Marker icon of the legend item. Classification legend
maxWidthnumberLegend item maximum width set. Classification legend
maxHeightnumberSet the maximum height of the legend item. Classification legend
railobjectThe style configuration item for the legend slider (background).reference  rail configuration Classification legend
reversedbooleanWhether to display legend items in reverse order. Classification legend
custombooleanIf it is a custom legend, the items property needs to be declared when this property is true.
itemsobject[]The user configures the content of the legend item himself.reference items configuration
minnumberThe minimum value of the range. Continuous legend
maxnumberSelect the maximum value of the range. Continuous legend
valuenumber[]The selected value. Continuous legend
slidablebooleanWhether the slider can slide. Continuous legend
trackobjectSelect the color block style configuration item for the range.reference  track  configuration Continuous legend
handlerobjectConfiguration items for the slider.reference handler configuration Continuous legend
animatebooleanWhether to turn on the animation switch.
animateOptionobjectAnimate parameter configuration, which takes effect if and only if the animate property is true, that is, the animation is turned on, reference animateOption configuration

Details

layout
optional horizontal | vertical

Layout of legend.

title
optional G2LegendTitleCfg

Legend title configuration is not displayed by default. G2LegendTitleCfg Configuration is as follows:

PropertiesTypeDefaultDescription
titlestringContent of legend title
spacingnumber-The spacing between the title and the legend item
styleobject-Text style configuration item, refer to Graphic Style
position
optional string

The position of legend is optional:'top', 'top-left', 'top-right', 'left', 'left-top', 'left-bottom', 'right', 'right-top', 'right-bottom', 'bottom', 'bottom-left', 'bottom-right'。

offsetX
optional number

Legends offset in the x direction.

offsetY
optional number

Legends offset in the y direction.

background
optional LegendBackgroundCfg

Background box configuration item. LegendBackgroundCFG is configured as follows:

PropertiesTypeDescription
paddingnumber | number[]White space in the background
styleShapeAttrBackground style configuration, Reference Graphic Style
flipPage
optional boolean
Apply to Classification legend,whether to page when there are too many legend items. (⚠️ 暂不支持多行展示分页)
maxRow
number optional
Apply to Classification legend. You can set the maximum number of rows when legend items is flip-paged, (only applicable to 'layout:' horizontal '),default: 1.
optional object
Apply to Classification legend, configure the style of page navigator, it works when legend is in flipPage. Types of LegendPageNavigatorCfg are as follow:
PropertiesTypeDescription
marker.stylePageNavigatorMarkerStyle分页器指示箭头配置项
text.stylePageNavigatorTextStyleThe text style of page info.

Types of PageNavigatorMarkerStyle are as follow:

PropertiesTypeDefaultDescription
inactiveFillstring-Fill color of arrow marker when unclickable (inactive status).
inactiveOpacitynumber-Fill opacity of arrow marker when unclickable (inactive status).
fillstring-Default fill color of arrow marker (active status).
opacitynumber-Default fill opacity of arrow marker (active status).
sizenumber-Size of arrow marker.

Types of PageNavigatorTextStyle are as follow:

PropertiesTypeDefaultDescription
fillstring-Font color of page navigator info.
fontSizenumber-Font size of page navigator info.

Example:

pageNavigator: {
  marker: {
    style: {
      // 非激活,不可点击态时的填充色设置
      inactiveFill: '#000',
      inactiveOpacity: 0.45,
      // 默认填充色设置
      fill: '#000',
      opacity: 0.8,
      size: 12,
    },
  },
  text: {
    style: {
      fill: '#ccc',
      fontSize: 8,
    },
  },
},
itemHeight
optional number default: null
Apply to Classification legend, lengend item height, default null。
itemWidth
optional number default: null
Apply to Classification legend, legend item width, default null, automatic calculation.
itemName
optional LegendItemNameCfg
适用于 分类图例,图例项 name 文本的配置。LegendItemNameCfg 配置如下:
参数名类型默认值描述
style((item: ListItem, index: number, items: ListItem[]) => ShapeAttrs) | ShapeAttrs-
spacingnumber-
formatter(text: string, item: ListItem, index: number) => any;

其中, ShapeAttrs 详细配置见:文档ListItem 配置如下:

type ListItem = {
  /**
   * 名称 {string}
   */
  name: string;
  /**
   * 值 {any}
   */
  value: any;
  /**
   * 图形标记 {object|string}
   */
  marker?: Marker | string;
}

type Marker = {
  symbol? string;
  style?: ShapeAttrs;
  spacing?: number;
};
itemValue
optional LegendItemValueCfg
适用于 分类图例,图例项 value 附加值的配置项。LegendItemValueCfg 配置如下:
参数名类型默认值描述
alignRightbooleanfalse是否右对齐,默认为 false,仅当设置图例项宽度时生效
formatterfunction-格式化函数, (text: string, item: ListItem, index: number) => any;
style((item: ListItem, index: number, items: ListItem[]) => ShapeAttrs) | ShapeAttrs-

其中, ShapeAttrs 详细配置见:文档ListItem 配置如下:

type ListItem = {
  /**
   * 名称 {string}
   */
  name: string;
  /**
   * 值 {any}
   */
  value: any;
  /**
   * 图形标记 {object|string}
   */
  marker?: Marker | string;
}

type Marker = {
  symbol? string;
  style?: ShapeAttrs;
  spacing?: number;
};
itemSpacing
optional number
Apply to Classification legend, control the horizontal spacing of legend items.
itemMarginBottom
optional number
Apply to Classification legend, control the vertical spacing of legend items.
label
optional ContinueLegendLabelCfg
Apply to Continuous legend, a configuration item for the text, ContinueLegendLabelCfg Configuration is as follows:
PropertiesTypeDefaultDescription
alignstring-The alignment of text with the slider
- rail : Align with the slide rail, at both ends of the slide rail
- top, bottom: Legends are valid when laid out horizontally
- left, right: Legends are valid when laid out vertically
styleobject-Text style configuration item, reference Graphic Style
spacingnumber-The distance between the text and the slide
formatter(value: any) => string文本的格式化方式
marker
optional MarkerCfg
Apply to Classification legend, the configuration of the Marker icon of the legend item.
PropertiesTypeDefaultDescription
symbolMarker | MarkerCallback-The symbol shape of a legend marker is configured
styleShapeAttrs-The configuration item of legend item Marker
spacingnumber-The spacing between legend item marker and the following name

Marker The supported tag types are: circle | square | line | diamond | triangle | triangle-down | hexagon | bowtie | cross | tick | plus | hyphenMarkerCallback is (x: number, y: number, r: number) => PathCommand

DEMO of Customize legend marker.

radio ✨
optional RadioCfg
适用于 分类图例,图例项的末尾展示一个 radio 的按钮 🔘,点击可以实现“图例正选”筛选(聚焦)。
type RadioCfg = { style: ShapeAttr };
maxItemWidth
number optional
适用于 分类图例,图例项最大宽度设置。
maxWidthRatio
number optional. 取值范围:[0, 1], 默认: 0.25
适用于 分类图例,图例项容器最大宽度比例(以 view 的 bbox 容器大小为参照)设置,如果不需要该配置,可以设置为 null
maxHeightRatio
number optional. 取值范围:[0, 1], 默认: 0.25
适用于 分类图例,图例项容器最大高度比例(以 view 的 bbox 容器大小为参照)设置,如果不需要该配置,可以设置为 null
maxWidth
optional number
Apply to Classification legend, the maximum width of the legend item. 当 layout 等于 'horizontal' 时,生效,当图例项横向排布,超过最大宽度时,会结合 flipPage: true 进行分页。
maxHeight
optional number
Apply to Classification legend, the maximum height of the legend item. 当 layout 等于 'vertical' 时,生效,当图例项纵向排布,超过最大高度时,会结合 flipPage: true 进行分页。
reversed
optional boolean Apply to Classification legend, whether to display legend items in reverse order.
custom
optional boolean

If it is a custom legend, the items property needs to be declared when this property is true.

items
optional LegendItem[] Apply to Classification legend, the user configures the content of the legend item. LegendItem Configuration is as follows:
PropertiesTypeRequiredDescription
idstringUnique value for animation or lookup
namestringrequiredname
valueanyrequiredvalue
markerMarkerCfgmarker
PropertiesTypeDefaultDescription
symbolMarker | MarkerCallback-The symbol shape of a legend marker is configured
styleShapeAttrs-The configuration item of legend item Marker
spacingnumber-The spacing between legend item marker and the following name

Marker The supported tag types are: circle | square | line | diamond | triangle | triangle-down | hexagon | bowtie | cross | tick | plus | hyphenMarkerCallback is (x: number, y: number, r: number) => PathCommand

DEMO of Customize legend marker.

min
optional number
Apply to Continuous legend, select the minimum value of the range.
max
optional number
Apply to Continuous legend, select the maximum value of the range.
value
optional number[]
Apply to Continuous legend, 当前选中的范围.
selected ✨ 🆕
object optional

图例高亮状态,false 表示默认置灰,默认不设置或为 true 表示高亮,会同步进行数据的筛选展示。

示例:

legend: {
  selected: {
    '分类一': true,
    '分类二': false,
    '分类三': false,
  }
}
slidable
optional boolean default: true Apply to Continuous legend, whether the slider can slide.
rail
optional ContinueLegendRailCfg Apply to Continuous legend, a style configuration item for the legend slider (background).ContinueLegendRailCfg Configuration is as follows:
PropertiesTypeDefaultDescription
typestring-rail type: color and size, default: 'color'
sizenumber-The width of the slide rail
defaultLengthnumber-The default length of the slider, default: 100. When maxWidth,maxHeight is limited, this property is not used and the length is automatically calculated
styleobject-Slide rail style, refer to Graphic Style
rail.type='color'rail.type='size
colorsize
track
optional ContinueLegendTrackCfg Apply to Continuous legend, select the color block style configuration item for the range. ContinueLegendTrackCfg Configuration is as follows:
PropertiesTypeDefaultDescription
styleobject-Selected range of styles, reference Graphic Style
handler
optional ContinueLegendHandlerCfg Apply to Continuous legend, configuration items for slider. (暂不支持自定义)

ContinueLegendHandlerCfg is configured as follows:

PropertiesTypeDefaultDescription
sizenumber-Slider size, default: 10
styleobject-Slider configuration, reference Graphic Style