ECharts API 通過echarts.init創(chuàng)建的實(shí)例

echartsInstance

通過 echarts.init 創(chuàng)建的實(shí)例。

echartsInstance.group   |  string, number

圖表的分組，用于聯(lián)動

echartsInstance.setOption   |   Function

(option: Object, notMerge?: boolean, lazyUpdate?: boolean)
or
(option: Object, opts?: Object)

設(shè)置圖表實(shí)例的配置項(xiàng)以及數(shù)據(jù)，萬能接口，所有參數(shù)和數(shù)據(jù)的修改都可以通過 setOption 完成，ECharts 會合并新的參數(shù)和數(shù)據(jù)，然后刷新圖表。如果開啟動畫的話，ECharts 找到兩組數(shù)據(jù)之間的差異然后通過合適的動畫去表現(xiàn)數(shù)據(jù)的變化。

如下示例：

點(diǎn)擊編輯實(shí)例 》》

注： ECharts 2.x 中的通過 addData , setSeries 方法設(shè)置配置項(xiàng)的方式將不再支持，在 ECharts 3 中統(tǒng)一使用setOption，可以參考上面示例。

參數(shù)：

調(diào)用方式：

chart.setOption(option, notMerge, lazyUpdate);

或者

chart.setOption(option, {
    notMerge: ...,
    lazyUpdate: ...,
    silent: ...
});

• option：圖表的配置項(xiàng)和數(shù)據(jù)，具體見配置項(xiàng)手冊。
• notMerge：可選，是否不跟之前設(shè)置的option進(jìn)行合并，默認(rèn)為false，即合并。
• lazyUpdate：可選，在設(shè)置完option后是否不立即更新圖表，默認(rèn)為false，即立即更新。
• silent：可選，阻止調(diào)用 setOption 時拋出事件，默認(rèn)為false，即拋出事件。

echartsInstance.getWidth  |  Function

() => number

獲取 ECharts 實(shí)例容器的寬度。

echartsInstance.getHeight   |  Function

() => number

獲取 ECharts 實(shí)例容器的高度。

echartsInstance.getDom   |  Function

() => HTMLCanvasElement|HTMLDivElement

獲取 ECharts 實(shí)例容器的 dom 節(jié)點(diǎn)。

echartsInstance.getOption   |  Function

() => Object

獲取當(dāng)前實(shí)例中維護(hù)的option對象，返回的option對象中包含了用戶多次setOption合并得到的配置項(xiàng)和數(shù)據(jù)，也記錄了用戶交互的狀態(tài)，例如圖例的開關(guān)，數(shù)據(jù)區(qū)域縮放選擇的范圍等等。所以從這份 option 可以恢復(fù)或者得到一個新的一模一樣的實(shí)例。

注意：返回的 option 每個組件的屬性值都統(tǒng)一是一個數(shù)組，不管setOption傳進(jìn)來的時候是單個組件的對象還是多個組件的數(shù)組。如下形式：

{
    title: [{...}],
    legend: [{...}],
    grid: [{...}]
}

另外不推薦下面這種寫法：

var option = myChart.getOption();
option.visualMap[0].inRange.color = ...;
myChart.setOption(option);

因?yàn)?nbsp;getOption獲取的是已經(jīng)合并過默認(rèn)值了的，所以在修改了某些配置項(xiàng)后會導(dǎo)致原本是根據(jù)這些配置項(xiàng)值去設(shè)置的默認(rèn)值失效。

因此我們更推薦通過setOption去修改部分配置。

myChart.setOption({
    visualMap: {
        inRange: {
            color: ...
        }    }
})

echartsInstance.resize   |  Function

(opts?: {
    width?: number|string,
    height?: number|string,
    silent?: boolean
}) => ECharts

改變圖表尺寸，在容器大小發(fā)生改變時需要手動調(diào)用。

參數(shù)

• optsopts 可缺省。有下面幾個可選項(xiàng)：
• width：可顯式指定實(shí)例寬度，單位為像素。如果傳入值為 null/undefined/'auto'，則表示自動取 dom（實(shí)例容器）的寬度。
• height：可顯式指定實(shí)例高度，單位為像素。如果傳入值為 null/undefined/'auto'，則表示自動取 dom（實(shí)例容器）的高度。
• silent：是否禁止拋出事件。默認(rèn)為 false。

