AntV | 蚂蚁数据可视化 G2Plot 通用 API

饶骁

2023-12-01

1、通用 API

G2Plot 的核心技术架构非常简单，所有的 Plot 图表都继承于一个基类，基类为所有的图表提供的了通用的 API 方法，而每个具体的可视化图表仅仅处理自己不同的配置项。所以 API 部分，所有图表基本都是一样，除了部分图表（比如：仪表盘、水波图）在 changeData API 上有细微的区别。

<1> 创建图表实例(new)

通用 API
所有图表的创建，都是一样的，从 G2Plot 中引入对应的 Plot class，然后创建实例，构造函数有两个参数：

【1】npm 引入

import { Line } from '@antv/g2plot';

const line = new Line(‘container', options);

// 1. `container`： 图表渲染的 DOM 容器 id 或者 HTMLElement 实例
// 2. `options`： 图表配置数据，不同的图表功能请参考[基础图表 API]

创建好的图表实例，都具有两个公开属性：

container HTMLElement: 图表渲染的 DOM 容器。
options PlotOptions: 图表当前的所有全量配置项 options，是有用户传入，以及图表内置的默认配置项合并之后结果。

const line = new Line('container', {
  data,
  /*...*/
});

对于 API，分别罗列图表实例的所有 API 方法。如果按照功能分类，主要可以分成为：生命周期函数、事件、状态量 等 API

【2】浏览器引入

const {Line } = G2Plot 

const line = new Line(’container', options);

<2> 图表渲染(render)

plot.render();

通过图表构造方法创建实例之后，调用这个方法，可以将图表渲染到指定的 DOM 容器中。

<3> 更新图表配置(update)

plot.update(options: Partial<PlotOptions>);

通过这个方法，可以增量的更新图表配置，方法会自动将传入的增量配置合并到当前的配置项中，并自动调用 render 方法，无需手动调用。

<4> 修改图表的数据(changeData)

plot.changeData(data: object[] | number);

通过这个方法，可以修改图表的数据，并自动重新渲染

<5> 手动指定图表的大小(changeSize)

plot.changeSize(width: number, height: number);

通过这个方法，手动指定图表的大小。当前如果图表配置 autoFit = true 的时候，图表大小会自动跟随容器的大小，只需要使用 css 约定外层 DOM 容器大小，图表即可自动跟随 resize；如果 autoFit = false，那么可以使用 changeSize 这个方法，自定义图表的宽高大小。

<6> 销毁整个画布(destroy)

plot.destroy();

完全销毁整个画布，回收所有资源，仅仅保留传入的 DOM container 容器。一般在组件销毁的时候调用，图表销毁之后，不可再次使用。

<7> 监听图表事件(once)

plot.once(event: string, callback: Function);

监听一次某一个图表事件，并触发一个回调函数，在触发一次之后，自动解除这个事件的监听。

<8> 解除事件的监听(off)

plot.off(event?: string, callback?: Function);

解除事件的监听，可以针对某一个监听函数去解绑；也可以一次解除所有的事件；当然也可以什么参数都不传，解绑所有事件监听。

<9>.设置元素的当前状态(setState)

plot.setState(state?: 'active' | 'inactive' | 'selected', condition?: Function, status: boolean = true);

状态量是 G2 提供的机制，G2 中设定一个元素具备有三种状态：

‘active’
‘inactive’
‘selected’

通过这个 API 可以根据 condition 条件来过滤元素，并设置这些元素的当前状态。

<11> 获取状态量信息 (getStates)

plot.getStates();

获取当前图表所有的状态量信息。

<12> 批量增加图表标注 (addAnnotations)

plot.addAnnotations(annotations: Annotation[]) => void;

批量为当前图表增加图表标注。通过 id 匹配，如果匹配成功，则更新，匹配不成功则增加。

<13> 批量删除图表标注(removeAnnotations)

plot.removeAnnotations(annotations: { id: string }[]) => void;

批量为当前图表删除图表标注。通过 id 匹配，如果匹配成功，则删除。