ECharts 是一个基于 JavaScript 实现的开源商业级数据图表库(Enterprise Charts),可用于生成一些诸如:折线图、柱状图、饼图、散点图、K线图、雷达图、热力图、仪表盘、数据地图、河流图等行业数据图形。ECharts 最初由百度团队开源,2018年初捐赠给Apache基金会,成为ASF孵化级项目,2021年初 Apache 官方宣布 ECharts 项目正式毕业并推出 5.0 版别。
其他数据可视化库还有:D3.js、Highchats.js、AntV 等。

引入 ECharts

script 标签引入

<script src="https://cdn.bootcdn.net/ajax/libs/echarts/5.0.2/echarts.min.js"></script>

打包环境中使用

// npm 安装
npm install echarts --save
// 注意 5.x 版别之后不能直接 import echarts from 'echarts';
import * as echarts from 'echarts';

Vue 项目中建议直接挂载到 Vue 原型上,方便后期调用

import * as echarts from 'echarts'
Vue.prototype.$echarts = echarts

指定用于显示的容器

ECharts 输出的内容需要包裹在一个固定宽高的容器内,所以在使用之前我们需要创建一个 HTML 标签。

<!-- ECharts 显示的容器 -->
<div id="echarts-dom" style="width: 600px;height:400px;"></div>

实例化 ECharts

ECharts 是一个 JavaScript 全局对象,在使用前我们需要将其实例化,本质为 new 了一个 ZRender 对象源码如下:

// 不让用户在外部直接 new ZRender 实例,主要是为了减少全局污染和降低命名冲突的风险
function init(dom, opts) {
    var zr = new ZRender(guid(), dom, opts);
    instances[zr.id] = zr;
    return zr;
}

所以我们实际使用时通过 init 方法初始化的图表对象。

// 获取用于显示 ECharts 的 DOM 容器
const echartsDom = document.getElementById('echarts-dom');
// 初始化 ECharts
let echartsInstance  = echarts.init(echartsDom);

ECharts 配置项 setOption

ECharts 支持折线图、柱状图、饼图、散点图、K线图、雷达图、热力图、仪表盘、数据地图、河流图等多种数据图表,具体需要生成何种图表需要我们通过 setOption 传入对应的配置及数据以生成所需的内容。下面简单介绍下 ECharts 各项参数的作用。

常用配置组件

  • title :标题组件,用于设置图表的标题内容
  • grid :网格组件,在直角坐标系内绘制网格,方便对比数据
  • toolbox :工具箱组件,给图表添加一些工具按钮,比如:下载、框选、切换图表类型

图形系列组件

  • series :系列组件,根据传入的数据生成对应的图表内容系列
  • legend :图例组件,图表上用于指示不同内容的标记
  • tooltip :提示框组件,用于设置图表的提示信息

坐标系组件

  • xAxis :坐标轴组件,直角坐标系的 x 轴,多于两个 x 轴需要配置 offset 防止同一位置多个 x 轴的重叠
  • yAxis :坐标轴组件,直角坐标系的 y 轴,多于两个 y 轴需要配置 offset 防止同一位置多个 y 轴的重叠
  • axisPointer :坐标轴组件,坐标轴指示器,就是鼠标悬浮时的虚线,十字或一字,方便指示数据
  • polar :极坐标系,表明当前图表采用极坐标系,可设置极坐标系的原点及半径等属性
  • radiusAxis :坐标轴组件,极坐标系的径向轴
  • angleAxis :坐标轴组件,极坐标系的角度轴
  • radar :雷达图坐标系,只用于生成一个雷达图
  • geo :地理坐标系,用于地图的绘制,支持在地理坐标系上绘制散点图,线集
  • singleAxis :坐标轴组件,一维坐标系中的坐标轴
  • parallel :平行坐标系,表明当前图表采用平行坐标系,每一行是一个数据项,每一列属于一个维度
  • parallelAxis :坐标轴组件,平行坐标系中的坐标轴
  • calendar :日历坐标系组件,添加一个日历坐标系,方便实现日历图
  • timeline :时间线组件,表明当前图表采用时间线方式展示,此时需在 options 中传入多组配置对象
  • options :用于时间线组件的配置对象

