Legend

The legend for F2 is determined by the color mapping. When the data mapped to color is a cat scale(for discrete ordinal (ordered) or categorical (unordered) data), a legend is generated.

How to Register Legend Plugin

F2 has modular structure provides best tree-shaking results and package size optimization.

If you just import F2 from '@antv/f2', then it has included legend by default. But if you want a better package size optimization, you can register manually:

const F2 = require('@antv/f2/lib/core');
const Legend = require('@antv/f2/lib/plugin/legend');
// Method 1: Global Registeration
F2.Chart.plugins.register(Legend); 

// Or Method2: Registeration for a Chart instance
const chart = new F2.Chart({
  id: 'canvas',
  plugins: Legend
});

Legend Configuration

Close the Legend

`chart.legend(false)`

Just close all legends. Sometimes there will be several legends.

`chart.legend(field, false)`

field: String type, the map field of the legend.

Close the legend corresponding to the field.

Configure Legend

`chart.legend(field, config)`

field: String, the map field of the legend.
config: Object type, configuration for the axis. The properties included are as follows:

Legend `align` demos

When position is set to be 'top' or 'bottom', you can set align property:

Legend `verticalAlign` demos

When position is set to be 'left' or 'right', you can set verticalAlign property:

`itemFormatter` callback

Use this property to complete the formatted display of the legend item text. See detailed demo.

chart.legend({
  position: 'right',
  itemFormatter(val) {
    return val + ' %';
  }
});

Custom `maker`

The following describes the specific use of the marker：

When marker is a String, F2 provides the following types：marker: 'circle' or marker: 'square'
when marker is an Object, you can configure the type of marker and its style.

chart.legend({
  marker: {
    symbol: 'circle', // shape of the marker
    radius: 5 // radius of the circle
  }
});

When marker is a Function, you can customize the shape you need

chart.legend({
  /**
   * customize the shape of marker
   * @param  {number} x   x-axis of the marker
   * @param  {number} y   y-axis of the marker
   * @param  {number} r   radius of the marker
   * @param  {object} ctx context object of the canvas
   * @return {null}     
   */
  marker(x, y, r, ctx) {}
});

The following code draws a marker shown below:

chart.legend('city', {
  marker(x, y, r, ctx) {
    ctx.lineWidth = 2;
    ctx.strokeStyle = ctx.fillStyle;
    ctx.moveTo(x - r - 3, y);
    ctx.lineTo(x + r + 3, y);
    ctx.stroke();
    ctx.arc(x, y, r, 0, Math.PI * 2, false);
    ctx.fill();
  }
});

`onClick` callback

See demo.

chart.legend({
 /**
  * callback for clicking the legend, invalid when clickable is false.
  * @param  {object} event obejct
  * @return {null}
  */
 onClick: ev => {
    const { clickedItem } = ev; // get the clicked legend item
 }
});

Legend Item Interface

The Legend item implement the following interface，the image below will help you better understand:

{
  // Label that will be displayed as name
  name: String,
  
  // Label that will be displayed as value
  value: String / Number,
  
  // For marker, see Custom maker
  marker: String / Object / Function,
  
  // For setting the legend click style, if not set, the default is true
  checked: Boolean,
  
  // Fill style of the legend marker, you also can set in marker(when it is an object)
  fill: String
}

For example, use the custom legend feature to define legend items as follows:

chart.legend({
  position: 'right',
  custom: true,
  items: [
    { name: 'TYPE A', value: '73.76%',  marker: { symbol: 'square', fill: '#1890FF', radius: 4 } },
    { name: 'TYPE B', value: '22.11%', marker: { symbol: 'square', fill: '#2FC25B', radius: 4 } },
    { name: 'TYPE C', value: '2.2%', marker: { symbol: 'square', fill: '#FACC14', radius: 4 } },
    { name: 'TYPE D', value: '1.93%', marker: { symbol: 'square', fill: '#F04864', radius: 4 } }
  ],
  nameStyle: {
    fill: '#808080'
  }, // For styling the name label
  valueStyle: {
    fill: '#333',
    fontWeight: 'bold' // For styling the value label
  }
});

Custom Legend

You can use the custom legend feature to customize the display content and style of the legend, and you can also use the onClick callback to define the interaction behavior of the legend.

Below is a demo, you can click on the legend to control the display and hide of the corresponding geometry，Complete code.

chart.legend({
  custom: true,
  items: [
    { name: '个人分数', marker: 'square', fill: '#FACC14', checked: true }, 
    { name: '平均分数',
      marker: function marker(x, y, r, ctx) {
        ctx.lineWidth = 1;
        ctx.strokeStyle = ctx.fillStyle;
        ctx.moveTo(x - r - 3, y);
        ctx.lineTo(x + r + 3, y);
        ctx.stroke();
        ctx.arc(x, y, r, 0, Math.PI * 2, false);
        ctx.fill();
      },
      fill: '#000',
      checked: true
    }
  ],
  onClick(ev) {
    const item = ev.clickedItem;
    const name = item.get('name');
    const checked = item.get('checked');
    const children = item.get('children'); 
    if (checked) {
      const markerFill = children[0].attr('fill');
      const textFill = children[1].attr('fill');
      children[0].set('_originColor', markerFill); // 缓存 marker 原来的颜色
      children[1].set('_originColor', textFill); // 缓存文本原来的颜色
    }
    const geoms = chart.get('geoms');
    const canvas = chart.get('canvas');
    for (let i = 0; i < geoms.length; i++) {
      const geom = geoms[i];
      const container = geom.get('container');

      if (geom.getYScale().alias === name)
        if (!checked) {
          container.show();
          children[0].attr('fill', children[0].get('_originColor'));
          children[1].attr('fill', children[1].get('_originColor'));
        } else {
          container.hide();
          children[0].attr('fill', '#bfbfbf'); // marker 置灰
          children[1].attr('fill', '#bfbfbf'); // 文本置灰 置灰
        }
      item.set('checked', !checked);
      legendItems[findLegendItem(name)].checked = !checked;
    }
    canvas.draw();
  }
});