| {{ target: event }} |
| |
| # ECharts 中的事件和行为 |
| |
| 在 Apache ECharts<sup>TM</sup> 的图表中用户的操作将会触发相应的事件。开发者可以监听这些事件，然后通过回调函数做相应的处理，比如跳转到一个地址，或者弹出对话框，或者做数据下钻等等。 |
| |
| 在 ECharts 3 中绑定事件跟 2 一样都是通过 [on](api.html#EChartsInstance.on) 方法，但是事件名称比 2 更加简单了。ECharts 3 中，事件名称对应 DOM 事件名称，均为小写的字符串，如下是一个绑定点击操作的示例。 |
| |
| ```ts |
| myChart.on('click', function (params) { |
| // 控制台打印数据的名称 |
| console.log(params.name); |
| }); |
| ``` |
| |
| 在 ECharts 中事件分为两种类型，一种是用户鼠标操作点击，或者 hover 图表的图形时触发的事件，还有一种是用户在使用可以交互的组件后触发的行为事件，例如在切换图例开关时触发的 ['legendselectchanged'](api.html#events.legendselectchanged) 事件（这里需要注意切换图例开关是不会触发`'legendselected'`事件的），数据区域缩放时触发的 ['datazoom'](api.html#events.legendselectchanged) 事件等等。 |
| |
| ## 鼠标事件的处理 |
| |
| ECharts 支持常规的鼠标事件类型，包括 `'click'`、`'dblclick'`、`'mousedown'`、`'mousemove'`、`'mouseup'`、`'mouseover'`、`'mouseout'`、`'globalout'`、`'contextmenu'` 事件。下面先来看一个简单的点击柱状图后打开相应的百度搜索页面的示例。 |
| |
| ```ts |
| // 基于准备好的dom，初始化ECharts实例 |
| var myChart = echarts.init(document.getElementById('main')); |
| |
| // 指定图表的配置项和数据 |
| var option = { |
| xAxis: { |
| data: ["衬衫","羊毛衫","雪纺衫","裤子","高跟鞋","袜子"] |
| }, |
| yAxis: {}, |
| series: [{ |
| name: '销量', |
| type: 'bar', |
| data: [5, 20, 36, 10, 10, 20] |
| }] |
| }; |
| // 使用刚指定的配置项和数据显示图表。 |
| myChart.setOption(option); |
| // 处理点击事件并且跳转到相应的百度搜索页面 |
| myChart.on('click', function (params) { |
| window.open('https://www.baidu.com/s?wd=' + encodeURIComponent(params.name)); |
| }); |
| ``` |
| |
| 所有的鼠标事件包含参数 `params`，这是一个包含点击图形的数据信息的对象，如下格式： |
| ```ts |
| { |
| // 当前点击的图形元素所属的组件名称， |
| // 其值如 'series'、'markLine'、'markPoint'、'timeLine' 等。 |
| componentType: string, |
| // 系列类型。值可能为：'line'、'bar'、'pie' 等。当 componentType 为 'series' 时有意义。 |
| seriesType: string, |
| // 系列在传入的 option.series 中的 index。当 componentType 为 'series' 时有意义。 |
| seriesIndex: number, |
| // 系列名称。当 componentType 为 'series' 时有意义。 |
| seriesName: string, |
| // 数据名，类目名 |
| name: string, |
| // 数据在传入的 data 数组中的 index |
| dataIndex: number, |
| // 传入的原始数据项 |
| data: Object, |
| // sankey、graph 等图表同时含有 nodeData 和 edgeData 两种 data， |
| // dataType 的值会是 'node' 或者 'edge'，表示当前点击在 node 还是 edge 上。 |
| // 其他大部分图表中只有一种 data，dataType 无意义。 |
| dataType: string, |
| // 传入的数据值 |
| value: number|Array |
| // 数据图形的颜色。当 componentType 为 'series' 时有意义。 |
| color: string |
| } |
| ``` |
| |
| 如何区分鼠标点击到了哪里： |
| ```ts |
| myChart.on('click', function (params) { |
| if (params.componentType === 'markPoint') { |
| // 点击到了 markPoint 上 |
| if (params.seriesIndex === 5) { |
| // 点击到了 index 为 5 的 series 的 markPoint 上。 |
| } |
| } |
| else if (params.componentType === 'series') { |
| if (params.seriesType === 'graph') { |
| if (params.dataType === 'edge') { |
| // 点击到了 graph 的 edge（边）上。 |
| } |
| else { |
| // 点击到了 graph 的 node（节点）上。 |
| } |
| } |
| } |
| }); |
| ``` |
| |
| 使用 `query` 只对指定的组件的图形元素的触发回调： |
| ```ts |
| chart.on(eventName, query, handler); |
| ``` |
| |
| `query` 可为 `string` 或者 `Object`。 |
| |
| 如果为 `string` 表示组件类型。格式可以是 'mainType' 或者 'mainType.subType'。例如： |
| ```ts |
| chart.on('click', 'series', function () {...}); |
| chart.on('click', 'series.line', function () {...}); |
| chart.on('click', 'xAxis.category', function () {...}); |
| ``` |
| |
| 如果为 `Object`，可以包含以下一个或多个属性，每个属性都是可选的： |
| ```ts |
| { |
| <mainType>Index: number // 组件 index |
| <mainType>Name: string // 组件 name |
| <mainType>Id: string // 组件 id |
| dataIndex: number // 数据项 index |
| name: string // 数据项 name |
| dataType: string // 数据项 type，如关系图中的 'node', 'edge' |
| element: string // 自定义系列中的 el 的 name |
| } |
| ``` |
| |
| 例如： |
| ```ts |
| chart.setOption({ |
| // ... |
| series: [{ |
| name: 'uuu' |
| // ... |
| }] |
| }); |
| chart.on('mouseover', {seriesName: 'uuu'}, function () { |
| // series name 为 'uuu' 的系列中的图形元素被 'mouseover' 时，此方法被回调。 |
| }); |
| ``` |
| |
| 例如： |
| ```ts |
| chart.setOption({ |
| // ... |
| series: [{ |
| // ... |
| }, { |
| // ... |
| data: [ |
| {name: 'xx', value: 121}, |
| {name: 'yy', value: 33} |
| ] |
| }] |
| }); |
| chart.on('mouseover', {seriesIndex: 1, name: 'xx'}, function () { |
| // series index 1 的系列中的 name 为 'xx' 的元素被 'mouseover' 时，此方法被回调。 |
| }); |
| ``` |
| |
| 例如： |
| ```ts |
| chart.setOption({ |
| // ... |
| series: [{ |
| type: 'graph', |
| nodes: [{name: 'a', value: 10}, {name: 'b', value: 20}], |
| edges: [{source: 0, target: 1}] |
| }] |
| }); |
| chart.on('click', {dataType: 'node'}, function () { |
| // 关系图的节点被点击时此方法被回调。 |
| }); |
| chart.on('click', {dataType: 'edge'}, function () { |
| // 关系图的边被点击时此方法被回调。 |
| }); |
| ``` |
| |
| 例如： |
| ```ts |
| chart.setOption({ |
| // ... |
| series: { |
| // ... |
| type: 'custom', |
| renderItem: function (params, api) { |
| return { |
| type: 'group', |
| children: [{ |
| type: 'circle', |
| name: 'my_el', |
| // ... |
| }, { |
| // ... |
| }] |
| } |
| }, |
| data: [[12, 33]] |
| } |
| }) |
| chart.on('mouseup', {element: 'my_el'}, function () { |
| // name 为 'my_el' 的元素被 'mouseup' 时，此方法被回调。 |
| }); |
| ``` |
| |
| |
| 你可以在回调函数中获得这个对象中的数据名、系列名称后在自己的数据仓库中索引得到其它的信息候更新图表，显示浮层等等，如下示例代码： |
| |
| ```ts |
| myChart.on('click', function (parmas) { |
| $.get('detail?q=' + params.name, function (detail) { |
| myChart.setOption({ |
| series: [{ |
| name: 'pie', |
| // 通过饼图表现单个柱子中的数据分布 |
| data: [detail.data] |
| }] |
| }); |
| }); |
| }); |
| ``` |
| |
| ## 组件交互的行为事件 |
| |
| 在 ECharts 中基本上所有的组件交互行为都会触发相应的事件，常用的事件和事件对应参数在 [events](api.html#events) 文档中有列出。 |
| |
| 下面是监听一个图例开关的示例： |
| |
| ```ts |
| // 图例开关的行为只会触发 legendselectchanged 事件 |
| myChart.on('legendselectchanged', function (params) { |
| // 获取点击图例的选中状态 |
| var isSelected = params.selected[params.name]; |
| // 在控制台中打印 |
| console.log((isSelected ? '选中了' : '取消选中了') + '图例' + params.name); |
| // 打印所有图例的状态 |
| console.log(params.selected); |
| }); |
| ``` |
| |
| ## 代码触发 ECharts 中组件的行为 |
| |
| 上面提到诸如`'legendselectchanged'`事件会由组件交互的行为触发，那除了用户的交互操作，有时候也会有需要在程序里调用方法触发图表的行为，诸如显示 tooltip，选中图例。 |
| |
| 在 ECharts 2.x 是通过 `myChart.component.tooltip.showTip` 这种形式调用相应的接口触发图表行为，入口很深，而且涉及到内部组件的组织。相对地，在 ECharts 3 里改为通过调用 `myChart.dispatchAction({ type: '' })` 触发图表行为，统一管理了所有动作，也可以方便地根据需要去记录用户的行为路径。 |
| |
| 常用的动作和动作对应参数在 [action](api.html#action) 文档中有列出。 |
| |
| 下面示例演示了如何通过`dispatchAction`去轮流高亮饼图的每个扇形。 |
| |
| ~[600x400](${galleryViewPath}doc-example/pie-highlight&edit=1&reset=1) |
| |
| |
| ## 监听“空白处”的事件 |
| |
| 有时候，开发者需要监听画布的“空白处”所触发的事件。比如，当需要在用户点击“空白处”的时候重置图表时。 |
| |
| 在讨论这个功能之前，我们需要先明确两种事件。`zrender 事件`和`echarts 事件`。 |
| |
| ```ts |
| myChart.getZr().on('click', function (event) { |
| // 该监听器正在监听一个`zrender 事件`。 |
| }); |
| myChart.on('click', function (event) { |
| // 该监听器正在监听一个`echarts 事件`。 |
| }); |
| ``` |
| `zrender 事件`与`echarts 事件`不同。前者是当鼠标在任何地方都会被触发，而后者是只有当鼠标在图形元素上时才能被触发。事实上，`echarts 事件` 是在 `zrender 事件` 的基础上实现的，也就是说，当一个 `zrender 事件` 在图形元素上被触发时，`echarts` 将触发一个 `echarts 事件` 给开发者。 |
| |
| 有了 `zrender事件`，我们就可以实现 “监听空白处的事件”，具体如下： |
| ```ts |
| myChart.getZr().on('click', function (event) { |
| // 没有 target 意味着鼠标/指针不在任何一个图形元素上，它是从“空白处”触发的。 |
| if (!event.target) { |
| // 点击在了空白处，做些什么。 |
| } |
| }); |
| ``` |