样式组件

  • darkMode :暗黑模式,echarts 会根据是否是暗黑模式调整文本等的颜色
  • textStyle :全局的字体样式
  • color :调色盘颜色列表,如果系列没有设置颜色,则会依次循环从该列表中取颜色作为系列颜色
  • backgroundColor :背景色,默认无背景,你可以根据需要自定义背景色
  • media :移动端自适应,类似 CSS Media Query 的自适应

动画组件

  • animation :是否开启动画
  • animationThreshold :是否开启动画的阈值,当单个系列显示的图形数量大于这个阈值时会关闭动画
  • animationDuration :初始动画的时长,支持回调函数,可以通过每个数据返回不同的时长实现更戏剧的初始动画效果
  • animationEasing :初始动画的缓动效果
  • animationDelay :初始动画的延迟,支持回调函数,可以通过每个数据返回不同的 delay 时间实现更戏剧的初始动画效果
  • animationDurationUpdate :数据更新动画的时长,支持回调函数,可以通过每个数据返回不同的时长实现更戏剧的更新动画效果
  • animationEasingUpdate :数据更新动画的缓动效果
  • animationDelayUpdate :数据更新动画的延迟,支持回调函数,可以通过每个数据返回不同的 delay 时间实现更戏剧的更新动画效果
  • stateAnimation :状态切换的动画配置,支持在每个系列里设置单独针对该系列的配置

杂项组件

  • dataZoom :区域缩放组件,用于设置图表随鼠标滚轮或拖拽放大缩小
  • brush :区域选择组件,根据设置展示用户选中数据区间的统计结果
  • visualMap :视觉映射组件,用于进行视觉编码,也就是将数据映射到视觉元素(视觉通道)
  • graphic :图形元素组件,原生的图形元素组件。支持:image、text、circle、sector、ring、polygon、polyline、line、bezierCurve 等
  • dataset :数据集组件,用于单独的数据集声明,从而数据可以单独管理,被多个组件复用,并且可以自由指定数据到视觉的映射
  • aria :无障碍访问组件,使图表内容能够被更多残障人士访问
  • blendMode :图形的混合模式,默认为 ‘source-over’。 支持每个系列单独设置
  • hoverLayerThreshold :图形数量阈值,决定是否开启单独的 hover 层,在整个图表的图形数量大于该阈值时开启单独的 hover 层
  • useUTC :是否使用 UTC 时间,默认取值为 false,即使用本地时间

注意:上述配置对象内大都包含更多详细配置,具体配置内容参考官网 >>> ECharts setOption

 

如上图所示,echarts 其实就是通过用户配置各个组件,传入对应的参数,然后通过 ZRender 渲染组合成我们需要的图表。

