图例 - Legend

阅读时间约 11 分钟

配置图例有两种方式

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

chart.legend(false); // 关闭图例

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

(field: legendOption) => View;
chart.legend({
  position: 'right',
});

第三种,对 field 字段对应的图例进行配置。

(field: string, legendOption) => View;
// 关闭某个图例,通过数据字段名进行关联
view.legend('city', false);

// 对特定的图例进行配置
view.legend('city', {
  position: 'right',
});

legendOption 配置如下:

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

legendOption.layout

'horizontal' | 'vertical' optional

布局方式: horizontal,vertical

legendOption.position

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

图例的位置。

legendOption.background

LegendBackgroundCfg optional

背景框配置项。LegendBackgroundCfg 配置如下:

参数名类型默认值描述
paddingnumber | number[]-背景的留白
styleShapeAttrs-背景样式配置项

legendOption.flipPage

boolean optional
适用于 分类图例,当图例项过多时是否进行分页。

legendOption.maxRow

number optional
适用于 分类图例,当图例项过多分页时,可以设置最大行数(仅适用于 layout: 'horizontal'),默认为:1。

legendOption.pageNavigator

LegendPageNavigatorCfg optional
适用于 分类图例,对图例分页器进行主题样式设置。LegendPageNavigatorCfg 配置如下:
参数名类型默认值描述
markerPageNavigatorMarker-分页器指示箭头配置项
textPageNavigatorText-分页器指示文本配置项

示例:

pageNavigator: {
  marker: {
    style: {
      // 非激活,不可点击态时的填充色设置
      inactiveFill: '#000',
      inactiveOpacity: 0.45,
      // 默认填充色设置
      fill: '#000',
      opacity: 0.8,
      size: 12,
    },
  },
  text: {
    style: {
      fill: '#ccc',
      fontSize: 8,
    },
  },
},

legendOption.selected ✨ 🆕

object optional

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

示例:

chart.legend('type', {
  selected: {
    分类一: true,
    分类二: false,
    分类三: false,
  },
});

legendOption.handler

ContinueLegendHandlerCfg optional
适用于 连续图例,滑块的配置项。ContinueLegendHandlerCfg 配置如下:
参数名类型默认值描述
sizenumber-滑块的大小
styleShapeAttrs-滑块的样式设置

legendOption.itemHeight

number optional
适用于 分类图例,图例的高度,默认为 null。

legendOption.itemWidth

number optional
适用于 分类图例,图例项的宽度, 默认为 null,自动计算。

legendOption.itemName

LegendItemNameCfg optional
适用于 分类图例,图例项 name 文本的配置。LegendItemNameCfg 配置如下:
参数名类型是否必选默认值描述
style((item: ListItem, index: number, items: ListItem[]) => ShapeAttrs) | ShapeAttrs-文本样式配置项
spacingnumber-图例项 marker 同后面 name 的间距
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;
};

legendOption.itemSpacing

number optional
适用于 分类图例,控制图例项水平方向的间距。

legendOption.itemValue

LegendItemValueCfg optional
适用于 分类图例,图例项 value 附加值的配置项。LegendItemValueCfg 配置如下:
参数名类型是否必选默认值描述
alignRightbooleanfalse是否右对齐,默认为 false,仅当设置图例项宽度时生效
style((item: ListItem, index: number, items: ListItem[]) => ShapeAttrs) | ShapeAttrs-文本样式配置项
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;
};

legendOption.animate

boolean optional default: true

是否开启动画开关。

legendOption.animateOption

ComponentAnimateOption optional

动画参数配置,当且仅当 animate 属性为 true,即动画开启时生效。动画配置详情如下:

ComponentAnimateOption 为组件各个动画类型配置。其中 easing 传入动画函数名称,内置默认动画函数如下表,同时也可以通过 registerAnimation 自定义动画函数。

interface ComponentAnimateOption {
  appear?: ComponentAnimateCfg; // 图表第一次加载时的入场动画
  enter?: ComponentAnimateCfg; // 图表绘制完成,发生更新后,产生的新图形的进场动画
  update?: ComponentAnimateCfg; // 图表绘制完成,数据发生变更后,有状态变更的图形的更新动画
  leave?: ComponentAnimateCfg; // 图表绘制完成,数据发生变更后,被销毁图形的销毁动画
}

interface ComponentAnimateCfg {
  duration?: number; // 动画执行时间
  easing?: string; // 动画缓动函数
  delay?: number; // 动画延迟时间
}
animation效果说明
'fade-in'fade-in.gif渐现动画。
'fade-out'fade-out.gif渐隐动画。
'grow-in-x'grow-in-x.gif容器沿着 x 方向放大的矩阵动画,多用于 G.Group 容器类进行动画。
'grow-in-y'grow-in-y.gif容器沿着 y 方向放大的矩阵动画,多用于 G.Group 容器类进行动画。
'grow-in-xy'grow-in-xy.gif容器沿着 x,y 方向放大的矩阵动画,多用于 G.Group 容器类进行动画。
'scale-in-x'scale-in-x.gif单个图形沿着 x 方向的生长动画。
'scale-in-y'scale-in-y.gif单个图形沿着 y 方向的生长动画。
'wave-in'wave-in-p.gifwave-in-r.gif划入入场动画效果,不同坐标系下效果不同。
'zoom-in'zoom-in.gif沿着图形中心点的放大动画。
'zoom-out'zoom-out.gif沿着图形中心点的缩小动画。
'path-in'path-in.gifpath 路径入场动画。
'position-update'图形位置移动动画。

