G6 插件机制完全指南:从内置插件到自定义扩展
G6 插件机制完全指南:从内置插件到自定义扩展
导读
插件(Plugin)是 G6 图可视化框架中最灵活的扩展机制,它让开发者可以在不侵入图渲染主流程的前提下,为画布挂载额外的图形组件(如小地图、网格线)、实现交互功能(如提示框、上下文菜单)甚至集成独立的业务逻辑(如撤销重做、远程数据加载)。本文基于 插件总览文档 展开,系统梳理 G6 内置插件的全貌与注册类型、四种常见的插件配置方式(基本配置、参数配置、动态更新、实例方法调用),并结合源码剖析插件的注册、解析与生命周期管理原理。读完本文,你将能熟练地在图实例中组合与编排插件,并掌握编写自定义插件的完整路径。
什么是插件
插件是 G6 中最灵活的扩展机制,用户可以通过插件来扩展 G6 的功能,例如在画布中额外挂载图形组件、实现撤销重做等功能。绝大多数定制需求都可以通过插件来实现,G6 内置了一些常用插件,例如 Tooltip、GridLine、History。
从源码结构看,G6 将插件与行为(behavior)、数据转换(transform)并列归为三类可注册的扩展之一:ExtensionController 的 category 类型为 'plugin' | 'behavior' | 'transform'(见 registry/extension/index.ts)。这意味着插件与行为、转换共用同一套“注册—解析—实例化—更新—销毁”的扩展管理机制,只是职责不同:行为关注交互,转换关注数据,而插件则拥有最大的自由度,可以承载任何附加能力。
内置插件一览
G6 提供了丰富的内置插件,涵盖多种常见功能场景。下表完整列出当前仓库(packages/g6/src/plugins)中可用的内置插件及其注册类型与功能描述:
| 分类 | 插件名称 | 注册类型 | 功能描述 |
|---|---|---|---|
| 视觉样式增强 | 网格线 | grid-line |
在画布上显示网格参考线 |
| 背景 | background |
为画布添加背景图片或颜色 | |
| 水印 | watermark |
为画布添加水印,保护版权 | |
| 轮廓包围 | hull |
为指定节点集合创建轮廓 | |
| 气泡集 | bubble-sets |
创建平滑气泡状的元素集合轮廓 | |
| 对齐线 | snapline |
拖动元素时显示对齐参考线 | |
| 导航与概览 | 缩略图 | minimap |
显示图的缩略预览,支持导航 |
| 全屏 | fullscreen |
支持图表全屏显示和退出 | |
| 时间轴 | timebar |
提供时序数据的筛选和播放控制 | |
| 交互控件 | 工具栏 | toolbar |
提供常用操作按钮集合 |
| 上下文菜单 | contextmenu |
右键点击时显示可选操作菜单 | |
| 提示框 | tooltip |
悬停时显示元素详细信息 | |
| 图例 | legend |
显示图表数据的类别和对应样式说明 | |
| 数据探索 | 鱼眼放大镜 | fisheye |
提供焦点+上下文的探索体验 |
| 边过滤镜 | edge-filter-lens |
在指定区域内筛选显示边 | |
| 边绑定 | edge-bundling |
将相似路径的边捆绑在一起,减少视觉混乱 | |
| 高级功能 | 历史记录 | history |
支持撤销/重做操作 |
| 相机设置 | camera-setting |
配置 3D 场景下的相机参数 |
说明:表中的插件名称均对应源码目录
packages/g6/src/plugins/下的同名实现,其导出与选项类型声明集中在 plugins/index.ts。除上表外,仓库还内置了title插件(画布标题,见 plugins/title),每个插件的详细配置可参考各自的文档页。
配置方式
基本配置
在图实例初始化时,通过 plugins 数组指定需要的插件,数组元素可以直接使用插件的注册类型字符串:
import { Graph } from '@antv/g6';
const graph = new Graph({
// 其他配置...
plugins: ['grid', 'minimap', 'tooltip'],
});
从源码看,plugins 选项的类型定义为 (string | CustomPluginOption | ((this: Graph) => CustomPluginOption))<a href="https://link.gitcode.com/i/88f7f9c13a201bee91193b426bdb13ae" target="_blank">](见 [spec/plugin.ts),即数组元素可以是一个类型名字符串、一个配置对象,甚至是一个返回配置对象的函数(函数内部可通过 this 访问图实例,按需动态生成配置)。
配置插件参数
对于需要自定义参数的插件,可以使用 object 形式配置属性。对象形式必须包含 type 字段,其余字段即为该插件的选项:
const graph = new Graph({
// 其他配置...
plugins: [
'grid',
{
type: 'tooltip',
key: 'my-tooltip', // 为插件指定key,便于后续更新
getContent: (e) => `<div>节点:${e.target.id}</div>`,
},
],
});
key 字段是插件的唯一标识,定义于 CustomPluginOption 接口中(见 spec/plugin.ts),它的作用体现在两个方面:
- 用于标识插件,从而进一步操作此插件,例如
graph.getPluginInstance('key')获取实例、graph.updatePlugin({ key, ... })更新配置; - 若未显式指定
key,扩展解析器会自动生成一个以“分类-类型-序号”为规则的自增 key(如plugin-tooltip-0),见 utils/extension.ts。
动态更新插件
G6 支持在图实例运行期间动态管理插件,满足复杂交互需求。
通过 getPlugins 方法获取当前插件列表:
// 获取插件列表
const plugins = graph.getPlugins();
// console.log(plugins) 👉 ['minimap', 'grid']
可以通过 setPlugins 方法调整插件。该方法接收插件配置数组或一个函数(函数的入参为当前插件配置,返回新的配置):
// 添加新插件
graph.setPlugins((plugins) => [...plugins, 'minimap']);
// 移除插件
graph.setPlugins((plugins) => plugins.filter((p) => p !== 'grid'));
注意:setPlugins 设置的插件会全量替换原有的插件配置(源码注释中明确提示了这一点),因此基于回调函数的写法是新增/移除插件的推荐方式。
可以通过 updatePlugin 方法更新单个插件的配置,它只针对 key 匹配的插件做浅合并更新,其余插件保持不变:
const graph = new Graph({
// 其他配置...
plugins: [
{
type: 'tooltip',
key: 'my-tooltip',
getContent: (e) => `<div>节点:${e.target.id}</div>`,
},
],
});
// 更新单个插件
graph.updatePlugin({
key: 'my-tooltip',
getContent: (e) => `<div>更新的内容:${e.target.id}</div>`,
});
:::warning{title=注意}
使用 updatePlugin 方法时,需要在初始化时为插件指定唯一的 key。
:::
卸载插件
使用 setPlugins 方法同样可以卸载插件,将插件配置列表置为空即可:
// 卸载所有插件
graph.setPlugins([]);
调用插件方法
一些插件提供了可供用户调用的 API 方法。例如 history 插件提供了 undo 和 redo 方法,用户可以通过调用这些方法来实现撤销和重做操作;fullscreen 插件则提供了 request 和 exit 方法用于请求与退出全屏(见 runtime/graph.ts 的源码注释示例)。
要调用这些方法,需要先通过 getPluginInstance 获取到插件实例:
// 配置插件
const graph = new Graph({
plugins: [{ type: 'history', key: 'my-history' }],
});
// 获取插件实例
const history = graph.getPluginInstance('my-history');
// 调用插件方法
history.undo();
history.redo();
:::warning{title=注意}
graph.getPluginInstance 方法接收插件 key 值作为参数,因此如果需要获取插件实例,需要将对应插件配置为 object 的形式,并传入 key 值。
:::
getPluginInstance 的底层实现位于 runtime/plugin.ts:它优先通过 extensionMap 按 key 精确匹配;若未命中会打印一条警告,并降级为按插件 type 模糊查找。以 history 插件为例,其 undo/redo 方法维护了 undoStack 与 redoStack 两个命令栈,并提供 canUndo()/canRedo() 用于判断当前是否可执行操作(见 plugins/history/index.ts)。
插件的注册、解析与生命周期
理解插件的底层机制有助于排查问题和编写高质量的自定义插件。一次 setPlugins 调用会走完如下链路:
- 解析(parse):
PluginController.setPlugins调用setExtensions,后者先通过parseExtensions将string | object | function三种形式的配置统一规范化为{ type, key }结构,未指定 key 的自动生成(见 utils/extension.ts); - 差异比对(diff):
ExtensionController基于 key 对旧配置与新配置做arrayDiff,拆分为enter / update / exit / keep四类(见 registry/extension/index.ts); - 创建(create):对新增的插件,通过
getExtension(category, type)从扩展注册表中取出构造函数并实例化;若类型未注册,会输出告警The extension ${type} of ${category} is not registered.(见 registry/extension/index.ts); - 更新(update):对
update与keep的插件调用instance.update(extension)合并新选项; - 销毁(destroy):对
exit的插件调用instance.destroy()并从extensionMap中移除。
BasePlugin 是所有插件的基类,它继承自 BaseExtension,本身没有额外逻辑(见 plugins/base-plugin.ts)。BaseExtension 为每个插件实例提供 context(运行上下文,含 graph 实例)、options(合并后的选项)、update() 与 destroy() 等基础设施(见 registry/extension/index.ts)。
自定义插件
当内置插件无法满足需求时,你可以:
- 继承和扩展现有插件
- 创建全新的自定义插件
自定义插件需要先注册后使用。详细教程可参考 自定义插件文档,其基本注册与使用方式如下:
import { register, ExtensionCategory } from '@antv/g6';
import { MyCustomPlugin } from './my-custom-plugin';
// 注册自定义插件
register(ExtensionCategory.PLUGIN, 'my-custom-plugin', MyCustomPlugin);
// 使用自定义插件
const graph = new Graph({
plugins: ['my-custom-plugin'],
});
自定义插件只需继承 BasePlugin 并实现构造逻辑。例如下面这个“远程数据加载”插件,在实例化时自动为图注入数据并渲染,此后初始化 Graph 时无需再手动传入数据:
import { BasePlugin } from '@antv/g6';
import type { BasePluginOptions, RuntimeContext } from '@antv/g6';
interface RemoteDataSourceOptions extends BasePluginOptions {}
class RemoteDataSource extends BasePlugin<RemoteDataSourceOptions> {
constructor(context: RuntimeContext, options: RemoteDataSourceOptions) {
super(context, options);
this.loadData();
}
private async loadData() {
// mock remote data
const data = {
nodes: [
{ id: 'node-1', x: 100, y: 100 },
{ id: 'node-2', x: 200, y: 200 },
],
edges: [{ source: 'node-1', target: 'node-2' }],
};
const { graph } = this.context;
graph.setData(data);
await graph.render();
}
}
更复杂的插件还可以监听图生命周期事件。例如“自动判断节点数量开启或关闭动画”的插件,监听 GraphEvent.BEFORE_RENDER 事件,在节点数超过阈值时关闭全局动画:
import type { BasePluginOptions, RuntimeContext } from '@antv/g6';
import { BasePlugin, GraphEvent } from '@antv/g6';
interface AutoSwitchAnimationOptions extends BasePluginOptions {
maxLength: number; // 节点数量达到这个值后关闭全局动画
}
class AutoSwitchAnimation extends BasePlugin<AutoSwitchAnimationOptions> {
static defaultOptions: Partial<AutoSwitchAnimationOptions> = {
maxLength: 1000,
};
constructor(context: RuntimeContext, options: AutoSwitchAnimationOptions) {
super(context, options);
this.bindEvents();
}
private bindEvents() {
const { graph } = this.context;
graph.on(GraphEvent.BEFORE_RENDER, this.switchAnimation);
}
private switchAnimation() {
const { graph } = this.context;
graph.setOptions({
animation: graph.getNodeData().length < this.options.maxLength,
});
}
private unbindEvents() {
const { graph } = this.context;
graph.off(GraphEvent.BEFORE_RENDER, this.switchAnimation);
}
destroy() {
this.unbindEvents();
super.destroy();
}
}
这个示例演示了自定义插件的几个关键实践:
- 通过
static defaultOptions声明默认配置,options中合并了默认值与用户传入值; - 在
destroy()中解绑事件,避免内存泄漏,这也是BaseExtension销毁钩子的正确用法; - 自定义配置项(如
maxLength)可在实例化时通过对象形式传入,与内置插件配置方式完全一致:
const graph = new Graph({
// 其他配置
plugins: [
{
type: 'auto-switch-animation',
maxLength: 500,
},
],
});
小结
插件的价值在于“功能解耦”:将提示框、小地图、历史记录、水印这类横切能力从图渲染主流程中剥离出来,通过统一的 plugins 配置即插即用,也可以在运行时动态增删与更新。借助内置的 20 余个插件(视觉增强、导航概览、交互控件、数据探索、高级功能五大类),再配合 BasePlugin 自定义扩展与 register 注册机制,你几乎可以为任何图可视化场景组合出恰到好处的功能集。更多与插件相关的 API 可参考 插件 API 文档。