echarts 原型的属性/方法

  • init :创建一个 ECharts 实例,返回 echartsInstance,不能在单个容器上初始化多个 ECharts 实例
    const chart = echarts.init(dom, theme, options);
    
    • dom :实例容器,一般是一个具有高宽的div元素
    • theme :应用的主题。可以是一个配置对象,也可以是通过 echarts.registerTheme 注册的主题名称
    • options :附加参数。可以是:devicePixelRatio、renderer、useDirtyRect、width、height、locale
  • connect :多个图表实例实现联动
    echarts.connect(group)
    
    • group :可以是一个 groupId ,也可以是对应的实例数组
  • disconnect :解除图表实例的联动
    echarts.disconnect(group)
    
    • group :需要解除实例联动的 groupId
  • dispose :销毁实例,实例销毁后无法再被使用
    echarts.dispose(target)
    
    • target :需要销毁的实例,可以是 ECharts 实例、DOM 对象或者 Canvas 元素
  • getInstanceByDom :获取 dom 容器上的实例
    echarts.getInstanceByDom(target)
    
    • target :需要销毁的实例,可以是 DOM 对象或者 Canvas 元素
  • use :使用组件,配合新的按需引入的接口使用,该方法必须在echarts.init之前使用
    // 引入 echarts 核心模块,核心模块提供了 echarts 使用必须要的接口。
    import * as echarts from 'echarts/core';
    // 引入柱状图图表,图表后缀都为 Chart
    import { BarChart } from 'echarts/charts';
    // 引入提示框,标题,直角坐标系组件,组件后缀都为 Component
    import { TitleComponent, GridComponent } from 'echarts/components';
    // 引入 Canvas 渲染器,注意引入 CanvasRenderer 或者 SVGRenderer 是必须的一步
    import { CanvasRenderer } from 'echarts/renderers';
    // 注册必须的组件
    echarts.use( [TitleComponent, GridComponent, BarChart, CanvasRenderer] );
    
  • registerMap :注册可用的地图,必须在包括 geo 组件或者 map 图表类型的时候才能使用
    echarts.registerMap(mapName, geoJson, specialAreas)
    
    • mapName :地图名称,在 geo 组件或者 map 图表类型中设置的 map 对应的就是该值
    • geoJson :GeoJson 格式的数据
    • specialAreas :将地图中的部分区域缩放到合适的位置,可以使得整个地图的显示更加好看
  • getMap :获取已注册的地图
    echarts.getMap(mapName)
    
    • mapName :地图名称,在 geo 组件或者 map 图表类型中设置的 map 对应的就是该值
  • registerTheme :注册主题,用于初始化实例的时候指定
    echarts.registerTheme(themeName, theme)
    
    • themeName :主题的名称
    • theme :主题对象
  • registerLocale :注册语言包,用于初始化实例的时候指定
    echarts. registerLocale(locale, localeCfg)
    
    • locale :要注册的语言包
    • localeCfg :挂载语言包对象
  • graphic :图形相关方法
    • extendShape :创建一个新的图形类
      echarts.graphic. extendShape(opts)
      
      • opts :对应 zrender.graphic.Path 的配置项
    • registerShape :注册一个开发者定义的图形类
      echarts.graphic. registerShape(name, ShapeClass)
      
      • name :要注册的图形类名
      • ShapeClass :由 echarts.graphic.extendShape 生成的图形类
    • getShapeClass :得到一个注册好的图形类
      echarts.graphic. getShapeClass(name)
      
      • name :要获取的图形类名
    • clipPointsByRect :输入一组点,和一个矩形,返回被矩形截取过的点
      echarts.graphic. clipPointsByRect(points, rect)
      
      • points :要被截取的点列表
      • rect :用于截取点的矩形
    • clipRectByRect :输入两个矩形,返回第二个矩形截取第一个矩形的结果
      echarts.graphic. clipPointsByRect(targetRect, rect)
      
      • targetRect :要被截取的矩形
      • rect :用于截取点的矩形