Tip: 有時候圖表會放在多個標(biāo)簽頁里，那些初始隱藏的標(biāo)簽在初始化圖表的時候應(yīng)為獲取不到容器的實(shí)際高寬，可能會繪制失敗，因此在切換到該標(biāo)簽頁時需要手動調(diào)用 resize 方法獲取正確的高寬并且刷新畫布，或者在 opts 中顯示指定圖表高寬。

echartsInstance.dispatchAction   |  Function

(payload: Object)

觸發(fā)圖表行為，例如圖例開關(guān)legendToggleSelect, 數(shù)據(jù)區(qū)域縮放dataZoom，顯示提示框showTip等等，更多見 action 和 events 的文檔。

payload 參數(shù)可以通過batch屬性同時觸發(fā)多個行為。

注：在 ECharts 2.x 是通過 myChart.component.tooltip.showTip 這種形式調(diào)用相應(yīng)的接口觸發(fā)圖表行為，入口很深，而且涉及到內(nèi)部組件的組織。因此在 ECharts 3 里統(tǒng)一改為 dispatchAction 的形式。

示例：

myChart.dispatchAction({
    type: 'dataZoom',
    start: 20,
    end: 30
});
// 可以通過 batch 參數(shù)批量分發(fā)多個 action
myChart.dispatchAction({
    type: 'dataZoom',
    batch: [{
        // 第一個 dataZoom 組件
        start: 20,
        end: 30
    }, {
        // 第二個 dataZoom 組件
        dataZoomIndex: 1,
        start: 10,
        end: 20
    }]})

echartsInstance.on   |  Function

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

綁定事件處理函數(shù)。

ECharts 中的事件有兩種，一種是鼠標(biāo)事件，在鼠標(biāo)點(diǎn)擊某個圖形上會觸發(fā)，還有一種是 調(diào)用 dispatchAction 后觸發(fā)的事件。每個 action 都會有對應(yīng)的事件，具體見 action 和  events 的文檔。

如果事件是外部 dispatchAction 后觸發(fā)，并且 action 中有 batch 屬性觸發(fā)批量的行為，則相應(yīng)的響應(yīng)事件參數(shù)里也會把屬性都放在 batch 屬性中。

參數(shù)：

• eventName事件名稱，全小寫，例如'click'，'mousemove', 'legendselected'注： ECharts 2.x 中會使用 config 對象中的 CLICK 等屬性作為事件名稱。在 ECharts 3 中統(tǒng)一使用跟 dom 事件一樣的全小寫字符串作為事件名。
• handler事件處理函數(shù)。格式為: (event: Object)
• context可選。回調(diào)函數(shù)內(nèi)部的context，即this的指向。

echartsInstance.off   |  Function

(eventName: string, handler?: Function)

解綁事件處理函數(shù)。

參數(shù)：

• eventName事件名稱。
• handler可選，可以傳入需要解綁的處理函數(shù)，不傳的話解綁所有該類型的事件函數(shù)。

echartsInstance.convertToPixel   |  Function

(    // finder 用于指示『使用哪個坐標(biāo)系進(jìn)行轉(zhuǎn)換』。
    // 通常地，可以使用 index 或者 id 或者 name 來定位。
    finder: {
        seriesIndex?: number,
        seriesId?: string,
        seriesName?: string,
        geoIndex?: number,
        geoId?: string,
        geoName?: string,
        xAxisIndex?: number,
        xAxisId?: string,
        xAxisName?: string,
        yAxisIndex?: number,
        yAxisId?: string,
        yAxisName?: string,
        gridIndex?: number,
        gridId?: string
        gridName?: string
    },
    // 要被轉(zhuǎn)換的值。
    value: Array|string
    // 轉(zhuǎn)換的結(jié)果為像素坐標(biāo)值，以 echarts 實(shí)例的 dom 節(jié)點(diǎn)的左上角為坐標(biāo) [0, 0] 點(diǎn)。
) => Array|string

轉(zhuǎn)換坐標(biāo)系上的點(diǎn)到像素坐標(biāo)值。

例：

在地理坐標(biāo)系（geo）上，把某個點(diǎn)的經(jīng)緯度坐標(biāo)轉(zhuǎn)換成為像素坐標(biāo)：

