ECharts 图例组件

我们之前看到的图表基本上都是同一个内容不同时间的变化展示，当时当我们需要将多条数据放在同一个图表中进行观察比较时，我们如何才能区分哪个代表哪个呢？所以我们就需要下面将要讲到的这个组件来帮助我们进行区分，让错综复杂的图表变得直观一些。

1. 简介

官方定义：

图例组件展现了不同系列的标记(symbol)，颜色和名字。可以通过点击图例控制哪些系列不显示。ECharts 3 中单个 ECharts 实例中可以存在多个图例组件，会方便多个图例的布局。

慕课解释

图例是图表的辅助视觉引导组件，用以解释说明图表中各数据序列的含义及图表中数据的筛选。在 ECharts 中的图例在视觉上通常包含颜色、图表、图案名称两类要素，形如：

ECharts 的图例组件主要实现了两类交互功能：

1. 鼠标悬停时高亮相应图表；
2. 点击选中后，隐藏/显示相应图表。

Tips ：
图例组件的引入为使用者开放了图表显示、隐藏的控制能力，适用于图表数量较多或交互要求较高的场景。但并不是多多益善，比如在移动端这种小尺寸环境，图例会占据一定的屏幕空间，而且点击交互略为别扭，应尽量避免使用。

2. 实例解析

ECharts 中的图例通过 legend 项配置，主要包含以下几类属性：

• 用于控制图例位置大小的属性，包括 left、top、right、bottom、width、height；
• 用于设定图例样式的属性，包括 background、shadowColor、borderColor 等；
• 用于图例项大小的属性，包括 itemGap、itemWidth、itemHeight；
• 与选中功能相关的属性，包括 selected、selectedMode；
• 与选择器相关的属性，包括 selector、selectorLabel、selectorPosition、selectorItemGap、selectorButtonGap；
• 用于设定分页效果的属性，包括 scrollDataIndex、pageButtonItemGappageButtonGap、pageButtonPosition、pageFormatter、pageIcons、pageIconColor、pageIconInactiveColor、pageIconSize、pageTextStyle；
• 用于设置图例数据的 data属性。

下面展开讨论。

2.1 基础配置

启动 legend 组件，简单方法是提供 legend: {show: true} 配置，基础示例：

示例效果：

示例中，图例项的名称根据 series.name 推断；图例项的颜色也会根据 series 项的颜色自动推断。

2.2 图例数据

上例的图例数据由 series 数组自动推断，应用中也可选择通过 data 属性显式提供图例数据。data 数组接受两种类型的数值：

• 字符串，用于指定图例项的名称，图例组件会根据对应的序列图形确定图例项的颜色；

• 对象，属性如：

  { // 名称 name: '系列1', // 图例项的图形 icon: 'circle', // 设置文本样式属性 textStyle: { color: 'red' } }

示例：

示例效果：

提示：

使用 legend.data 项时，务必注意几个要点：

1. 提供 legend.data 后会关闭字段推断功能，如果某个序列的名称在 data 中没有出现，图例上自然也不会出现该项；
2. series名称必须能对应上 legend.data 项，否则也不会渲染该项；
3. 对于 legend.data 存在，但 series中不存在的项，也不会渲染。

legend.data 还支持传入对象，对象形式能够制定图例项的名称、标记、文本样式。内置的标记支持有 ‘circle’, ‘rect’, ‘roundRect’, ‘triangle’, ‘diamond’, ‘pin’, ‘arrow’, ‘none’ 项，详情请参考 legend.data.icon 一节。示例：

示例效果：

2.3 分页图例

当图例数量过多时，ECharts 默认会对图例元素折行处理，此时组件的高度是不可控的，可能会对图表造成某种程度的遮挡，可以考虑用分页图例解决这个问题：

启动分页功能需要设置 legend.type = scroll 与分页相关的属性有：

分页配置属性大多数与分页控制器的样式有关，并没有太多隐含逻辑或与其他组件的关联，故此处不展开讨论。

2.4 图例的交互

图例组件具备两种交互能力，一是鼠标悬停时高亮突出相应的序列图形，例如：

第二种是鼠标单击切换图例项的选中状态，控制相应图形的显示、隐藏，例如：

与选中态相关的属性有：

其中 selectedMode 支持 singlemultiple 用于设定组件是否支持多选，单选模式下的交互效果：

selected用于设定图表初始渲染时，图例项的选中状态，注意这里需要提供 key-value 对象形态的值，例如：

{
    '邮件营销': false,
    '联盟广告': true,
    '视频广告': false,
    '直接访问': true,
    '搜索引擎': true
}

上述配置的渲染效果：

提示：

有两种接口能动态修改图例的选中态，一是 setOption({ legend:{ selected:{...}} }) 接口 ，但这种方法会导致整个图表重新计算、重新渲染，性能较低，应尽量避免使用。

第二种方法是分发图例相关的 action，这种接口只会触发图例及相关序列的更新，性能更佳。ECharts 提供了 legendSelectlegendUnSelectlegendToggleSelectlegendScroll四种行为用以实现对图例组件的控制，调用规则可参考 ECharts action 交互 一节。

2.5 额外的选择器

ECharts 图例还支持额外的选择器模块，用以实现图例的全选、反选交互功能，可通过设置 legend.selector 属性启动，效果如：

与选择器相关的配置项有：

其中，selector 属性支持如下值：

selector: [
    {
        // 按钮类型
        // 支持 all、inverse
        type: 'all',
        title: '全选',
    },
    {
        type: 'inverse',
        title: '反选',
    },
];

// 或
selector: true;

// 或
selector: ['all', 'inverse'];

当图例项较多时，可以配合分页功能使用，示例：

示例效果：

3. 小结

本节结合多个实例，讲述 Echarts 图例组件(legend)的各类应用方法，包括基础配置方法；数据配置方法；分页功能；以及丰富的选中、全选等功能。