ECharts 事件系统

当我们的图表变得越来越庞大之后，我们加入的组件也会越来越多，所以我们之后做的不单单只有 “看”这一个动作，还要有其他的动作，对应的就是一个个事件的处理，用户操作触发事件，我们则可以通过监听事件并处理来完成一系列的事件操作，所以这一节我们就来从事件三要素，事件绑定，事件解绑这几个方面去了解一下 ECharts 的事件系统。

1. 简介

官方解释:

在 ECharts 的图表中用户的操作将会触发相应的事件。开发者可以监听这些事件，然后通过回调函数做相应的处理，比如跳转到一个地址，或者弹出对话框，或者做数据下钻等等。更多细节可参考 官网。

慕课解释

ECharts 开放了两套 API 体系，一是 ECharts 类接口及实例的接口，例如常用的 echarts.init 方法、echartInstance.setOption()；二是围绕事件展开的动态交互接口，包括用于监听事件的 echartInstance.on 函数和用于触发行为的 echartInstance.dispatchAction 函数。

本文讨论使用 echartInstance.on 接口实现的事件监听功能。

2. 事件三要素

与 Dom Event 规范 类似，ECharts 通过事件名称、事件源、事件参数三个要素精确描述谁在何处执行了何种操作。在展开示例讨论前，有必要简单讨论下 ECharts 事件三要素的含义。

2.1 事件名称

ECharts 中存在两种类型的事件，第一种是鼠标在图形示例上的行为所触发的鼠标事件，包括：

• click
• dbclick
• mousedown
• mousemove
• mouseup
• mouseover
• mouseout
• contextmenu
• globalout

上述事件除 globalout 外，均与 DOM Event 规范 定义的同名事件有相同的语义、触发条件。globalout 在鼠标移出图表示例范围时触发。

第二种称为行为事件，在组件、图表状态发生某种业务状态迁移时触发，包括：

上表只摘录行为事件的关键部分，更详细的介绍请参考 官网文档。

行为事件的发生代表着组件实体内部状态发生了某些变更，有两种原因可能触发行为事件：

1. 用户交互行为，例如图例组件中，用户通过鼠标点击切换图例开关时，ECharts 除触发鼠标 click 事件外，还会触发 legendselectchanged 行为事件；
2. 接口调用，例如图例组件中，调用 echartInstance.dispatchAction({ type: 'legendToggleSelect' }) 后也依然会触发 legendselectchanged 行为事件。

2.2 事件源

事件源描述了触发事件的主体，对于鼠标事件，事件源通常是行为发生时鼠标焦点所在图形区域对应的图表。所有类型的图表都支持鼠标事件；部分组件支持触发鼠标事件，但默认是关闭的，需要通过设置 triggerEvent: true 来启动。组件对鼠标事件的支持情况如下：

• 支持：title，xAxis ，yAxis， radiusAxis ，angleAxis，radar ，parallelAxis， singleAxis ，timeline，calendar；
• 不支持： polar ，legend， grid ，datazoom， visualMap， tooltip， axisPointer， toolbox， brush， geo ，parallel， graphic。

Tips：

graphic 是原生图形组件，不支持echartInstance.on 接口，但可直接调用 element.onclick 等接口实现事件监听。

行为事件由特定的组件、图表触发，例如 legendselectchanged 的事件源只能是 legend 组件，更多信息请参考 事件名称 一节。

2.3 事件参数

事件参数描述事件发生时的上下文信息，ECharts中不同事件的参数信息相差极大，甚至同种事件在不同组件触发时，回调参数也有差异。

2.3.1 鼠标事件参数

ECharts 鼠标事件，虽然名称上与 DOM Event 规范 一致，但回调中传递的参数比标准相差很大。以 click 为例，DOM 的 click 事件参数是一个 MouseEvent 对象，主要属性有：

{
	isTrusted: boolean,
	screenX: number,
	screenY: number,
	clientX: number,
	clientY: number,
	ctrlKey: boolean,
	shiftKey: boolean,
	altKey: boolean,
	metaKey: boolean,
	relatedTarget: object,
	pageX: number,
	pageY: number,
	x: number,
	y: number,
	offsetX: number,
  offsetY: number,
  ...
}

可以看出 DOM 的 click 事件参数详细描述了点击行为发生的位置、事件源的 dom、是否带有快捷键、捕获的阶段等。而 ECharts 在 series 上发生的 click 事件带有如下参数：

{
	// 当前点击的图形元素所属的组件名称，
	// 其值如 'series'、'markLine'、'markPoint'、'timeLine' 等。
	componentType: string,
	// 图形元素所属二级组件类型
	// 如 `bar`、`line`、`pie` 等
	componentSubType: string,
	componentIndex: number,
	// 系列类型。值可能为：'line'、'bar'、'pie' 等
	seriesType: string,
	// 系列在传入的 option.series 中的 index
	seriesIndex: number,
	// 系列ID
	seriesId: string,
	// 系列名称
	seriesName: string,
	// 数据名，类目名
	name: string,
	// 触发事件的数据在data数组中的index
	dataIndex: number,
	// 触发事件的数据所传入的原始data值
	data: number,
	// sankey、graph 等图表同时含有 nodeData 和 edgeData 两种 data，
	// dataType 的值会是 'node' 或者 'edge'，表示当前点击在 node 还是 edge 上。
	// 其他大部分图表中只有一种 data，dataType 无意义。
	dataType: string,
	// 传入的数据值
	value: number | Array,
	// 数据图形的颜色
	color: string,
	// 数据图形的边框色
	borderColor: undefined,
	// 数据图形的维度信息
	dimensionNames: object,
	encode: object,
	// 标记信息的html内容
	marker: string,
	$vars: object,
	// 原始click事件参数
	event: object,
	// 事件名称，本例中为 `click`
	type: string,
}

可以看出，ECharts 传递的 click 事件参数侧重于描述发生点击行为的图形所对应的组件信息、状态、配置，比如上例中的 componentType、componentSubType 指明单击的组件类别、子类别；seriesType、seriesIndex、data 等指明单击组件所对应的数据配置值；marker、encode 则指明单击发生时，组件内部状态信息。大多数情况下这些信息是足够使用的，必要时也可以通过 event 属性读取原始 dom 事件参数。

需要注意的第二点是，即使是同种事件，不同组件所暴露的参数也是不一样的，以 click 为例，在 series.bar 上触发时有如下属性：

componentType、componentSubType、componentIndex、seriesType、seriesIndex、seriesId、seriesName、name、dataIndex、data、dataType、value、color、borderColor、dimensionNames、encode、marker、$vars、event、type

在 yAxis 则有：

componentType、componentIndex、yAxisIndex、targetType、value、event、type

在 title 上则是：

componentType、componentIndex、event、type

Tips：
遗憾的是，官网并未就此给出详细、完整的列表，建议开发时通过 console.log、debugger 等手段获取各种组件所传递的事件参数。

2.3.2 行为事件参数

与鼠标事件参数一样，行为事件也没有提供一致的参数模型，不过官网提供了 明细说明，开发时建议前往查阅。

3. 监听事件

ECharts 中可通过 echartInstance.on 函数绑定事件处理函数，on 函数签名：

(eventName: string, query?: string|Object, handler: Function, context?: Object)

各参数说明：

3.1 全局监听

若未提供 query 参数，ECharts 将不对事件源做任何过滤，相当于注册了一个全局事件回调。例如：