// [128.3324, 89.5344] 表示 [經(jīng)度，緯度]。
// 使用第一個 geo 坐標(biāo)系進(jìn)行轉(zhuǎn)換：
chart.convertToPixel('geo', [128.3324, 89.5344]); // 參數(shù) 'geo' 等同于 {geoIndex: 0}
// 使用第二個 geo 坐標(biāo)系進(jìn)行轉(zhuǎn)換：
chart.convertToPixel({geoIndex: 1}, [128.3324, 89.5344]);
// 使用 id 為 'bb' 的 geo 坐標(biāo)系進(jìn)行轉(zhuǎn)換：
chart.convertToPixel({geoId: 'bb'}, [128.3324, 89.5344]);

在直角坐標(biāo)系（cartesian，grid）上，把某個點(diǎn)的坐標(biāo)轉(zhuǎn)換成為像素坐標(biāo)：

// [300, 900] 表示該點(diǎn) x 軸上對應(yīng)刻度值 300，y 軸上對應(yīng)刻度值 900。
// 注意，一個 grid 可能含有多個 xAxis 和多個 yAxis，任何一對 xAxis-yAxis 形成一個 cartesian。
// 使用第三個 xAxis 和 id 為 'y1' 的 yAxis 形成的 cartesian 進(jìn)行轉(zhuǎn)換：
chart.convertToPixel({xAxisIndex: 2, yAxisId: 'y1'}, [300, 900]);
// 使用 id 為 'g1' 的 grid 的第一個 cartesian 進(jìn)行轉(zhuǎn)換：
chart.convertToPixel({gridId: 'g1'}, [300, 900]);

把某個坐標(biāo)軸的點(diǎn)轉(zhuǎn)換成像素坐標(biāo)：

// id 為 'x0' 的 xAxis 的刻度 3000 位置所對應(yīng)的橫向像素位置：
chart.convertToPixel({xAxisId: 'x0'}, 3000); // 返回一個 number。
// 第二個 yAxis 的刻度 600 位置所對應(yīng)的縱向像素位置：
chart.convertToPixel({yAxisIndex: 1}, 600); // 返回一個 number。

把關(guān)系圖（graph）的點(diǎn)轉(zhuǎn)換成像素坐標(biāo)：

// 因?yàn)槊總€ graph series 自己持有一個坐標(biāo)系，所以我們直接在 finder 中指定 series：
chart.convertToPixel({seriesIndex: 0}, [2000, 3500]);
chart.convertToPixel({seriesId: 'k2'}, [100, 500]);

在某個系列所在的坐標(biāo)系（無論是 cartesian、geo、graph 等）中，轉(zhuǎn)換某點(diǎn)成像素坐標(biāo)：

// 使用第一個系列對應(yīng)的坐標(biāo)系：
chart.convertToPixel({seriesIndex: 0}, [128.3324, 89.5344]);
// 使用 id 為 'k2' 的系列所對應(yīng)的坐標(biāo)系：
chart.convertToPixel({seriesId: 'k2'}, [128.3324, 89.5344]);

echartsInstance.

   |   Function

(    // finder 用于指示『使用哪個坐標(biāo)系進(jìn)行轉(zhuǎn)換』。
    // 通常地，可以使用 index 或者 id 或者 name 來定位。
    finder: {
        seriesIndex?: number,
        seriesId?: string,
        seriesName?: string,
        geoIndex?: number,
        geoId?: string,
        geoName?: string,
        xAxisIndex?: number,
        xAxisId?: string,
        xAxisName?: string,
        yAxisIndex?: number,
        yAxisId?: string,
        yAxisName?: string,
        gridIndex?: number,
        gridId?: string
        gridName?: string
    },
    // 要被轉(zhuǎn)換的值，為像素坐標(biāo)值，以 echarts 實(shí)例的 dom 節(jié)點(diǎn)的左上角為坐標(biāo) [0, 0] 點(diǎn)。
    value: Array|string
    // 轉(zhuǎn)換的結(jié)果，為邏輯坐標(biāo)值。
) => Array|string

轉(zhuǎn)換像素坐標(biāo)值到邏輯坐標(biāo)系上的點(diǎn)。是 convertToPixel 的逆運(yùn)算。 具體實(shí)例可參考 convertToPixel。

echartsInstance.containPixel   |  Function