echartsInstance 实例的属性/方法

  • group :图表的分组,用于联动
    echartsInstance.group = 'groupId';
    
  • setOption :设置图表实例的配置项以及数据
    echartsInstance.setOption(option, opts)
    
    • option :图表的配置项和数据
    • opts :其他的一些配置项
      • notMerge :boolean,可选。是否不跟之前设置的 option 进行合并。默认为 false
      • replaceMerge :string | string[],可选。可选。用户可以在这里指定一个或多个组件
      • lazyUpdate :boolean,可选。在设置完 option 后是否不立即更新图表,默认为 false
      • silent :boolean,可选。阻止调用 setOption 时抛出事件,默认为 false
      • transition :可选。指定如何进行“合并”/“分裂”过渡动画
  • getWidth :获取 ECharts 实例容器的宽度
    echartsInstance.getWidth()
    
  • getHeight :获取 ECharts 实例容器的高度
    echartsInstance.getHeight()
    
  • getDom :获取 ECharts 实例容器的 dom 节点
    echartsInstance.getDom()
    
  • getOption :获取当前实例中维护的 option 对象
    echartsInstance.getOption()
    
  • resize :
    echartsInstance.resize(opts)
    
    • opts :相关配置
    • width :可显式指定实例宽度,单位:px
    • height :可显式指定实例高度,单位:px
    • silent :是否禁止抛出事件。默认为 false
    • animation : resize 的时候是否应用过渡动画,包含时长duration和缓动easing两个配置
  • dispatchAction :触发图表行为
    echartsInstance.dispatchAction(payload)
    
    • payload :要触发的图表行为
  • on :绑定事件处理函数
    echartsInstance.on(eventName, query, handler, context)
    
    • eventName :事件名称,如:click、mousemove、legendselected
    • query :可选的过滤条件,能够只在指定的组件或者元素上进行响应
    • handler :事件处理函数
    • context :可选。回调函数内部的 context,即 this 的指向
  • off :解绑事件处理函数
    echartsInstance.off(eventName, handler)
    
    • eventName :事件名称,如:click、mousemove、legendselected
    • handler :可选,可以传入需要解绑的处理函数,不传的话解绑所有该类型的事件函数
  • covertToPixel :转换坐标系上的点到像素坐标值
    echartsInstance.covertToPixel(finder, value)
    
    • finder :用于指示使用哪个坐标系进行转换
    • value :要被转换的值
  • convertFromPixel :转换像素坐标值到逻辑坐标系上的点。是 convertToPixel 的逆运算
    echartsInstance.convertFromPixel(finder, value)
    
    • finder :用于指示在哪个坐标系或者系列上判断
    • value :要被转换的值,为像素坐标值
  • containPixel :判断给定的点是否在指定的坐标系或者系列上
    echartsInstance.containPixel(finder, value)
    
    • finder :用于指示在哪个坐标系或者系列上判断
    • value :要被判断的点,为像素坐标值
  • showLoading :显示加载动画效果。可以在加载数据前手动调用该接口显示加载动画,在数据加载完成后调用 hideLoading 隐藏加载动画
    echartsInstance.showLoading(type, opts)
    
    • type :可选,加载动画类型,目前只有一种’default’
    • opts :可选,加载动画配置项,跟type有关
  • hideLoading :隐藏动画加载效果
    echartsInstance.hideLoading()
    
  • getDataURL :导出图表图片,返回一个 base64 的 URL,可以设置为 Image 的 src
    echartsInstance.getDataURL(opts)
    
    • opts :导出图片的配置对象
  • getConnectedDataURL :导出联动的图表图片,返回一个 base64 的 url,可以设置为Image的src
    echartsInstance.getConnectedDataURL(opts)
    
    • opts :导出联动图片的配置对象
  • appendData :此接口用于,在大数据量(百万以上)的渲染场景,分片加载数据和增量渲染
    echartsInstance.appendData(opts)
    
    • opts :要增加数据的配置对象
  • clear :清空当前实例,会移除实例中所有的组件和图表
    echartsInstance.clear()
    
  • isDisposed :当前实例是否已经被释放
    echartsInstance.isDisposed()
    
  • dispose :销毁实例,销毁后实例无法再被使用
    echartsInstance.dispose()
    

ECharts 行为 Action

