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

销毁实例。实例销毁之后无法再被使用。