(    // finder 用于指示『在哪個坐標(biāo)系或者系列上判斷』。
    // 通常地，可以使用 index 或者 id 或者 name 來定位。
    finder: {
        seriesIndex?: number,
        seriesId?: string,
        seriesName?: string,
        geoIndex?: number,
        geoId?: string,
        geoName?: string,
        xAxisIndex?: number,
        xAxisId?: string,
        xAxisName?: string,
        yAxisIndex?: number,
        yAxisId?: string,
        yAxisName?: string,
        gridIndex?: number,
        gridId?: string
        gridName?: string
    },
    // 要被判斷的點(diǎn)，為像素坐標(biāo)值，以 echarts 實(shí)例的 dom 節(jié)點(diǎn)的左上角為坐標(biāo) [0, 0] 點(diǎn)。
    value: Array
) => boolean

判斷給定的點(diǎn)是否在指定的坐標(biāo)系或者系列上。

目前支持在這些坐標(biāo)系和系列上進(jìn)行判斷：grid, polar, geo,  series-map, series-graph, series-pie。

例：

// 判斷 [23, 44] 點(diǎn)是否在 geoIndex 為 0 的 geo 坐標(biāo)系上。
chart.containPixel('geo', [23, 44]); // 'geo' 等同于 {geoIndex: 0}
// 判斷 [23, 44] 點(diǎn)是否在 gridId 為 'z' 的 grid 上。
chart.containPixel({gridId: 'z'}, [23, 44]);
// 判斷 [23, 44] 點(diǎn)是否在 index 為 1，4，5 的系列上。
chart.containPixel({seriesIndex: [1, 4, 5]}, [23, 44]);
// 判斷 [23, 44] 點(diǎn)是否在 index 為 1，4，5 的系列或者 gridName 為 'a' 的 grid 上。
chart.containPixel({seriesIndex: [1, 4, 5], gridName: 'a'}, [23, 44]);

echartsInstance.showLoading   |   Function

(type?: string, opts?: Object)

顯示加載動畫效果?？梢栽诩虞d數(shù)據(jù)前手動調(diào)用改接口顯示加載動畫，在數(shù)據(jù)加載完成后調(diào)用 hideLoading 隱藏加載動畫。

參數(shù)：

• type可選，加載動畫類型，目前只有一種'default'
• opts可選，加載動畫配置項(xiàng)，跟type有關(guān)，下面是默認(rèn)配置項(xiàng)：default: { text: 'loading', color: '#c23531', textColor: '#000', maskColor: 'rgba(255, 255, 255, 0.8)', zlevel: 0 }

echartsInstance.hideLoading   |   Function

隱藏動畫加載效果。

echartsInstance.getDataURL    |   Function

(opts: {    // 導(dǎo)出的格式，可選 png, jpeg
    type?: string,
    // 導(dǎo)出的圖片分辨率比例，默認(rèn)為 1。
    pixelRatio?: number,
    // 導(dǎo)出的圖片背景色，默認(rèn)使用 option 里的 backgroundColor
    backgroundColor?: string,
    // 忽略組件的列表，例如要忽略 toolbox 就是 ['toolbox']
    excludeComponents?: Array.<string>
}) => string

導(dǎo)出圖表圖片，返回一個 base64 的 URL，可以設(shè)置為Image的src。

示例：

var img = new Image();
img.src = myChart.getDataURL({
    pixelRatio: 2,
    backgroundColor: '#fff'
});

echartsInstance.getConnectedDataURL   | *

(opts: {
    // 導(dǎo)出的格式，可選 png, jpeg
    type?: string,
    // 導(dǎo)出的圖片分辨率比例，默認(rèn)為 1。
    pixelRatio?: number,
    // 導(dǎo)出的圖片背景色，默認(rèn)使用 option 里的 backgroundColor
    backgroundColor?: string,
    // 忽略組件的列表，例如要忽略 toolbox 就是 ['toolbox']
    excludeComponents?: Array.<string>
}) => string

導(dǎo)出聯(lián)動的圖表圖片，返回一個 base64 的 url，可以設(shè)置為Image的src。導(dǎo)出圖片中每個圖表的相對位置跟容器的相對位置有關(guān)。

echartsInstance.clear   |  *

清空當(dāng)前實(shí)例，會移除實(shí)例中所有的組件和圖表。清空后調(diào)用 getOption 方法返回一個{}空對象。

echartsInstance.isDisposed   |  *

() => boolean

當(dāng)前實(shí)例是否已經(jīng)被釋放。

echartsInstance.dispose    |   *

銷毀實(shí)例，銷毀后實(shí)例無法再被使用。