Legend

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

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

如何引入图例

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

  1. const F2 =require('@antv/f2/lib/core');
  2. constLegend=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(默认)centerright
undefinedundefinedundefined
  • verticalAlign: String
    position 为 'left'、'right' 时生效,用于设置垂直方向上图例的对齐方式,可设置的值为:'top'、'middle'、'bottom',默认为 'middle',居中对齐。
middle(默认)topbottom
undefinedundefinedundefined
  • 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