From: http://echarts.baidu.com/doc/doc.html
简介
ECharts,缩写来自Enterprise Charts,商业级数据图表,一个纯Javascript的图表库,可以流畅的运行在PC和移动设备上,兼容当前绝大部分浏览器(IE6/7/8/9/10/11,chrome,firefox,Safari等),底层依赖轻量级的Canvas类库ZRender,提供直观,生动,可交互,可高度个性化定制的数据可视化图表。创新的拖拽重计算、数据视图、值域漫游等特性大大增强了用户体验,赋予了用户对数据进行挖掘、整合的能力。
支持折线图(区域图)、柱状图(条状图)、散点图(气泡图)、K线图、饼图(环形图)、雷达图(填充雷达图)、和弦图、力导向布局图、地图、仪表盘、漏斗图、事件河流图等12类图表,同时提供标题,详情气泡、图例、值域、数据区域、时间轴、工具箱等7个可交互组件,支持多图表、组件的联动和混搭展现。
名词解析
基本名词
名词 | 描述 |
---|---|
chart | 是指一个完整的图表,如折线图,饼图等“基本”图表类型或由基本图表组合而成的“混搭”图表,可能包括坐标轴、图例等 |
axis | 直角坐标系中的一个坐标轴,坐标轴可分为类目型、数值型或时间型 |
xAxis | 直角坐标系中的横轴,通常并默认为类目型 |
yAxis | 直角坐标系中的纵轴,通常并默认为数值型 |
grid | 直角坐标系中除坐标轴外的绘图网格,用于定义直角系整体布局 |
legend | 图例,表述数据和图形的关联 |
dataRange | 值域选择,常用于展现地域数据时选择值域范围 |
dataZoom | 数据区域缩放,常用于展现大量数据时选择可视范围 |
roamController | 缩放漫游组件,搭配地图使用 |
toolbox | 辅助工具箱,辅助功能,如添加标线,框选缩放等 |
tooltip | 气泡提示框,常用于展现更详细的数据 |
timeline | 时间轴,常用于展现同一系列数据在时间维度上的多份数据 |
series | 数据系列,一个图表可能包含多个系列,每一个系列可能包含多个数据 |
图表名词
名词 | 描述 |
---|---|
line | 折线图,堆积折线图,区域图,堆积区域图。 |
bar | 柱形图(纵向),堆积柱形图,条形图(横向),堆积条形图。 |
scatter | 散点图,气泡图。散点图至少需要横纵两个数据,更高维度数据加入时可以映射为颜色或大小,当映射到大小时则为气泡图 |
k | K线图,蜡烛图。常用于展现股票交易数据。 |
pie | 饼图,圆环图。饼图支持两种(半径、面积)南丁格尔玫瑰图模式。 |
radar | 雷达图,填充雷达图。高维度数据展现的常用图表。 |
chord | 和弦图。常用于展现关系数据,外层为圆环图,可体现数据占比关系,内层为各个扇形间相互连接的弦,可体现关系数据 |
force | 力导布局图。常用于展现复杂关系网络聚类布局。 |
map | 地图。内置世界地图、中国及中国34个省市自治区地图数据、可通过标准GeoJson扩展地图类型。支持svg扩展类地图应用,如室内地图、运动场、物件构造等。 |
gauge | 仪表盘。用于展现关键指标数据,常见于BI类系统。 |
funnel | 漏斗图。用于展现数据经过筛选、过滤等流程处理后发生的数据变化,常见于BI类系统。 |
evnetRiver | 事件河流图。常用于展示具有时间属性的多个事件,以及事件随时间的演化。 |
funnel | 漏斗图。用于展现数据经过筛选、过滤等流程处理后发生的数据变化,常见于BI类系统。 |
evnetRiver | 事件河流图。常用于展示具有时间属性的多个事件,以及事件随时间的演化。 |
treemap | 矩形式树状结构图,简称:矩形树图。用于展示树形数据结构,优势是能最大限度展示节点的尺寸特征。 |
venn | 韦恩图。用于展示集合以及它们的交集。 |
图表类型
图表库标准包含单图表类型的标准图表以及多图表类型混合的混搭图表:
单图表类型:line
折线图 | 堆积折线图 | 区域图 | 堆积区域图 |
---|---|---|---|
单图表类型:bar
柱形图 | 堆积柱形图 | 条形图 | 堆积条形图 |
---|---|---|---|
单图表类型:scatter
散点图 | 气泡图 | |
---|---|---|
单图表类型:k
K线图 | |
---|---|
单图表类型:pie
饼图 | 圆环图 | 南丁格尔玫瑰图 |
---|---|---|
单图表类型:radar
雷达图 | 填充雷达图 |
---|---|
单图表类型:chord
和弦图 | |
---|---|
单图表类型:force
力导向布局图。 | ||
---|---|---|
单图表类型:map
中国地图 | 全国34个省市自治区 | 世界地图 |
---|---|---|
子区域模式 | 标准GeoJson扩展 | SVG扩展 |
单图表类型:gauge
仪表盘 | |
---|---|
单图表类型:funnel
漏斗图 | ||
---|---|---|
单图表类型:eventRiver
事件河流图 | ||
---|---|---|
单图表类型:treemap
矩形树图 | |
---|---|
单图表类型:venn
韦恩图类型 |
---|
引入ECharts
echarts提供多种引入方式,请根据你的项目类型选择合适的方式:
模块化包引入
如果你熟悉模块化开发,你的项目本身就是模块化且遵循AMD规范的,那引入echarts将很简单,使用一个符合AMD规范的模块加载器,如esl.js,只需要配置好packages路径指向src即可,你将享受到图表的按需加载等最大的灵活性,由于echarts依赖底层zrender,你需要同时下载zrender到本地,可参考demo,你需要配置如下。
需要注意的是,包引入提供了开发阶段最大的灵活性,但并不适合直接上线,减少请求的文件数量是前端性能优化中最基本但很重要的规则,务必在上线时做文件的连接压缩。
//from echarts example require.config({ packages: [ { name: 'echarts', location: '../../src', main: 'echarts' }, { name: 'zrender', location: '../../../zrender/src', // zrender与echarts在同一级目录 main: 'zrender' } ] });
模块化单文件引入(推荐)
如果你使用模块化开发但并没有自己的打包合并环境,或者说你不希望在你的项目里引入第三方库的源文件,我们建议你使用单文件引入,同模块化包引入一样,你需要熟悉模块化开发。
自2.1.8起,我们为echarts开发了专门的合并压缩工具echarts-optimizer。如你所发现的,build文件夹下已经包含了由echarts-optimizer生成的单文件:
- dist(文件夹) : 经过合并、压缩的单文件
-
- echarts.js : 这是包含AMD加载器的echarts主文件,需要通过script最先引入
- chart(文件夹) : echarts-optimizer通过依赖关系分析同时去除与echarts.js的重复模块后为echarts的每一个图表类型单独打包生成一个独立文件,根据应用需求可实现图表类型按需加载
- echarts-line.js : 折线图(如需折柱动态类型切换,require时还需要echarts/chart/bar)
- echarts-bar.js : 柱形图(如需折柱动态类型切换,require时还需要echarts/chart/line)
- echarts-scatter.js : 散点图
- echarts-k.js : K线图
- echarts-pie.js : 饼图(如需饼漏斗图动态类型切换,require时还需要echarts/chart/funnel)
- echarts-radar.js : 雷达图
- echarts-map.js : 地图
- echarts-force.js : 力导向布局图(如需力导和弦动态类型切换,require时还需要echarts/chart/chord)
- echarts-chord.js : 和弦图(如需力导和弦动态类型切换,require时还需要echarts/chart/force)
- echarts-funnel.js : 漏斗图(如需饼漏斗图动态类型切换,require时还需要echarts/chart/pie)
- echarts-gauge.js : 仪表盘
- echarts-eventRiver.js : 事件河流图
- source(文件夹) : 经过合并,但并没有压缩的单文件,内容同dist,可用于调试
采用单一文件使用例子见ECharts单一文件引入,存放在example/www下,首先你需要通过script标签引入echarts主文件
//from echarts example <body> <div id="main" style="height:400px;"></div> ... <script src="./js/echarts.js"></script> </body>
在主文件引入后你将获得一个AMD环境,配置require.conifg如下:
//from echarts example <body> <div id="main" style="height:400px;"></div> ... <script src="./js/echarts.js"></script> <script type="text/javascript"> require.config({ paths: { echarts: './js/dist' } }); </script> </body>
require.config配置后就可以通过动态加载使用echarts
//from echarts example <body> <div id="main" style="height:400px;"></div> ... <script src="./js/echarts.js"></script> <script type="text/javascript"> require.config({ paths: { echarts: './js/dist' } }); require( [ 'echarts', 'echarts/chart/line', // 按需加载所需图表,如需动态类型切换功能,别忘了同时加载相应图表 'echarts/chart/bar' ], function (ec) { var myChart = ec.init(document.getElementById('main')); var option = { ... } myChart.setOption(option); } ); </script> </body>
总结来说,模块化单文件引入ECharts,你需要如下4步:
- 为ECharts准备一个具备大小(宽高)的Dom(当然可以是动态生成的)
- 通过script标签引入echarts主文件
- 为模块加载器配置echarts的路径,从当前页面链接到echarts.js所在目录,见上述说明
- 动态加载echarts及所需图表然后在回调函数中开始使用(容我罗嗦一句,当你确保同一页面已经加载过echarts,再使用时直接require('echarts').init(dom)就行)
标签式单文件引入
自1.3.5开始,ECharts提供标签式引入。如果你的项目本身并不是基于模块化开发的,或者是基于CMD规范(如使用的是seajs),那么引入基于AMD模块化的echarts可能并不方便,我们建议你采用srcipt标签式引入,忘掉require。Srcipt标签引入echarts后将可以直接使用两个全局的命名空间:echarts,zrender,可参考ECharts标签式引入,需要注意的是excanvas依赖body标签插入Canvas节点去判断Canvas的支持,如果你把引用echarts的script标签放置head内在IE8-的浏览器中会出现报错,解决的办法就是把标签移动到body内(后)。
标签式引入环境中,常用模块的引用可通过命名空间直取,同模块化下的路径结构,如:
echarts.config = require('echarts/config'), zrender.tool.color = require('zrender/tool/color')
//from echarts example <body> <div id="main" style="height:400px;"></div> ... <script src="example/www2/js/dist/echarts-all.js"></script> <script> var myChart = echarts.init(document.getElementById('main')); var option = { ... } myChart.setOption(option); </script> </body>
可以直接引入的单文件如下:
- dist/echarts-all.js : 经过压缩,全图表,包含world,china以及34个省市级地图数据
- source/echarts-all.js : 未压缩,全图表,包含world,china以及34个省市级地图数据,可用于调试
自定义构建echarts单文件
详见 echarts-optimizer 安装使用说明:README.md
初始化
通过require获得echarts接口(或者命名空间)后可实例化图表,echarts接口仅有一个方法init,执行init时传入一个具备大小的dom节点(width、height可被计算得到即可,不一定可见)后即可实例化出图表对象,图表库实现为多实例的,同一页面可在多个dom上init出多个图表,同一个dom上多次init将自动释放已有实例(1.4.0+)。init方法说明如下:
名称 | 参数 | 描述 |
---|---|---|
{ECharts}init | {dom} dom, {string | Object =} theme |
初始化接口,返回ECharts实例,其中dom为图表所在节点,theme为可选的主题,内置主题('macarons', 'infographic')直接传入名称,自定义扩展主题可传入主题对象。如: var myCharts = echarts.init(document.getElementById('main'), 'macarons'); |
图表实例可用方法见方法
引入ECharts后的的初始化代码如下:
// 作为入口 require( [ 'echarts', 'echarts/chart/pie' ], function (ec) { var myChart = ec.init(document.getElementById('main')); myChart.setOption({...}); } ); // ----------------------------- // 非入口或再次使用,图表已被加载注册 require('echarts').init(dom).setOption({...}); // 如果需要再次使用ECharts的图表实例,建议你还是保存init返回的图表实例吧 var myChart = require('echarts').init(dom); myChart.setOption({...});
熟悉模块化的你可以跳过了下面代码了
// 不习惯模块化的你当然可以 var echarts; require(['echarts'], function (ec){ echarts = ec; }); // 是的,把echarts加载后保存起来作为命名空间使用
实例方法
实例指的就是接口init()返回的对象,即上述代码中的“myChart”,非get接口均返回自身self支持链式调用
名称 | 参数 | 描述 |
---|---|---|
{self}setOption | {Object} option, {boolean=}notMerge |
万能接口,配置图表实例任何可配置选项(详见option),多次调用时option选项默认是合并(merge)的,merge的设计可以让setOption很方便的成为更新任何属性的万能方法,比如你仅需要改title文字,则仅需要: setOption({title : {text : '新标题'}}); 如果不需要,可以通过notMerger参数为true阻止与上次option的合并,如多次setOption间数据改变、长度不一致等的场景。 2.0.0起支持timeline组件,option中包含timeline(详见timeline)时每一个独立的option应该放置到命名为options的数组内,如 myCharts.setOption({ timeline : {...}, options : [ { // option1 title : {...}, series : [...] }, {...}, // option2 ... ] }); |
{Object}getOption | {void} | 返回内部持有的当前显示option克隆(拷贝)。 |
{self} setSeries | {Array} series, {boolean=}notMerge |
数据接口,驱动图表生成的数据内容(详见series),效果等同调用 setOption({series : {...}}, notMerge) |
{Object}getSeries | {void} | 返回内部持有的当前显示series克隆(拷贝),效果同 getOption().series |
{self}addData | 单组数据: {number} seriesIdx {number | Object}data {boolean=} isHead {boolean=}dataGrow {string=}additionData 多组数据添加: {Array} params |
动态数据接口,try this (Line & Bar) » try this (Scatter & K) » try this (Pie & Radar) » seriesIdx 系列索引 data 增加数据 isHead 是否队头加入,默认,不指定或false时为队尾插入 dataGrow 是否增长数据队列长度,默认,不指定或false时移出目标数组对位数据 additionData 是否增加类目轴(饼图为图例)数据,附加操作同isHead和dataGrow 多组数据添加时参数为: params == [[seriesIdx, data, isHead, dataGrow, additionData], [...]] |
{self}addMarkPoint | {number} seriesIdx {Object} markData |
新增标注接口,其中 seriesIdx 系列索引 markData [标注]对象,同series.markPoint,支持多个 |
{self}addMarkLine | {number} seriesIdx {Object} markData |
新增标线接口,其中 seriesIdx 系列索引 markData [标线]对象,同series.markLine,支持多个 |
{self}delMarkPoint | {number} seriesIdx {string} markName |
删除单个标注接口,其中 seriesIdx 系列索引 markName [标注]名称 |
{self}delMarkLine | {number} seriesIdx {string} markName |
删除单个标线接口,其中 seriesIdx 系列索引 markName [标线]名称,已构建的标线名称默认为markLine数据中起始点的name,如果同时终点也有name属性,如地图标线,则标线名称等于“nameStart > nameEnd”,如markLine的data为 [{name:'北京', value:100}, {name:'上海'}] 则删除该标线时传入的markName为 "北京 > 上海" |
{self} on | {string} eventName, {Function}eventListener |
事件绑定,事件命名统一挂载到require('echarts/config').EVENT(非模块化为echarts.config.EVENT)命名空间下,建议使用此命名空间作为事件名引用,当前版本支持事件有: -----------------------基础事件----------------------- REFRESH(刷新), RESTORE(还原), RESIZE(显示空间变化), CLICK(点击), DBLCLICK(双击), HOVER(悬浮), MOUSEOUT(鼠标离开数据图形), ---------------------交互逻辑事件-------------------- DATA_CHANGED(数据修改,如拖拽重计算), DATA_VIEW_CHANGED(数据视图修改), MAGIC_TYPE_CHANGED(动态类型切换), TIMELINE_CHANGED(时间轴变化), DATA_ZOOM(数据区域缩放), DATA_RANGE(值域漫游), DATA_RANGE_SELECTED(值域开关选择), DATA_RANGE_HOVERLINK(值域漫游hover), LEGEND_SELECTED(图例开关选择), LEGEND_HOVERLINK(图例hover), MAP_ROAM(地图漫游), MAP_SELECTED(地图选择), PIE_SELECTED(饼图选择), FORCE_LAYOUT_END(力导向布局结束) 事件调试 » |
{self} un | {string} eventName, {Function}eventListener |
事件解绑定 |
{self}setTheme | {string | Object}theme | 设置主题,内置主题('macarons', 'infographic')直接传入名称,自定义扩展主题可传入主题对象 |
{self} connect | {ECharts | Array <ECharts>}connectTarget | 多图联动,传入联动目标为EChart实例,支持数组。多图联动支持直角系下tooltip联动,保存图片的自动拼接,同时支持的联动事件有: REFRESH,RESTORE,MAGIC_TYPE_CHANGED DATA_ZOOM,DATA_RANGE,LEGEND_SELECTED 多图联动 » |
{self}disConnect | {ECharts | Array <ECharts>}connectTarget | 解除已连结的多图联动 |
{self}showLoading | {Object}loadingOption | 过渡控制(详见loadingOption),显示loading(读取中) try this » |
{self}hideLoading | {void} | 过渡控制,隐藏loading(读取中) |
{ZRender}getZrender | {void} | 获取当前图表所用ZRender实例,可用于添加额外图形或进行深度定制,zrender接口详见ZRender |
{string}getDataURL | {string=} imgType | 获取当前图表的Base64图片dataURL,IE8-不支持,imgType 图片类型,支持png|jpeg,默认为png |
{Dom}getImage | {string=} imgType | 获取一个当前图表的img,imgType 图片类型,支持png|jpeg,默认为png |
{self} resize | {void} | ECharts没有绑定resize事件,显示区域大小发生改变内部并不知道,使用方可以根据自己的需求绑定关心的事件,主动调用resize达到自适应的效果,常见如window.onresize = myChart.resize。 |
{self} refresh | {void} | 刷新图表,图例选择、数据区域缩放,拖拽状态均保持。 |
{self} restore | {void} | 还原图表,各种状态均被清除,还原为最初展现时的状态。 |
{self} clear | {void} | 清空绘画内容,清空后实例可用 |
{void} dispose | {void} | 释放图表实例,释放后实例不再可用 |
选项
option
图表选项,包含图表实例任何可配置选项: 公共选项 , 组件选项 , 数据选项
名称 | 描述 |
---|---|
{color}backgroundColor | 全图默认背景,(详见backgroundColor),支持rgba,默认为无,透明 |
{Array} color | 数值系列的颜色列表,(详见color),可配数组,eg:['#87cefa', 'rgba(123,123,123,0.5)','...'],当系列数量个数比颜色列表长度大时将循环选取 |
{boolean}renderAsImage | 非IE8-支持渲染为图片,(详见renderAsImage) |
{boolean}calculable | 是否启用拖拽重计算特性,默认关闭,(详见calculable,相关的还有 calculableColor, calculableHolderColor,nameConnector, valueConnector) |
{boolean}animation | 是否开启动画,默认开启,(详见 animation,相关的还有 addDataAnimation, animationThreshold,animationDuration, animationDurationUpdate , animationEasing) |
{Object} timeline | 时间轴(详见timeline),每个图表最多仅有一个时间轴控件 |
{Object} title | 标题(详见title),每个图表最多仅有一个标题控件 |
{Object} toolbox | 工具箱(详见toolbox),每个图表最多仅有一个工具箱 |
{Object} tooltip | 提示框(详见tooltip),鼠标悬浮交互时的信息提示 |
{Object} legend | 图例(详见legend),每个图表最多仅有一个图例,混搭图表共享 |
{Object}dataRange | 值域选择(详见dataRange),值域范围 |
{Object}dataZoom | 数据区域缩放(详见dataZoom),数据展现范围选择 |
{Object}roamController | 漫游缩放组件(详见roamController),搭配地图使用 |
{Object} grid | 直角坐标系内绘图网格(详见grid) |
{Array | Object}xAxis | 直角坐标系中横轴数组(详见xAxis),数组中每一项代表一条横轴坐标轴,标准(1.0)中规定最多同时存在2条横轴 |
{Array | Object}yAxis | 直角坐标系中纵轴数组(详见yAxis),数组中每一项代表一条纵轴坐标轴,标准(1.0)中规定最多同时存在2条纵轴 |
{Array} series | 驱动图表生成的数据内容(详见series),数组中每一项代表一个系列的特殊选项及数据 |
timeline
时间轴,每个图表最多仅有一个时间轴控件,try bar »、scatter »、pie »、map »
名称 | 默认值 | 描述 |
---|---|---|
{boolean} show | true | 显示策略,可选为:true(显示) | false(隐藏) |
{number} zlevel | 0 | 一级层叠控制。每一个不同的zlevel将产生一个独立的canvas,相同zlevel的组件或图标将在同一个canvas上渲染。zlevel越高越靠顶层,canvas对象增多会消耗更多的内存和性能,并不建议设置过多的zlevel,大部分情况可以通过二级层叠控制z实现层叠控制。 |
{number} z | 4 | 二级层叠控制,同一个canvas(相同zlevel)上z越高约靠顶层。 |
{string} type | 'time' | 模式是时间类型,时间轴间隔根据时间跨度自动计算,可选为:'number' |
{boolean}notMerge | false | 时间轴上多个option切换时是否进行merge操作,同setOption第二个参数(详见实例方法) |
{boolean}realtime | true | 拖拽或点击改变时间轴是否实时显示,在不支持Canvas的浏览器中该值自动强制置为false |
{number | string}x | 80 | 时间轴左上角横坐标,数值单位px,支持百分比(字符串),如'50%'(显示区域横向中心) |
{number | string}y | null | 时间轴左上角纵坐标,数值单位px,支持百分比(字符串),默认无,随y2定位,如'50%'(显示区域纵向中心) |
{number | string}x2 | 80 | 时间轴右下角横坐标,数值单位px,支持百分比(字符串),如'50%'(显示区域横向中心) |
{number | string}y2 | 0 | 时间轴右下角纵坐标,数值单位px,支持百分比(字符串),如'50%'(显示区域纵向中心) |
{number} width | 自适应 | 时间轴宽度,默认为总宽度 - x - x2,数值单位px,指定width后将忽略x2。见下图。 支持百分比(字符串),如'50%'(显示区域一半的宽度) |
{number} height | 50 | 时间轴高度,数值单位px,支持百分比(字符串),如'50%'(显示区域一半的高度) |
{color}backgroundColor | 'rgba(0,0,0,0)' | 背景颜色,默认透明。 |
{number}borderWidth | 0 | 边框线宽 |
{color}borderColor | '#ccc' | 边框颜色。 |
{number | Array}padding | 5 | 内边距,单位px,默认各方向内边距为5,接受数组分别设定上右下左边距,同css,见下图 |
{string}controlPosition | 'left' | 播放控制器位置,可选为:'left' | 'right' | 'none' |
{boolean}autoPlay | false | 是否自动播放 |
{boolean} loop | true | 是否循环播放 |
{number}playInterval | 2000 | 播放时间间隔,单位ms |
{Object} lineStyle | { color: '#666', width: 1, type: 'dashed' } |
时间轴轴线样式,lineStyle控制线条样式,(详见lineStyle) |
{Object} label |