Legend

F2 图例的生成是由图形语法中的图形属性决定的，我们会根据图形属性映射以及数据的类型自动生成不同类型的图例：color, size 这两个图形属性如果判断接收的参数是数据源的字段时，会自动生成不同的图例：

  • color，会赋予不同的图例项不同的颜色来区分图形，如果该字段是分类类型，则会生成离散图例，如果是连续类型，则会生成连续图例（本期未支持）
  • size，在图例上显示图形的大小 （本期未支持）

如何引入图例

如果你默认加载的是完整的 F2 代码，那么 Legend 已经注册至 Chart 类中，如果您采用动态引用的策略，那么需要先将该组件注册入 Chart 类或者 Chart 实例。

  1. const F2 = require('@antv/f2/lib/core');
  2. const Legend = require('@antv/f2/lib/plugin/legend');
  3. F2.Chart.plugins.register(Legend); // 方式一：全局注册
  4.  
  5. // 方式二：具体的 chart 实例注册
  6. const chart = new F2.Chart({
  7.   id: 'canvas',
  8.   plugins: Legend
  9. });

API

chart.legend(false)

不显示所有的图例。

chart.legend(field, false)

不显示 field 字段对应的图例。

  • field: String
    代表图例对应的数据字段名。

chart.legend(field, config)

为 field 对应的图例进行配置。如下所示：

  1. chart.legend('gender', {
  2.   position: 'right'
  3. });

  • field: String
    代表图例对应的数据字段名。

  • config: Object
    图例的配置信息，支持的属性如下：

参数

  • position: String
    设置图例的显示位置，可设置的值为：'top'、'right'、'bottom'、'left'，分别表示上、右、下、左。默认为 top。

  • align: String
    当 position 为 'top'，'bottom' 时生效，用于设置水平方向上图例的对齐方式，可设置的值为：'left'、'center'、'right' ，默认为 'left' ，左对齐。

left（默认） center right
undefined undefined undefined
  • verticalAlign: String
    当 position 为 'left'、'right' 时生效，用于设置垂直方向上图例的对齐方式，可设置的值为：'top'、'middle'、'bottom'，默认为 'middle'，居中对齐。
middle（默认） top bottom
undefined undefined undefined

  • itemWidth: Number/'auto'
    用于设置每个图例项的宽度，默认为 'auto'，即使用 F2 默认的图例布局计算 itemWidth。如果 itemWidth 为 null，则会根据每个图例项自身的宽度计算，另外用户也可以自己设置 itemWidth 的数值。

  • showTitle: Boolean
    是否显示图例标题，默认值为 false，即不展示。

  • titleStyle: Object
    图例标题的显示样式设置，详见绘图属性。

  1. titleStyle: {
  2.   textAlign: 'center', // 文本对齐方向，可取值为： start middle end
  3.   fill: '#404040', // 文本的颜色
  4.   fontSize: 12, // 文本大小
  5.   fontWeight: 'bold', // 文本粗细
  6.   textBaseline: 'top' // 文本基准线，可取 top middle bottom，默认为middle
  7. }

  • offsetX: Number
    图例 x 方向的整体偏移值，数值类型，数值单位为 'px'，默认值为 0。

  • offsetY: Number
    图例 Y 方向的整体偏移值，数值类型，数值单位为 'px'，默认值为 0。

  • titleGap: Number
    标题距离图例项的间距，默认为 12px，如果不展示标题，不生效。

  • itemGap: Number
    每个图例项水平方向上的间距，默认值为 12px。

  • itemMarginBottom: Number
    每个图例项下方留白间距，默认值为 12px。

  • wordSpace: Number
    marker 和文本之间的间距，默认值为 6px。

  • unCheckStyle: Object
    用于设置取消选中的图例 marker 以及文本的样式。默认值为：

  1. unCheckStyle: {
  2.   fill: '#bfbfbf'
  3. }
  • itemFormatter: Function
    回调函数，用于格式化图例每项的文本显示。
  1. itemFormatter(val) {
  2.   return val; // val 为每个图例项的文本值
  3. }

  • marker: String/Function/Object
    用于设置图例的 marker 样式，默认为 'circle' 即圆形。

  • String 类型
    当为 String 类型时，即表示使用 F2 默认提供的类型，支持的类型如下：