ECharts 中支持的图表行为,通过 dispatchAction 触发。可用的行为包括:

  • highlight :高亮指定的数据图形
  • downplay :取消高亮指定的数据图形
  • select :选中指定的数据。选中数据会使用 select 配置的样式
  • unselect :取消选中指定的数据
  • toggleSelected :切换选中状态
  • legend :图例组件相关的行为,必须引入图例组件后才能使用
    • legendSelect :选中图例
    • legendUnSelect :取消选中图例
    • legendToggleSelect :切换图例的选中状态
    • legendAllSelect :将图例全选
    • legendInverseSelect :将图例反选
    • legendScroll :控制图例的滚动。当 legend.type 为 ‘scroll’ 时有效
  • tooltip :提示框组件相关的行为,必须引入提示框组件后才能使用
    • showTip :显示提示框
    • hideTip :隐藏提示框
  • dataZoom :数据区域缩放组件相关的行为,必须引入数据区域缩放组件后才能使用
    • dataZoom :数据区域缩放
    • takeGlobalCursor :启动或关闭 toolbox 中 dataZoom 的刷选状态
  • visualMap :视觉映射组件相关的行为,必须引入视觉映射组件后才能使用
    • selectDataRange :选取映射的数值范围
  • timeline :时间轴组件相关的行为,必须引入时间轴组件后才能使用
    • timelineChange :设置当前的时间点
    • timelinePlayChange :切换时间轴的播放状态
  • toolbox :工具栏组件相关的行为,必须引入工具栏组件后才能使用
    • restore :重置 option
  • geo :地图组件相关的行为,必须引入地图组件后才能使用
    • geoSelect :选中指定的地图区域
    • geoUnSelect :取消选中指定的地图区域
    • geoToggleSelect :切换指定的地图区域选中状态
  • brush :区域选择相关的行为
    • brush :“刷选”动作进行中时,会触发此 action。 此 action 能设置或删除 chart 中的选框
    • brushEnd :“刷选” 动作完毕时,会自动触发此 action。 其参数和 brush action 完全相同
    • takeGlobalCursor :刷选模式的开关。使用此 action 可将当前鼠标变为可刷选状态

ECharts 事件 Events

ECharts 中的事件分为两种,一种是鼠标事件,在鼠标点击某个图形上会触发,还有一种是 调用 dispatchAction 后触发的事件。

  • 鼠标事件 :鼠标事件的事件参数是事件对象的数据的各个属性
    • click :鼠标点击
    • dblclick :鼠标双击
    • mousedown :鼠标按下
    • mousemove :鼠标移动
    • mouseup :鼠标弹起
    • mouseover :鼠标滑过
    • mouseout :鼠标滑出
    • globalout :鼠标滑出实例
    • contextmenu :鼠标右键触发并打开上下文菜单
  • highlight :高亮事件
  • downplay :取消高亮事件
  • selectchanged :在数据选中状态发生变化时触发的事件
  • legendselectchanged :legendToggleSelect 切换图例选中状态后的事件
  • legendselected :legendSelect 图例选中后的事件
  • legendselectall :legendAllSelect 图例全选后的事件
  • legendinverseselect :legendInverseSelect 图例反选后的事件
  • legendscroll :legendscroll 图例滚动事件
  • datazoom :数据区域缩放后的事件
  • datarangeselected :selectDataRange 视觉映射组件中,range 值改变后触发的事件
  • timelinechanged :timelineChange 时间轴中的时间点改变后的事件
  • timelineplaychanged :timelinePlayChange 时间轴中播放状态的切换事件
  • restore :restore 重置 option 事件
  • dataviewchanged :工具栏中数据视图的修改事件
  • magictypechanged :工具栏中动态类型切换的切换事件
  • geoselectchanged :geo 中地图区域切换选中状态的事件
  • geoselected :geo 中地图区域选中后的事件
  • geounselected :geo 中地图区域取消选中后的事件
  • axisareaselected :平行坐标轴 (Parallel) 范围选取事件
  • brush :选框正在添加事件。即发出 brush action 得到的事件
  • brushEnd :选框添加完毕事件。即发出 brushEnd action 得到的事件
  • brushselected :对外通知当前选中了什么。在 setOption 时不会发出,在其他的 dispatchAction 时,或者用户在界面中创建、删除、修改选框时会发出
  • globalcursortaken :对应 takeGlobalCursor 的事件
  • rendered :渲染结束后触发的事件
  • finished :渲染完成后触发的事件

除了鼠标事件外,其他事件基本是对照图表行为触发的(通过 dispatchAction 控制触发什么动作),可参照图表行为理解。