ECharts—JavaScript开源可视化图标库

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 ：渲染完成后触发的事件