{{ target: echarts-instance }}
通过 echarts.init 创建的实例。
图表的分组,用于联动
(option: Object, notMerge?: boolean, lazyUpdate?: boolean) or (option: Object, opts?: { notMerge?: boolean; replaceMerge?: string | string[]; lazyUpdate?: boolean; })
设置图表实例的配置项以及数据,万能接口,所有参数和数据的修改都可以通过 setOption
完成,ECharts 会合并新的参数和数据,然后刷新图表。如果开启动画的话,ECharts 找到两组数据之间的差异然后通过合适的动画去表现数据的变化。
如下示例:
注: ECharts 2.x 中的通过 addData
, setSeries
方法设置配置项的方式将不再支持,在 ECharts 3 中统一使用 setOption
,可以参考上面示例。
参数:
调用方式举例:
chart.setOption(option, notMerge, lazyUpdate);
或者
chart.setOption(option, { notMerge: ..., lazyUpdate: ..., silent: ... });
或者
chart.setOption(option, { replaceMerge: ['xAxis', 'yAxis', 'series'] });
option
: ECOption
图表的配置项和数据,具体见配置项手册。
opts
notMerge
: boolean
可选。是否不跟之前设置的 option
进行合并。默认为 false
。即表示合并。合并的规则,详见 组件合并模式。如果为 true
,表示所有组件都会被删除,然后根据新 option
创建所有新组件。
replaceMerge
: string
| string[]
可选。用户可以在这里指定一个或多个组件,如:xAxis
, series
,这些指定的组件会进行 “replaceMerge”。如果用户想删除部分组件,也可使用 “replaceMerge”。详见 组件合并模式。
lazyUpdate
: boolean
可选。在设置完 option
后是否不立即更新图表,默认为 false
,即同步立即更新。如果为 true
,则会在下一个 animation frame 中,才更新图表。
silent
: boolean
可选。阻止调用 setOption
时抛出事件,默认为 false
,即抛出事件。
组件合并模式
对于一种类型的组件(如:xAxis
, series
):
opts.notMerge
为true
,那么旧的组件会被完全移除,新的组件会根据option
创建。opts.notMerge
为false
,或者没有设置 opts.notMerge
:opts.replaceMerge
里指定组件类型,这类组件会进行替换合并
。普通合并
。什么是普通合并
和替换合并
?
普通合并
xAxis
, series
),新来的 option
中的每个“组件描述”(如:{type: 'xAxis', id: 'xx', name: 'kk', ...}
)会被尽量合并到已存在的组件中。剩余的情况,会在组件列表尾部创建新的组件。整体规则细节如下:option
中每个有声明 id
或者 name
的“组件描述”,寻找能匹配其 id
或者 name
的已有的组件,找到的话则合并。option
中剩余的“组件描述”,寻找还未执行过前一条的已有组件,找到的话则合并。option
中剩余的“组件描述”,用于在组件列表尾部创建新组件。id
和 name
没有在 option
中被指定(这是经常出现的情况),组件会按照它在 option
中的顺序一一合并到已有组件中。这种设定比较符合直觉。// 已有组件: { xAxis: [ { id: 'm', interval: 5 }, { id: 'n', name: 'nnn', interval: 6 } { id: 'q', interval: 7 } ] } // 新来的 option : chart.setOption({ xAxis: [ // id 没有指定。会寻找到第一个没有进行过合并的已有组件,进行合并。 // 即合并到 `id: 'q'`。 { interval: 77 }, // id 没有指定。最终会创建新组件。 { interval: 88 }, // id 没有指定,但是 name 指定了。会被合并到已有的 `name: 'nnn'` 组件。 { name: 'nnn', interval: 66 }, // id 指定了,会被合并到已有的 `id: 'm'` 组件。 { id: 'm', interval: 55 } ] }); // 结果组件: { xAxis: [ { id: 'm', interval: 55 }, { id: 'n', name: 'nnn', interval: 66 }, { id: 'q', interval: 77 }, { interval: 88 } ] }
替换合并
xAxis
, series
),只有 option
中指定了 id
并且已有组件中有此 id
时,已有组件会和 option
相应组件描述进行合并。否则,已有组件都会删除,新组件会被根据 option
创建。细节规则如下:option
中每个有声明 id
的“组件描述”,寻找能匹配其 id
或者 name
的已有的组件,找到的话则合并。option
中剩余的“组件描述”,创建新组件,填入刚因删除而空出来的位置上,或者增加到末尾。普通合并
相比,支持了组件删除。option
或者 API 中的 index 引用(例如:xAxisIndex: 2
)仍能正常一致得使用。// 已有组件: { xAxis: [ { id: 'm', interval: 5, min: 1000 }, { id: 'n', name: 'nnn', interval: 6, min: 1000 } { id: 'q', interval: 7, min: 1000 } ] } // 新来的 option : chart.setOption({ xAxis: [ { interval: 111 }, // id 已经指定了。因此会被合并进已有的组件 `id: 'q'`。 { id: 'q', interval: 77 }, // id 已经指定了。但是已有组件没有此 id 。 { id: 't', interval: 222 }, { interval: 333 } ] }, { replaceMerge: 'xAxis' }); // 结果组件: { xAxis: [ // 原来的 id 为 'm' 的组件,被移除。 // 替换为新的组件。新组件中,并没有原来的 `min: 1000` 了。 { interval: 111 }, // 原来的 id 为 'n' 的组件,被移除。 // 替换为新的组件。新组件中,并没有原来的 `min: 1000` 了。 { id: 't', interval: 222 }, // 原来的组件没有被移除,而是和 option 中的组件描述进行了合并。 // 所以 `min: 1000` 被保留了。 { id: 'q', interval: 77, min: 1000 }, // 新添加的组件。 { interval: 333 } ] }
删除组件
有两种方法能删除组件:
notMerge: true
,则所有组件都被删除。replaceMerge: [...]
,被指定的组件类型,会根据 replaceMerge 的规则:如果 id 匹配就合并( merge ),否则旧组件被删除,新组件被创建。“部分删除” 有助于,在删除该删除的组件时,保留其他组件的状态(如高亮、动画、选中状态)。() => number
获取 ECharts 实例容器的宽度。
() => number
获取 ECharts 实例容器的高度。
() => HTMLCanvasElement|HTMLDivElement
获取 ECharts 实例容器的 dom 节点。
() => Object
获取当前实例中维护的 option
对象,返回的 option
对象中包含了用户多次 setOption
合并得到的配置项和数据,也记录了用户交互的状态,例如图例的开关,数据区域缩放选择的范围等等。所以从这份 option
可以恢复或者得到一个新的一模一样的实例。
**注意:**返回的 option 每个组件的属性值都统一是一个数组,不管 setOption
传进来的时候是单个组件的对象还是多个组件的数组。如下形式:
{ title: [{...}], legend: [{...}], grid: [{...}] }
另外不推荐下面这种写法:
var option = myChart.getOption(); option.visualMap[0].inRange.color = ...; myChart.setOption(option);
因为 getOption
获取的是已经合并过默认值了的,所以在修改了某些配置项后会导致原本是根据这些配置项值去设置的默认值失效。
因此我们更推荐通过setOption
去修改部分配置。
myChart.setOption({ visualMap: { inRange: { color: ... } } })
(opts?: { width?: number|string, height?: number|string, silent?: boolean, animation?: { duration?: number easing?: string } }) => ECharts
改变图表尺寸,在容器大小发生改变时需要手动调用。
参数
opts
opts 可缺省。有下面几个可选项:
width
可显式指定实例宽度,单位为像素。如果传入值为 null
/undefined
/'auto'
,则表示自动取 dom
(实例容器)的宽度。
height
可显式指定实例高度,单位为像素。如果传入值为 null
/undefined
/'auto'
,则表示自动取 dom
(实例容器)的高度。
silent
是否禁止抛出事件。默认为 false
。
animation
resize 的时候是否应用过渡动画,包含时长duration
和缓动easing
两个配置,默认duration
为 0,即不应用过渡动画。
Tip: 有时候图表会放在多个标签页里,那些初始隐藏的标签在初始化图表的时候因为获取不到容器的实际高宽,可能会绘制失败,因此在切换到该标签页时需要手动调用 resize
方法获取正确的高宽并且刷新画布,或者在 opts
中显示指定图表高宽。
(payload: Object)
触发图表行为,例如图例开关legendToggleSelect
, 数据区域缩放dataZoom
,显示提示框showTip
等等,更多见 action 和 events 的文档。
payload
参数可以通过batch
属性同时触发多个行为。
**注:**在 ECharts 2.x 是通过 myChart.component.tooltip.showTip
这种形式调用相应的接口触发图表行为,入口很深,而且涉及到内部组件的组织。因此在 ECharts 3 里统一改为 dispatchAction
的形式。
示例
myChart.dispatchAction({ type: 'dataZoom', start: 20, end: 30 }); // 可以通过 batch 参数批量分发多个 action myChart.dispatchAction({ type: 'dataZoom', batch: [{ // 第一个 dataZoom 组件 start: 20, end: 30 }, { // 第二个 dataZoom 组件 dataZoomIndex: 1, start: 10, end: 20 }] })
( eventName: string, handler: Function, context?: Object ) ( eventName: string, query: string|Object, handler: Function, context?: Object )
绑定事件处理函数。
ECharts 中的事件有两种,一种是鼠标事件,在鼠标点击某个图形上会触发,还有一种是 调用 dispatchAction 后触发的事件。每个 action 都会有对应的事件,具体见 action 和 events 的文档。
如果事件是外部 dispatchAction 后触发,并且 action 中有 batch 属性触发批量的行为,则相应的响应事件参数里也会把属性都放在 batch 属性中。
参数:
eventName
事件名称,全小写,例如'click'
,'mousemove'
, 'legendselected'
注: ECharts 2.x 中会使用 config
对象中的 CLICK
等属性作为事件名称。在 ECharts 3 中统一使用跟 dom 事件一样的全小写字符串作为事件名。
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' 时,此方法被回调。 });
handler
事件处理函数。格式为:
(event: Object)
context
可选。回调函数内部的context
,即this
的指向。
(eventName: string, handler?: Function)
解绑事件处理函数。
参数:
eventName
事件名称。
handler
可选,可以传入需要解绑的处理函数,不传的话解绑所有该类型的事件函数。
( // 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
转换坐标系上的点到像素坐标值。
例:
在地理坐标系(geo)上,把某个点的经纬度坐标转换成为像素坐标:
// [128.3324, 89.5344] 表示 [经度,纬度]。 // 使用第一个 geo 坐标系进行转换: chart.convertToPixel('geo', [128.3324, 89.5344]); // 参数 'geo' 等同于 {geoIndex: 0} // 使用第二个 geo 坐标系进行转换: chart.convertToPixel({geoIndex: 1}, [128.3324, 89.5344]); // 使用 id 为 'bb' 的 geo 坐标系进行转换: chart.convertToPixel({geoId: 'bb'}, [128.3324, 89.5344]);
在直角坐标系(cartesian,grid)上,把某个点的坐标转换成为像素坐标:
// [300, 900] 表示该点 x 轴上对应刻度值 300,y 轴上对应刻度值 900。 // 注意,一个 grid 可能含有多个 xAxis 和多个 yAxis,任何一对 xAxis-yAxis 形成一个 cartesian。 // 使用第三个 xAxis 和 id 为 'y1' 的 yAxis 形成的 cartesian 进行转换: chart.convertToPixel({xAxisIndex: 2, yAxisId: 'y1'}, [300, 900]); // 使用 id 为 'g1' 的 grid 的第一个 cartesian 进行转换: chart.convertToPixel({gridId: 'g1'}, [300, 900]);
把某个坐标轴的点转换成像素坐标:
// id 为 'x0' 的 xAxis 的刻度 3000 位置所对应的横向像素位置: chart.convertToPixel({xAxisId: 'x0'}, 3000); // 返回一个 number。 // 第二个 yAxis 的刻度 600 位置所对应的纵向像素位置: chart.convertToPixel({yAxisIndex: 1}, 600); // 返回一个 number。
把关系图(graph)的点转换成像素坐标:
// 因为每个 graph series 自己持有一个坐标系,所以我们直接在 finder 中指定 series: chart.convertToPixel({seriesIndex: 0}, [2000, 3500]); chart.convertToPixel({seriesId: 'k2'}, [100, 500]);
在某个系列所在的坐标系(无论是 cartesian、geo、graph 等)中,转换某点成像素坐标:
// 使用第一个系列对应的坐标系: chart.convertToPixel({seriesIndex: 0}, [128.3324, 89.5344]); // 使用 id 为 'k2' 的系列所对应的坐标系: chart.convertToPixel({seriesId: 'k2'}, [128.3324, 89.5344]);
( // 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 的逆运算。 具体实例可参考 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 }, // 要被判断的点,为像素坐标值,以 echarts 实例的 dom 节点的左上角为坐标 [0, 0] 点。 value: Array ) => boolean
判断给定的点是否在指定的坐标系或者系列上。
目前支持在这些坐标系和系列上进行判断:grid, polar, geo, series-map, series-graph, series-pie。
例:
// 判断 [23, 44] 点是否在 geoIndex 为 0 的 geo 坐标系上。 chart.containPixel('geo', [23, 44]); // 'geo' 等同于 {geoIndex: 0} // 判断 [23, 44] 点是否在 gridId 为 'z' 的 grid 上。 chart.containPixel({gridId: 'z'}, [23, 44]); // 判断 [23, 44] 点是否在 index 为 1,4,5 的系列上。 chart.containPixel({seriesIndex: [1, 4, 5]}, [23, 44]); // 判断 [23, 44] 点是否在 index 为 1,4,5 的系列或者 gridName 为 'a' 的 grid 上。 chart.containPixel({seriesIndex: [1, 4, 5], gridName: 'a'}, [23, 44]);
(type?: string, opts?: Object)
显示加载动画效果。可以在加载数据前手动调用该接口显示加载动画,在数据加载完成后调用 hideLoading 隐藏加载动画。
参数:
type
可选,加载动画类型,目前只有一种'default'
opts
可选,加载动画配置项,跟type
有关,下面是默认配置项:
default: { text: ‘loading’, color: ‘#c23531’, textColor: ‘#000’, maskColor: ‘rgba(255, 255, 255, 0.8)’, zlevel: 0,
// 字体大小。从 `v4.8.0` 开始支持。 fontSize: 12, // 是否显示旋转动画(spinner)。从 `v4.8.0` 开始支持。 showSpinner: true, // 旋转动画(spinner)的半径。从 `v4.8.0` 开始支持。 spinnerRadius: 10, // 旋转动画(spinner)的线宽。从 `v4.8.0` 开始支持。 lineWidth: 5, // 字体粗细。从 `v5.0.1` 开始支持。 fontWeight: 'normal', // 字体风格。从 `v5.0.1` 开始支持。 fontStyle: 'normal', // 字体系列。从 `v5.0.1` 开始支持。 fontFamily: 'sans-serif'
} ```
隐藏动画加载效果。
(opts: { // 导出的格式,可选 png, jpeg type?: string, // 导出的图片分辨率比例,默认为 1。 pixelRatio?: number, // 导出的图片背景色,默认使用 option 里的 backgroundColor backgroundColor?: string, // 忽略组件的列表,例如要忽略 toolbox 就是 ['toolbox'] excludeComponents?: Array.<string> }) => string
导出图表图片,返回一个 base64 的 URL,可以设置为Image
的src
。
示例:
var img = new Image(); img.src = myChart.getDataURL({ pixelRatio: 2, backgroundColor: '#fff' });
(opts: { // 导出的格式,可选 png, jpeg type?: string, // 导出的图片分辨率比例,默认为 1。 pixelRatio?: number, // 导出的图片背景色,默认使用 option 里的 backgroundColor backgroundColor?: string, // 忽略组件的列表,例如要忽略 toolbox 就是 ['toolbox'] excludeComponents?: Array.<string> }) => string
导出联动的图表图片,返回一个 base64 的 url,可以设置为Image
的src
。导出图片中每个图表的相对位置跟容器的相对位置有关。
(opts: { // 要增加数据的系列序号。 seriesIndex?: string, // 增加的数据。 data?: Array|TypedArray }) => string
此接口用于,在大数据量(百万以上)的渲染场景,分片加载数据和增量渲染。在大数据量的场景下(例如地理数的打点),就算数据使用二进制格式,也会有几十或上百兆,在互联网环境下,往往需要分片加载。appendData
接口提供了分片加载后增量渲染的能力,渲染新加入的数据块时不会清除原有已经渲染的部分。
注意:
appendData
,只支持系列使用自己的 series.data 时使用 appendData
。清空当前实例,会移除实例中所有的组件和图表。
() => boolean
当前实例是否已经被释放。
销毁实例,销毁后实例无法再被使用。