marker 类型 样式
'circle' Legend - 图7
'square' Legend - 图8
  • Object 类型
    marker 为 Object 时，可以配置 symbol、radius 以及一些绘图属性。
  1. marker: {
  2.   symbol: 'circle', // marker 的形状
  3.   radius: 5 // 半径大小
  4. }
  • Function 类型
    用于自定义 shape，使用方式如下，
  1. /**
  2.  * 自定义 marker 形状
  3.  * @param  {number} x   该 marker 的横轴坐标
  4.  * @param  {number} y   该 marker 的纵轴坐标
  5.  * @param  {number} r   该 marker 的半径大小
  6.  * @param  {object} ctx canvas 的上下文对象
  7.  * @return {null}
  8.  */
  9. marker(x, y, r, ctx) {}

以下代码绘制了如图所示的 marker：Legend - 图9

  1. chart.legend('city', {
  2.   marker(x, y, r, ctx) {
  3.     ctx.lineWidth = 2;
  4.     ctx.strokeStyle = ctx.fillStyle;
  5.     ctx.moveTo(x - r - 3, y);
  6.     ctx.lineTo(x + r + 3, y);
  7.     ctx.stroke();
  8.     ctx.arc(x, y, r, 0, Math.PI * 2, false);
  9.     ctx.fill();
  10.   }
  11. });
  • nameStyle: ObjectLegend - 图10
    用于设置图例项的文本样式，详见绘图属性。
  1. nameStyle: {
  2.   textAlign: 'center', // 文本对齐方向，可取值为： start middle end
  3.   fill: '#404040', // 文本的颜色
  4.   fontSize: '12', // 文本大小
  5.   fontWeight: 'bold', // 文本粗细
  6.   textBaseline: 'top' // 文本基准线，可取 top middle bottom，默认为middle
  7. }
  • valueStyle: Object
    用于设置图例项的文本样式，详见绘图属性。
  1. valueStyle: {
  2.   textAlign: 'center', // 文本对齐方向，可取值为： start middle end
  3.   fill: '#404040', // 文本的颜色
  4.   fontSize: '12', // 文本大小
  5.   fontWeight: 'bold', // 文本粗细
  6.   textBaseline: 'top' // 文本基准线，可取 top middle bottom，默认为middle
  7. }

  • joinString: String
    设置图例项中 name 和 value 的连接字符，默认为 ':'。

  • triggerOn: String
    图例筛选行为的触发事件，默认为 click。

  • selectedMode: String
    设置图例项的选中模式，提供两种模式：

  1. // 默认模式，多选
  2. selectedMode: 'multiple'
  3.  
  4. // 单选模式
  5. selectedMode: 'single'

  • clickable: Boolean
    设置图例项是否允许点击，默认为 true，即允许点击。

  • onClick: Function
    用于自定义鼠标点击图例项的交互，当 clickable 为 false 不生效。

  1. /**
  2.  * 自定义图例项点击事件， clickable 为 false 不生效
  3.  * @param  {object} ev 事件对象
  4.  * @return {null}
  5.  */
  6. onClick: ev => {}
  • custom: Boolean
    默认为 false，当 custom 为 true，表示不使用默认生成的图例，允许用户自定义图例，包括具体的图例项以及点击交互行为。

自定义图例时需要用户自己声明具体的图例项 items(该属性是一个对象数组，数组中每一项为一个对象类型，结构为：{ name: '', value: 12, marker:{ fill: 'red' } }, checked: true)以及图例项的 onClick 事件。

  1. chart.legend({ custom: true, items: [], onClick(){} });
  2. chart.legend('field', { custom: true, items: [], onClick(){} });

marker 的格式可以为数组或者字符串。

具体使用如下：

  1. chart.legend({
  2.   custom: true,
  3.   position: 'left',
  4.   items: [
  5.     { name: 'a1', marker: 'square', fill: 'red'},
  6.     { name: 'a2', marker: 'square', fill: 'blue'},
  7.     { name: 'a3', marker: 'square', fill: 'green'}
  8.   ]
  9. });
  10. chart.legend({
  11.   custom: true,
  12.   position: 'left',
  13.   items: [
  14.     { name: 'a1', marker: { symbol: 'square', stroke: 'red', radius: 8 }},
  15.     { name: 'a2', marker: { symbol: 'square', stroke: 'green', radius: 8 }},
  16.     { name: 'a3', marker: { symbol: 'square', stroke: 'blue', radius: 8 }}
  17.   ]
  18. });

DEMO

场景描述 demo
水平居中布局 Legend - 图11
自定义文本样式 Legend - 图12
自定义带交互的图例 Legend - 图13
marker 定制 Legend - 图14
图例单选模式 Legend - 图15
右上角图例 Legend - 图16

原文: https://antv.alipay.com/zh-cn/f2/3.x/api/legend.html