Echarts常用API（echarts和echartsInstance）

一、echarts上的方法

一般在項目中引入echarts之后，可以獲得一個全局的echarts對象。

1.下面是幾個比較常用的echarts方法

echarts.init()

創建一個echarts實例，返回echarts實例。不能在單個容器中創建多個echarts實例。

(dom: HTMLDivElement|HTMLCanvasElement, theme?: Object|string, opts?: {
    devicePixelRatio?: number
    renderer?: string
    width?: number|string
    height? number|string
}) => ECharts

echarts.dispose(target: ECharts|HTMLDivElement|HTMLCanvasElement)

銷毀實例。實例銷毀后無法再被使用。

echarts.getInstanceByDom(target: HTMLDivElement|HTMLCanvasElement)

獲取Dom容器上的實例。

echarts.registerTheme(themeName: string, theme: Object)

注冊主題，用於初始化實例的時候指定。

2.然后是幾個比較具體的方法

echarts.connect(group:string|Array)

多個圖表實例實現聯動

echarts.disconnect(group:string)

解除圖表實例的聯動，如果只需要移除單個實例，可以通過將該圖表實例group設為空。

echarts.registerMap(mapName: string, geoJson: Object, specialAreas?: Object)

注冊可用的地圖。必須在包括geo組件或者map圖表類型的時候才能使用。

echarts.getMap(mapName: string) => Object

獲取已注冊的地圖，返回的對象類型是：

{
    // 地圖的 geoJson 數據
    geoJson: Object,
    // 地圖的特殊區域，見 registerMap
    specialAreas: Object
}

echarts.graphic

圖形相關幫助方法。主要有兩個方法：clipPointsByRect()和clipRectByRect()。
1）clipPointsByRect()
輸入一組點，一個矩形，返回被矩形截取過的點

(
    // 要被截取的點列表，如 [[23, 44], [12, 15], ...]。
    points: Array.<Array.<number>>,
    // 用於截取點的矩形。
    rect: {
        x: number,
        y: number,
        width: number,
        height: number
}
) => Array.<Array.<number>> // 截取結果。

2）clipRectByRect()
輸入兩個矩形，返回第二個矩形截取第一個矩形的結果。

(
    // 要被截取的矩形。
    targetRect: {
        x: number,
        y: number,
        width: number,
        height: number
    },
    // 用於截取點的矩形。
    rect: {
        x: number,
        y: number,
        width: number,
        height: number
    }
) => { // 截取結果。
    x: number,
    y: number,
    width: number,
    height: number
}

如果矩形完全被截取完，則會返回undefined。

二、echartsInstance的方法

1.echartsInstance.group

圖表的分組，用於聯動。

2.echartsInstance.setOption()

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

設置圖表實例的配置項和數據，萬能接口，所有參數和數據的修改都可以通過setOption來完成。Echarts會合並新的參數和數據，然后刷新圖表。還有開啟動畫的話，Echarts會找到兩組數據的差異然后通過合適的動畫去展示。
notMerge: 可選參數，是否可以不和之前的option進行合並，默認為false，進行合並。
lazyUpdate：也是一個可選參數，在設置完option之后是否不更新圖表。默認為false，即立即更新。
注意：lazyUpdate這個參數，設置為false的時候，會立即更新圖表。一般在做項目的時候，會根據一定的不同條件值（時間等condition）來在一個div容器上渲染具有不同數據的圖表。這時候會從后端獲取不同的數據來渲染echarts圖表。這時候需要將lazyUpdate參數設置為true，然后圖表才能隨着數據的變化而正常變化。

3.下面是幾個獲取條件的方法

1）echartsInstance.getWidth() => number

獲取實例所在容器的寬度。

2）echartsInstance.getHeight() => number

獲取實例所在容器的高度。

3）echartsInstance.getDom() => HTMLCanvasElement|HTMLDivElement

獲取實例容器的dom節點

4）echartsInstance.getOption() => Object

獲取當前實例維護的option對象，返回的option對象是經過用戶多次setOption之后修改合並之后的配置項和數據，也記錄了用戶的交互狀態。

4.下面是幾個和echarts實例事件相關的方法

1）echartsInstance.dispatchAction(payload：Object)