legendOption.label

ContinueLegendLabelCfg optional
适用于 连续图例,文本的配置项。ContinueLegendLabelCfg 配置如下:
参数名类型是否必选默认值描述
alignstring-文本同滑轨的对齐方式
- rail : 同滑轨对齐,在滑轨的两端
- top, bottom: 图例水平布局时有效
- left, right: 图例垂直布局时有效
styleShapeAttrs-文本样式配置项
spacingnumber-文本同滑轨的距离

legendOption.marker

MarkerCfg | MarkerCfgCallback optional
适用于 分类图例,图例项的 marker 图标配置,也支持通过回调的方式设置。

MarkerCfg  配置

参数名类型默认值描述
symbolstring | function -配置图例 marker 的 symbol 形状,详见 marker.symbol 配置
styleShapeAttrs | ((style: ShapeAttrs) => ShapeAttrs)-图例项 marker 的配置项, 详见 ShapeAttrs
spacingnumber-图例项 marker 同后面 name 的间距

marker.symbol

内置一些 symbol 类型,可以指定具体的标记类型,也可以通过回调的方式返回 symbol 绘制的 path 命令

内置支持的标记类型有:"circle" | "square" | "line" | "diamond" | "triangle" | "triangle-down" | "hexagon" | "bowtie" | "cross" | "tick" | "plus" | "hyphen"

回调的方式为:(x: number, y: number, r: number) => PathCommand

type LegendItem = { name: string; value: string; } & MarkerCfg;

type MarkerCfgCallback = (name: string, index: number, item: LegendItem) => MarkerCfg;

legendOption.min

number optional
适用于 连续图例,选择范围的最小值。

legendOption.max

number optional
适用于 连续图例,选择范围的最大值。

legendOption.maxItemWidth

number optional
适用于 分类图例,图例项最大宽度设置。

legendOption.maxWidthRatio

number optional. 取值范围:[0, 1], 默认: 0.25
适用于 分类图例,图例项容器最大宽度比例(以 view 的 bbox 容器大小为参照)设置,如果不需要该配置,可以设置为 null

legendOption.maxHeightRatio

number optional. 取值范围:[0, 1], 默认: 0.25
适用于 分类图例,图例项容器最大高度比例(以 view 的 bbox 容器大小为参照)设置,如果不需要该配置,可以设置为 null

legendOption.maxWidth

number optional
适用于 分类图例,图例项容器最大宽度设置。实际上,图例项容器最大宽度的计算如下:
const viewBBox = this.view.viewBBox;
const maxWidth = Math.min(maxWidth, maxWidthRatio * viewBBox.width);

legendOption.maxHeight

number optional
适用于 分类图例,图例项容器最大高度设置。实际上,图例项容器最大宽度的计算如下:
const viewBBox = this.view.viewBBox;
const maxHeight = Math.min(maxHeight, maxHeightRatio * viewBBox.height);

legendOption.offsetX

number optional

图例 x 方向的偏移。

legendOption.offsetY

number optional

图例 y 方向的偏移。

legendOption.rail

ContinueLegendRailCfg optional
适用于 分类图例,图例滑轨(背景)的样式配置项。ContinueLegendRailCfg 配置如下:
参数名类型是否必选默认值描述
typestring-rail 的类型,color, size
sizenumber-滑轨的宽度
defaultLengthnumber-滑轨的默认长度,,当限制了 maxWidth,maxHeight 时,不会使用这个属性会自动计算长度
styleShapeAttrs-滑轨的样式

legendOption.reversed

boolean optional
适用于 分类图例,是否将图例项逆序展示。

legendOption.slidable

boolean optional
适用于 连续图例,滑块是否可以滑动。

legendOption.title

G2LegendTitleCfg optional

图例标题配置,默认不展示。G2LegendTitleCfg 配置如下:

参数名类型是否必选默认值描述
spacingnumber-标题同图例项的间距
styleShapeAttrs-文本样式配置项

legendOption.track

ContinueLegendTrackCfg optional
适用于 连续图例,选择范围的色块样式配置项。ContinueLegendTrackCfg 配置如下:
参数名类型是否必选默认值描述
styleShapeAttrs-选定范围的样式

legendOption.values

number[] optional
适用于 连续图例,选择的值。

legendOption.custom

boolean optional

是否为自定义图例,当该属性为 true 时,需要声明 items 属性。

legendOption.items

LegendItem[] optional
适用于 分类图例,用户自己配置图例项的内容。LegendItem 配置如下:
参数名类型是否必选默认值描述
idstring-唯一值,用于动画或者查找
namestringrequired-名称
valueanyrequired-
markerMarkerCfg-图形标记

MarkerCfg  配置

参数名类型默认值描述
symbolstring | function -配置图例 marker 的 symbol 形状,详见 marker.symbol 配置
styleShapeAttrs | ((style: ShapeAttrs) => ShapeAttrs)-图例项 marker 的配置项, 详见 ShapeAttrs
spacingnumber-图例项 marker 同后面 name 的间距

marker.symbol

内置一些 symbol 类型,可以指定具体的标记类型,也可以通过回调的方式返回 symbol 绘制的 path 命令

内置支持的标记类型有:"circle" | "square" | "line" | "diamond" | "triangle" | "triangle-down" | "hexagon" | "bowtie" | "cross" | "tick" | "plus" | "hyphen"

回调的方式为:(x: number, y: number, r: number) => PathCommand