ECharts 中的事件和行爲
在 ECharts 的圖表中用戶的操作將會觸發相應的事件。開發者可以監聽這些事件,然後通過回調函數做相應的處理,比如跳轉到一個地址,或者彈出對話框,或者做數據下鑽等等。
在 ECharts 3 中綁定事件跟 2 一樣都是通過 on 方法,但是事件名稱比 2 更加簡單了。ECharts 3 中,事件名稱對應 DOM 事件名稱,均爲小寫的字符串,如下是一個綁定點擊操作的示例。
myChart.on('click', function (params) {
// 控制檯打印數據的名稱
console.log(params.name);
});
在 ECharts 中事件分爲兩種類型,一種是用戶鼠標操作點擊,或者 hover 圖表的圖形時觸發的事件,還有一種是用戶在使用可以交互的組件後觸發的行爲事件,例如在切換圖例開關時觸發的 'legendselectchanged' 事件(這裏需要注意切換圖例開關是不會觸發'legendselected'
事件的),數據區域縮放時觸發的 'datazoom' 事件等等。
鼠標事件的處理
ECharts 支持常規的鼠標事件類型,包括 'click'
、'dblclick'
、'mousedown'
、'mousemove'
、'mouseup'
、'mouseover'
、'mouseout'
、'globalout'
、'contextmenu'
事件。下面先來看一個簡單的點擊柱狀圖後打開相應的百度搜索頁面的示例。
// 基於準備好的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
,這是一個包含點擊圖形的數據信息的對象,如下格式:
{
// 當前點擊的圖形元素所屬的組件名稱,
// 其值如 '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
}
如何區分鼠標點擊到了哪裏:
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
只對指定的組件的圖形元素的觸發回調:
chart.on(eventName, query, handler);
query
可爲 string
或者 Object
。
如果爲 string
表示組件類型。格式可以是 'mainType' 或者 'mainType.subType'。例如:
chart.on('click', 'series', function () {...});
chart.on('click', 'series.line', function () {...});
chart.on('click', 'dataZoom', function () {...});
chart.on('click', 'xAxis.category', function () {...});
如果爲 Object
,可以包含以下一個或多個屬性,每個屬性都是可選的:
{
<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
}
例如:
chart.setOption({
// ...
series: [{
name: 'uuu'
// ...
}]
});
chart.on('mouseover', {seriesName: 'uuu'}, function () {
// series name 爲 'uuu' 的系列中的圖形元素被 'mouseover' 時,此方法被回調。
});
例如:
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' 時,此方法被回調。
});
例如:
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 () {
// 關係圖的邊被點擊時此方法被回調。
});
例如:
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' 時,此方法被回調。
});
你可以在回調函數中獲得這個對象中的數據名、系列名稱後在自己的數據倉庫中索引得到其它的信息候更新圖表,顯示浮層等等,如下示例代碼:
myChart.on('click', function (parmas) {
$.get('detail?q=' + params.name, function (detail) {
myChart.setOption({
series: [{
name: 'pie',
// 通過餅圖表現單個柱子中的數據分佈
data: [detail.data]
}]
});
});
});
組件交互的行爲事件
在 ECharts 中基本上所有的組件交互行爲都會觸發相應的事件,常用的事件和事件對應參數在 events 文檔中有列出。
下面是監聽一個圖例開關的示例:
// 圖例開關的行爲只會觸發 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 文檔中有列出。
下面示例演示瞭如何通過dispatchAction
去輪流高亮餅圖的每個扇形。