1. 目标
从 echarts 源码入手了解如何添加定制的图表组件。
2. echarts 图表的使用方法
2.1 基本运行环境
- 使用 vite 的 vanilla-ts 模板，通过
npm create vite@latest命令可以按照步骤安装- 使用 vite 的目的是可以实现修改代码之后的动态刷新
- 使用 vanilla 的目的是可以使用纯粹的 js，并不引入其他的库
- 使用 ts 的目的是可以方便的跳转各个方法，方便查找源码，毕竟 echarts 实际也是使用 ts 编写的。
- 执行
npm install安装对应的包。之后运行npm run dev就可以进入 vite 的例子程序了 - 其中 main.ts 是程序的入口文件，可以在其中增加一些链接，来跳转子页面。之后，就在子页面中调试独立的 echarts 相关内容
<div><a href="/subpages/echarts_init.html"> 初始化 echart 并使用 </a></div>
2.2 echarts 基本图表库使用
2.2.1 使用 ts 按需引入 echarts 相关资源并建立配置文件
- 参考 echarts 官网的使用例子，在项目中引入 Apache ECharts
- 安装 echarts 包
npm install echarts --save - 按需引入相关资源
// 引入 echarts 核心包。用于初始化图表
import * as echarts from 'echarts/core';
// 引入主要的图表类型，以及对应的选项类型
// 系列类型的定义后缀都为 SeriesOption
import {
BarChart, // 柱状图
BarSeriesOption, // 柱状图选项
} from 'echarts/charts';
// 引入图表使用的附加组件
// 组件类型的定义后缀都为 ComponentOption
import {
TitleComponent, // 标题组件
TitleComponentOption, // 标题组件选项
TooltipComponent, // 提示框组件
TooltipComponentOption, // 提示框组件选项
GridComponent, // 网格组件，或者叫做子图组件
GridComponentOption, // 网格组件选项
DatasetComponent, // 数据集组件
DatasetComponentOption, // 数据集组件选项
} from 'echarts/components';
// 引入 canvas 图表渲染
import { CanvasRenderer } from 'echarts/renderers';
// 通过 ComposeOption 来组合出一个只有必须组件和图表的 Option 类型
type ECOption = echarts.ComposeOption<
| BarSeriesOption
| TitleComponentOption
| TooltipComponentOption
| GridComponentOption
| DatasetComponentOption
>;
// 注册必须的组件
echarts.use([
TitleComponent,
TooltipComponent,
GridComponent,
DatasetComponent,
BarChart,
CanvasRenderer
]);
// 建立 echarts 的图表配置
const option: ECOption = {
// 标题组件配置
title: {
text: 'ECharts 入门示例'
},
// 提示框组件配置
tooltip: {},
// x 轴配置
xAxis: {
data: ['衬衫', '羊毛衫', '雪纺衫', '裤子', '高跟鞋', '袜子']
},
// y 轴配置
yAxis: {},
// 数据系列配置
series: [
{
name: '销量',
type: 'bar',
data: [5, 20, 36, 10, 10, 20]
}
]
}
// 初始化图表，设置配置项，完成图表的显示
// 这里将 myChart 显示到 id 为 main 的 DOM 节点之上，参考对应 html 文件
const myChart = echarts.init(document.getElementById('main'));
myChart.setOption(option);
2.2.2 建立 html 显示 echarts 图表
- 建立一个子页面到 /subpages/echarts_init.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Echart init</title>
</head>
<body>
<div id="app">
<div id="main" style="width: 800px; height:600px;"></div>
</div>
<script type="module" src="/src/subpages/echart_init.ts"></script>
</body>
</html>
- 其中使用了 es6 的模块语法引入了我们写的 echart_init.ts 文件
- 其中 id 为 main 的 div 节点，之后会用于显示 myChart 图表，同时还设置了其显示大小。
2.2.3 显示效果
myChart的显示效果
- 鼠标悬浮在每个系列的柱状图上面会显示 toolTip
- 刷新页面会显示动画
3. echarts 图表的渲染逻辑
由于 echarts 的手册主要是说明其每个图表的使用方法，对于底层是如何处理的并没有详细介绍，也没有具体介绍如果需要扩展 echarts 图表应当具体如何去做。
所以，需要首先从 echarts 的渲染逻辑入手，逐步了解 echarts 是如何组织图表上的各个组件元素的布局，如何共享数据，以及如何最终完成渲染。
3.1 查找入口点
- 查看上面最简单的 echarts 示例代码，得知整个图表的渲染通过 echarts.init 函数处理的。所以以这个函数为入手点查看具体的渲染逻辑。
- 在 vscode 编辑器之中，通过右键导航的方式查看 echarts.init 方法。
- 发现定位到了 node_modules\echarts\types\dist\shared.d.ts 这个文件之中。
- shared.d.ts 是 echars 的包公开的全部的类型和方法，我们在使用的时候基本上也是使用其中的类型和方法。上面代码之中的 BarChart、
TitleComponent、BarSeriesOption等图表、组件和选项也都指向到这个文件。曾经尝试直接使用 node_modules\echarts 里面的源代码直接使用，但是发现出现很多类型冲突的问题。因此在定制图表的时候，尽量还是使用官方公开的接口。
3.2 查看 echarts 的源代码
- shared.d.ts 找到了入口函数但是并不包含源代码，还是无法了解业务逻辑，因此需要找到源代码。
- 在 node_modules\echarts\lib 文件夹包含了 echars 的全部 js 文件源代码。是很有参考意义的。但是这部分代码的可读性并不好。因为他们是通过 ts 生成的。很多 ts 的语法糖已经转化为 js 代码。如果对 js 和 ts 的映射关系不熟，是无法了解的。
- 所以还是要看到 ts 源码，这些源码，只有去 github 寻找了。echars源码 可以在 github上进行搜索，这样就可以知道每个具体的函数是在什么地方定义的以及在什么地方使用了。
- 为了方便搜索，可以将源码下载位 zip 文件 echarts-master.zip，解压缩之后并用 vscode 打开进行搜索。由于并不是为了重新生成 echarts 的包，因此不需要安装对应的依赖并运行。
3.3 查看 echarts.init 函数
- 有了源代码，就可以查看 echarts.init 函数是如何具体实现的了。
- 找到 echarts-master\src\echarts.ts 这个文件。其中定义了 init 方法。
export * from './export/core';
import { use } from './extension';
import { init } from './core/echarts';
import {install as CanvasRenderer} from './renderer/installCanvasRenderer';
import {install as DatasetComponent} from './component/dataset/install';
// Default to have canvas renderer and dataset for compitatble reason.
use([CanvasRenderer, DatasetComponent]);
// TODO: Compatitable with the following code
// import echarts from 'echarts/lib/echarts'
export default {
init() {
if (__DEV__) {
/* eslint-disable-next-line */
console.error(`"import echarts from 'echarts/lib/echarts'" is not supported anymore. Use "import * as echarts from 'echarts/lib/echarts'" instead;`);
}
// @ts-ignore
return init.apply(null, arguments);
}
};
// Import label layout by default.
// TODO remove
import {installLabelLayout} from './label/installLabelLayout';
use(installLabelLayout);
- 源代码之中包含了不少附加的方法调用，比如为了兼容性和设定默认值，使用use方法加载了CanvasRenderer, DatasetComponent、installLabelLayout等。
- 但是核心的还是 export default 之中包含的 init 函数。这个函数没有复杂的函数体，真正的代码是通过
import { init } from './core/echarts';引入的，并把传入的参数通过 argument 传递给引入的 init 函数。 - 因此进入对应的文件查看 echarts-master\src\core\echarts.ts，这个文件就很大了。由于我们关注的是 init 函数，因此。只看这一部分代码
/**
* @param opts.devicePixelRatio Use window.devicePixelRatio by default
* @param opts.renderer Can choose 'canvas' or 'svg' to render the chart.
* @param opts.width Use clientWidth of the input `dom` by default.
* Can be 'auto' (the same as null/undefined)
* @param opts.height Use clientHeight of the input `dom` by default.
* Can be 'auto' (the same as null/undefined)
* @param opts.locale Specify the locale.
* @param opts.useDirtyRect Enable dirty rectangle rendering or not.
*/
export function init(
dom: HTMLElement,
theme?: string | object,
opts?: EChartsInitOpts
): EChartsType {
const isClient = !(opts && opts.ssr);
if (isClient) {
if (__DEV__) {
if (!dom) {
throw new Error('Initialize failed: invalid dom.');
}
}
const existInstance = getInstanceByDom(dom);
if (existInstance) {
if (__DEV__) {
warn('There is a chart instance already initialized on the dom.');
}
return existInstance;
}
if (__DEV__) {
if (isDom(dom)
&& dom.nodeName.toUpperCase() !== 'CANVAS'
&& (
(!dom.clientWidth && (!opts || opts.width == null))
|| (!dom.clientHeight && (!opts || opts.height == null))
)
) {
warn('Can\'t get DOM width or height. Please check '
+ 'dom.clientWidth and dom.clientHeight. They should not be 0.'
+ 'For example, you may need to call this in the callback '
+ 'of window.onload.');
}
}
}
const chart = new ECharts(dom, theme, opts);
chart.id = 'ec_' + idBase++;
instances[chart.id] = chart;
isClient && modelUtil.setAttribute(dom, DOM_ATTRIBUTE_KEY, chart.id);
enableConnect(chart);
lifecycle.trigger('afterinit', chart);
return chart;
}
- 在这个函数之中，首先要查看参数
- dom: HTMLElement 渲染的dom节点
- theme?: string | object, 可选的渲染主题，明亮或者黑暗
- opts?: EChartsInitOpts 图表的配置项，也就是刚才的 ECOption
- 这个函数会返回一个 EChartsType 的对象，这个实际就是一个具体的图表了
- 接下来查看函数体。忽略掉其中的 DEV 相关的调试信息，得到的简化代码，根据代码填写对应的注释
export function init(
dom: HTMLElement,
theme?: string | object,
opts?: EChartsInitOpts
): EChartsType {
// 判定是否是客户端，并不清楚是什么意思。
// 推测是如果选项不存在，就是客户端。通过 getInstanceByDom 获得实例。ssr 为服务端渲染。因此如果是服务端渲染就直接显示图片即可。
// 测试的基本代码包含opts，因此跳过这部分
const isClient = !(opts && opts.ssr);
if (isClient) {
const existInstance = getInstanceByDom(dom);
if (existInstance) {
return existInstance;
}
}
// 此处建立了一个 echarts 对象。并将 dom theme opts 传给了构造函数
const chart = new ECharts(dom, theme, opts);
// 此处设定了图表的id
chart.id = 'ec_' + idBase++;
// 此处将生成的chart添加到instances，估计为了之后可以统一管理
instances[chart.id] = chart;
// 是客户端才进行处理，跳过
isClient && modelUtil.setAttribute(dom, DOM_ATTRIBUTE_KEY, chart.id);
// 并不清楚这部分功能，暂时跳过
enableConnect(chart);
// 触发生存期的事件，初始化完成
lifecycle.trigger('afterinit', chart);
// 返回对应的chart
return chart;
}
- 通过查看，发现真正的初始化函数还是在 ECharts 对象的构造函数之中。这类也是在 echarts-master\src\core\echarts.ts 这个文件中定义的。这个类也很大。包含的属性和函数也很多。首先查看一下构造函数 constructor，参考其中的注释，尽量补全其中的逻辑。同样删除 DEV相关的调试信息
class ECharts extends Eventful<ECEventDefinition> {
constructor(
dom: HTMLElement,
theme?: string | ThemeOption,
opts?: EChartsInitOpts
) {
// 调用父类构造函数，处理事件功能
super(new ECEventProcessor());
// 确保配置选项不为undefined
opts = opts || {};
// Get theme by name 获取主题名字，跳过
if (isString(theme)) {
theme = themeStorage[theme] as object;
}
// 设置dom节点
this._dom = dom;
// 设置默认的渲染器
let defaultRenderer = 'canvas';
// 设置默认的粗指针，不理解？跳过
let defaultCoarsePointer: 'auto' | boolean = 'auto';
// 设置默认不使用脏矩形，似乎与渲染有关
let defaultUseDirtyRect = false;
// 初始化zrender，zrender 是 echarts 使用的底层渲染库。
// 封装了canvas和svg的绘制接口。
// 其中的参数都是与具体的渲染相关的，包括尺寸，分辨率。
const zr = this._zr = zrender.init(dom, {
renderer: opts.renderer || defaultRenderer,
devicePixelRatio: opts.devicePixelRatio,
width: opts.width,
height: opts.height,
ssr: opts.ssr,
useDirtyRect: retrieve2(opts.useDirtyRect, defaultUseDirtyRect),
useCoarsePointer: retrieve2(opts.useCoarsePointer, defaultCoarsePointer),
pointerSize: opts.pointerSize
});
// 记录是否是服务端渲染，跳过
this._ssr = opts.ssr;
// Expect 60 fps. 设定刷新频率。使用了节流器，1000ms/60 = 16.666 ms
this._throttledZrFlush = throttle(bind(zr.flush, zr), 17);
// 设置主题，跳过
theme = clone(theme);
theme && backwardCompat(theme as ECUnitOption, true);
this._theme = theme;
// 设置本地化，跳过
this._locale = createLocaleObject(opts.locale || SYSTEM_LANG);
// 设置坐标系统管理器，好像很重要，与绘制相关
this._coordSysMgr = new CoordinateSystemManager();
// 设置 api，重要，之后需要通过 api 获取很多信息
const api = this._api = createExtensionAPI(this);
// Sort on demand 设置按需排序，跳过
function prioritySortFunc(a: StageHandlerInternal, b: StageHandlerInternal): number {
return a.__prio - b.__prio;
}
timsort(visualFuncs, prioritySortFunc);
timsort(dataProcessorFuncs, prioritySortFunc);
// 设置调度器，不明白，跳过
this._scheduler = new Scheduler(this, api, dataProcessorFuncs, visualFuncs);
// 设置消息中心
this._messageCenter = new MessageCenter();
// Init mouse events 初始化鼠标事件，
// 比较重要，自定义的时候用户交互需要用到
this._initEvents();
// In case some people write `window.onresize = chart.resize`
// 处理一些异常
this.resize = bind(this.resize, this);
// 响应 zrender 的单帧动画
zr.animation.on('frame', this._onframe, this);
// 绑定 zrender 渲染事件
bindRenderedEvent(zr, this);
// 绑定 zrender 鼠标事件
bindMouseEvent(zr, this);
// ECharts instance can be used as value.
// 将 ECharts 实例设置为可以为 value
// 主要是 zrender 使用的
setAsPrimitive(this);
}
}
- 从上面的构造函数可以知道，ECharts 实例主要是完成了一些基础资源的绑定。其中包括：zrender，坐标系统管理器，事件绑定等。
- 真正包含渲染数据的 opts 并没有在构造函数里面使用。因此一定有其他的地方使用了 opts 从而完成了渲染。
3.4 查找渲染入口
- 重新查看了示例代码，发现在初始化 myChart 之后，真正绘制图表是使用的
myChart.setOption(option);这个语句。 - 因此需要再次查看 ECharts 实例的 setOption 方法。这个方法在官网有更加详细的说明
- 其中主要涉及了如何将 option 进行合并。
- 为了确认是否是通过 setOption这个函数触发图表的渲染。使用了 chrome 浏览器的调试功能。
- 在控制台的 Source 页，查找 BarView.js 文件。
- 这个文件实际是在网站的 http://localhost:5173/node_modules/echarts/lib/chart/bar/BarView.js 位置，也就是lib 的文件夹之中。
- 其中 BarView.prototype.render 就是渲染柱状图的函数。
- 在这个渲染函数上增加断点，之后刷新示例的页面，就会进入断点。
-
进一步的在 Source 页的右侧 call stack 之中可以查看到调用堆栈。
image.png - 在调用堆栈中可以看到，确实是在 setOption 之中通过 update 方法，进而调用了 render 方法
- 这些方法都是在 /src/core/echart.ts 之中
- 下面就可以查看 setOption 函数的主要功能