觸發圖表行為。payload可以通過batch屬性同時觸發多個行為。

2）echartsInstance.on()

參數列表：

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

綁定事件處理函數。
Echarts的事件有兩種。一種是鼠標事件。還有一種是通過dispatchAction觸發的事件，每個action上都有對應的事件。
注意：如果事件是外部dispatchAction觸發，並且 action 中有 batch 屬性觸發批量的行為，則相應的響應事件參數里也會把屬性都放在 batch 屬性中。？？？

3）echartsInstance.off((eventName: string, handler?: Function))

解綁事件處理函數.handler是可選參數，可以傳入需要解綁的處理函數，如果不傳的話，則解綁事件下所有綁定的處理函數。

5.涉及到坐標系上的點的方法

1）echartsInstance.convertToPixel()

方法的參數列表：

(
    // finder 用於指示『使用哪個坐標系進行轉換』。
    // 通常地，可以使用 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
    },
    // 要被轉換的值。
    value: Array|string
    // 轉換的結果為像素坐標值，以 echarts 實例的 dom 節點的左上角為坐標 [0, 0] 點。
) => Array|string

轉換坐標系上的點到像素坐標值

2）echartsInstance.convertFromPixel()

方法列表參數：

(
    // finder 用於指示『使用哪個坐標系進行轉換』。
    // 通常地，可以使用 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
    },
    // 要被轉換的值，為像素坐標值，以 echarts 實例的 dom 節點的左上角為坐標 [0, 0] 點。
    value: Array|string
    // 轉換的結果，為邏輯坐標值。
) => Array|string

轉換像素坐標值到邏輯坐標系上的點，是convertToPixel的逆運算。

3）echartsInstance.containPixel

方法參數列表

(
    // finder 用於指示『在哪個坐標系或者系列上判斷』。
    // 通常地，可以使用 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
    },
    // 要被判斷的點，為像素坐標值，以 echarts 實例的 dom 節點的左上角為坐標 [0, 0] 點。
    value: Array
) => boolean

判斷指定的點是否在指定的坐標系或系列上。

6.其他的一些方法

1）echartsInstance.showLoading(type?: string, opts?: Object)

顯示加載動畫效果。可以在加載數據前手動調用該接口顯示加載動畫，在數據加載完成后調用 hideLoading 隱藏加載動畫。

• type
  可選。加載動畫類型。目前只有一種‘default’
• opts
  可選。加載動畫配置項，跟type有關。

2）echartsInstance.hideLoading()

隱藏動畫加載效果

3）echartsInstance.getDataURL()

參數列表

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

導出圖表圖片，返回一個base64的URL，可以設置為Image的src。

4）echartsInstance.getConnectedDataURL()

參數列表格式

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

導出聯動的圖表圖片，返回一個base64的url，可以設置為Image的src。導出圖片中每個圖表的相對位置跟容器的相對位置有關。

5）echartsInstance.appendData()

(opts: {
    // 要增加數據的系列序號。
    seriesIndex?: string,
    // 增加的數據。
    data?: Array|TypedArray,
}) => string

此接口用於，在大數據量（百萬以上）的渲染場景，分片加載數據和增量渲染。在大數據量的場景下（例如地理數的打點），就算數據使用二進制格式，也會有幾十或上百兆，在互聯網環境下，往往需要分片加載。appendData 接口提供了分片加載后增量渲染的能力，渲染新加入的數據塊時不會清除原有已經渲染的部分。
注意：

• 現在不支持 系列（series） 使用 dataset 同時使用 appendData，只支持系列使用自己的 series.data 時使用 appendData
• 目前並非所有的圖表都支持分片加載時的增量渲染。目前支持的圖有：ECharts 基礎版本的 散點圖（scatter） 和 線圖（lines）。ECharts GL 的 散點圖（scatterGL）、線圖（linesGL） 和 可視化建築群（polygons3D）

6）echartsInstance.clear()

清空當前實例。會移除實例中所有的組件和圖表。清空后調用getOption會返回一個{}空對象。

7）echartsInstance.isDisposed

當前實例是否已經被釋放

8）echartsInstance.dispose

銷毀實例。實例銷毀之后無法再被使用。