echarts文档解读
Posted 叶秋学长
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了echarts文档解读相关的知识，希望对你有一定的参考价值。
前言：今天给大家分享一个前端的开源可视化图标库echarts。
💕点击下方名片，即可领取学长个人微信💕
echarts
全局 echarts 对象，在 script 标签引入 echarts.js 文件后获得，或者在 AMD 环境中通过 require('echarts') 获得。
所有属性
Function
(dom?: htmlDivElement|HTMLCanvasElement, theme?: Object|string, opts?:
devicePixelRatio?: number,
renderer?: string,
useDirtyRect?: boolean, // 从 `5.0.0` 开始支持
useCoarsePointer?: boolean, // 从 `5.4.0` 开始支持
pointerSize?: number, // 从 `5.4.0` 开始支持
ssr?: boolean, // 从 `5.3.0` 开始支持
width?: number|string,
height?: number|string,
locale?: string // 从 `5.0.0` 开始支持
) => ECharts
创建一个 ECharts 实例，返回 echartsInstance，不能在单个容器上初始化多个 ECharts 实例。
参数解释
-
dom实例容器，一般是一个具有高宽的 DIV 元素。只有在设置
opts.ssr开启了服务端渲染后该参数才是可选。也支持直接使用
canvas元素作为容器，这样绘制完图表可以直接将 canvas 作为图片应用到其它地方，例如在 WebGL 中作为贴图，这跟使用 getDataURL 生成图片链接相比可以支持图表的实时刷新。 -
theme应用的主题。可以是一个主题的配置对象，也可以是使用已经通过 echarts.registerTheme 注册的主题名称。参见 ECharts 中的样式简介。
-
opts附加参数。有下面几个可选项：
devicePixelRatio设备像素比，默认取浏览器的值window.devicePixelRatio。renderer渲染模式，支持'canvas'或者'svg'。参见 使用 Canvas 或者 SVG 渲染。ssr是否使用服务端渲染，只有在 SVG 渲染模式有效。开启后不再会每帧自动渲染，必须要调用 renderToSVGString 方法才能得到渲染后 SVG 字符串。useDirtyRect是否开启脏矩形渲染，只有在 Canvas 渲染模式有效，默认为false。参见 ECharts 5 新特性。useCoarsePointer是否扩大可点击元素的响应范围。null表示对移动设备开启；true表示总是开启；false表示总是不开启。参见增加交互响应范围。pointerSize扩大元素响应范围的像素大小，配合opts.useCoarsePointer使用。width可显式指定实例宽度，单位为像素。如果传入值为null/undefined/'auto'，则表示自动取dom（实例容器）的宽度。height可显式指定实例高度，单位为像素。如果传入值为null/undefined/'auto'，则表示自动取dom（实例容器）的高度。-
locale使用的语言，内置'ZH'和'EN'两个语言，也可以使用 echarts.registerLocale 方法注册新的语言包。目前支持的语言见 src/i18n。如果不指定主题，也需在传入
opts前先传入null，如：const chart = echarts.init(dom, null, renderer: 'svg');
注： 如果容器是隐藏的，ECharts 可能会获取不到 DIV 的高宽导致初始化失败，这时候可以明确指定 DIV 的style.width和style.height，或者在div显示后手动调用 resize 调整尺寸。
在使用服务端渲染的模式下，必须通过opts.width和opts.height设置高和宽。
Function
(group:string|Array)
多个图表实例实现联动。
参数：
groupgroup 的 id，或者图表实例的数组。
示例：
// 分别设置每个实例的 group id
chart1.group = 'group1';
chart2.group = 'group1';
echarts.connect('group1');
// 或者可以直接传入需要联动的实例数组
echarts.connect([chart1, chart2]);
Function
(group:string)
解除图表实例的联动，如果只需要移除单个实例，可以将通过将该图表实例 group 设为空。
参数：
-
groupgroup 的 id。
Function
(target: ECharts|HTMLDivElement|HTMLCanvasElement)
销毁实例，实例销毁后无法再被使用。
Function
(target: HTMLDivElement|HTMLCanvasElement) => ECharts
获取 dom 容器上的实例。
Function
从
5.0.1开始支持
使用组件，配合新的按需引入的接口使用。
注意：该方法必须在echarts.init之前使用。
// 引入 echarts 核心模块，核心模块提供了 echarts 使用必须要的接口。
import * as echarts from 'echarts/core';
// 引入柱状图图表，图表后缀都为 Chart
import
BarChart
from 'echarts/charts';
// 引入直角坐标系组件，组件后缀都为 Component
import
GridComponent
from 'echarts/components';
// 引入 Canvas 渲染器，注意引入 CanvasRenderer 或者 SVGRenderer 是必须的一步
import
CanvasRenderer
from 'echarts/renderers';
// 注册必须的组件
echarts.use(
[GridComponent, BarChart, CanvasRenderer]
);
更详细的使用方式见 在项目中引入 Apache ECharts 一文
Function
(
mapName: string,
opt:
geoJSON: Object | string;
specialAreas?: Object;
)
| (
mapName: string,
opt:
svg: Object | string;
)
| (
mapName: string,
geoJSON: Object | string,
specialAreas?: Object
)
注册可用的地图，只在 geo 组件或者 map 图表类型中使用。
使用方法见 option.geo。
参数：
-
mapName -
opt
echarts.registerMap('USA', usaJson,
// 把阿拉斯加移到美国主大陆左下方
Alaska:
// 左上角经度
left: -131,
// 左上角纬度
top: 25,
// 经度横跨的范围
width: 15
,
// 夏威夷
Hawaii:
left: -110,
top: 28,
width: 5
,
// 波多黎各
'Puerto Rico':
left: -76,
top: 26,
width: 2
);
注：如果你在项目中使用了按需引入，从 v5.3.0 开始registerMap必须要在引入地图组件后才能使用。
Function
(mapName: string) => Object
获取已注册的地图，返回的对象类型如下
// 地图的 geoJSON 数据
geoJSON: Object,
// 地图的特殊区域，见 registerMap
specialAreas: Object
注：
geoJSON也可写为geoJson，二者引用的是相同的内容。- 对于
registerMap所注册的 SVG ，暂并不支持从此方法中返回。 - 如果你在项目中使用了按需引入，从 v5.3.0 开始
getMap必须要在引入地图组件后才能使用。
Function
(themeName: string, theme: Object)
注册主题，用于初始化实例的时候指定。
Function
从
5.0.0开始支持
(locale: string, localeCfg: Object)
注册语言包，用于初始化实例的时候指定。语言包格式见 src/i18n/langEN.ts
Function
从
5.3.0开始支持
(platformAPI?:
createCanvas(): HTMLCanvasElement
measureText(text: string, font?: string): width: number
loadImage(
src: string,
onload: () => void,
onerror: () => void
): HTMLImageElement
) => void
设置平台相关的 API，在 NodeJS 等非浏览器平台的时候可能需要提供。
createCanvas创建 Canvas 元素，主要用于测量文本宽度，在没提供measureText的时候需要提供。measureText测量文本宽度，默认会通过createCanvas得到 Canvas 元素提供的接口来测量文本宽度，也可以替换成更轻量的实现。loadImage加载图片，在使用 Canvas 渲染模式的时候并且使用 URL 作为图片的时候需要提供。
any
图形相关帮助方法。
Function
创建一个新的 shape class。
(
opts: Object
) => zrender.graphic.Path
更多的关于参数 opts 的细节，请参阅 zrender.graphic.Path。
echarts.graphic. registerShape
Function
注册一个开发者定义的 shape class。
(
name: string,
ShapeClass: zrender.graphic.Path
)
ShapeClass 须用 echarts.graphic.extendShape 生成。 注册后，这个 class 可以用 echarts.graphic.getShapeClass 方法得到。 registerShape 会覆盖已注册的 class，如果用相同的 name 的话。 注册的 class，可以被用于 自定义系列（custom series） 和 图形组件（graphic component），声明 type: name 即可。
例如：
var MyShape = echarts.graphic.extendShape(
shape:
x: 0,
y: 0,
width: 0,
height: 0
,
buildPath: function (ctx, shape)
ctx.moveTo(shape.x, shape.y);
ctx.lineTo(shape.x + shape.width, shape.y);
ctx.lineTo(shape.x, shape.y + shape.height);
ctx.lineTo(shape.x + shape.width, shape.y + shape.height);
ctx.closePath();
);
echarts.graphic.registerShape('myCustomShape', MyShape);
var option =
series:
type: 'custom',
coordinateSystem: 'none',
renderItem: function (params, api)
return
type: 'myCustomShape',
shape:
x: api.value(0),
y: api.value(1),
width: api.value(2),
height: api.value(3)
,
style:
fill: 'red'
;
,
data: [[10, 20, 30, 40]]
;
echarts.graphic. getShapeClass
Function
得到一个 注册 好的 class。
(
name: String
) => zrender.graphic.Path
这些内置 shape class 会被默认预先注册进去: 'circle', 'sector', 'ring', 'polygon', 'polyline', 'rect', 'line', 'bezierCurve', 'arc'.
echarts.graphic. clipPointsByRect
Function
输入一组点，和一个矩形，返回被矩形截取过的点。
(
// 要被截取的点列表，如 [[23, 44], [12, 15], ...]。
points: Array.<Array.<number>>,
// 用于截取点的矩形。
rect:
x: number,
y: number,
width: number,
height: number
) => Array.<Array.<number>> // 截取结果。
echarts.graphic. clipRectByRect
Function
输入两个矩形，返回第二个矩形截取第一个矩形的结果。
(
// 要被截取的矩形。
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。
echarts.js源码 初始化函数init()解读
1.源代码init()函数
export function init(dom, theme, opts)
if (__DEV__)
// Check version
if ((zrender.version.replace('.', '') - 0) < (dependencies.zrender.replace('.', '') - 0))
throw new Error(
'zrender/src ' + zrender.version
+ ' is too old for ECharts ' + version
+ '. Current version need ZRender '
+ dependencies.zrender + '+'
);
if (!dom)
throw new Error('Initialize failed: invalid dom.');
// 判断该DOM结构是否已经存在绑定的echarts实例
var existInstance = getInstanceByDom(dom);
if (existInstance)
if (__DEV__)
console.warn('There is a chart instance already initialized on the dom.');
return existInstance;
// 需要DOM结构设定特定的width以及height值
if (__DEV__)
if (zrUtil.isDom(dom)
&& dom.nodeName.toUpperCase() !== 'CANVAS'
&& (
(!dom.clientWidth && (!opts || opts.width == null))
|| (!dom.clientHeight && (!opts || opts.height == null))
)
)
console.warn('Can\\'t get dom width or height');
// 新建Echarts实例
var chart = new ECharts(dom, theme, opts);
chart.id = 'ec_' + idBase++;
instances[chart.id] = chart;
modelUtil.setAttribute(dom, DOM_ATTRIBUTE_KEY, chart.id);
enableConnect(chart);
return chart;
2.带有自己学习每行注释的代码
export function init(dom, theme, opts)
if (__DEV__)
/*1.__DEV__ 是开发阶段的产物
2.__DEV__ 在编译阶段，将会根据当前运行环境将其变换成 常量
3.通过 process.env.NODE_ENV 来区分不同模式，应该是 web 前端开发中的一种约定了吧
4.<script> 标签，通过文件名 .js和 .min.js 区分生产环境和开发环境
5.webpack 引入了一个简单的 mode 配置项，用于更快捷的区分环境
6.npm包，在发布之前，一般会经过 __DEV__ 替换成 process.env.NODE_ENV !== 'production' 的操作。（怪不得没搜到）
7.在一些包中，会拆分成两套 js ，一套生产模式，一套开发模式
作者：anddju
链接：https://www.jianshu.com/p/b12a1dedf30e
*/
// Check version 检查zrender的版本
//使用replace()函数将zrender的版本（如2.0）中的“.”换成''然后减去0得到一个数字看是否小于依赖zrender的版本数字
if ((zrender.version.replace('.', '') - 0) < (dependencies.zrender.replace('.', '') - 0))
throw new Error(
//如果小于抛出错误 提示版本太老 需要Echarts依赖的新版本
'zrender/src ' + zrender.version
+ ' is too old for ECharts ' + version
+ '. Current version need ZRender '
+ dependencies.zrender + '+'
);
if (!dom)
//如果传入的dom不是DOM结构的元素则抛出非法DOM结构的错误提示
throw new Error('Initialize failed: invalid dom.');
// 判断该DOM结构是否已经存在绑定的echarts实例
var existInstance = getInstanceByDom(dom);
if (existInstance)
if (__DEV__)
console.warn('There is a chart instance already initialized on the dom.');
return existInstance;
// 需要DOM结构设定特定的width以及height值
if (__DEV__)
//1.先判断传入的对象是否为DOM结构
//2.结构的节点名字是否是CANVAS
//3.最后判断dom节点的宽度和高度是否为0
//如果传入对象既不是DOM结构，或者节点名为CANVAS或者节点的高度和和长度其中一个为0或者全为0则判断结果成立
if (
zrUtil.isDom(dom)
&& dom.nodeName.toUpperCase() !== 'CANVAS'
&& (
(!dom.clientWidth && (!opts || opts.width == null))
|| (!dom.clientHeight && (!opts || opts.height == null))
)
)
//输出提示不能得到节点的宽度和高度
console.warn('Can\\'t get dom width or height');
// 新建Echarts实例
var chart = new ECharts(dom, theme, opts);
chart.id = 'ec_' + idBase++;
instances[chart.id] = chart;
modelUtil.setAttribute(dom, DOM_ATTRIBUTE_KEY, chart.id);
enableConnect(chart);
return chart;
3.真实示例：
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
<script src="echarts.js"></script>
</head>
<body>
<!-- 为 ECharts 准备一个定义了宽高的 DOM -->
<div id="main" style="width: 600px;height:400px;"></div>
</body>
<script type="text/javascript">
// 基于准备好的dom，初始化echarts实例
var myChart = echarts.init(document.getElementById('main'));
// 指定图表的配置项和数据
var option =
title:
text: 'ECharts 入门示例'
,
tooltip: ,
legend:
//图例
data: ['销量']
,
xAxis:
data: ['衬衫', '羊毛衫', '雪纺衫', '裤子', '高跟鞋', '袜子']
,
yAxis: ,
series: [
name: '销量',
type: 'bar',
data: [5, 20, 36, 10, 10, 20]
]
;
// 使用刚指定的配置项和数据显示图表。
myChart.setOption(option);
</script>
</html>
// 基于准备好的dom，初始化echarts实例
var myChart = echarts.init(document.getElementById(‘main’));
这句话就是示例，传入名为main的dom盒子结构，然后进行绘制。
ps：友情学习链接
http://qiuruolin.cn/2019/05/21/echarts-2/
以上是关于echarts文档解读的主要内容，如果未能解决你的问题，请参考以下文章