G6 插件机制完全指南:从内置插件到自定义扩展

原创2026-09-23 17:52:581,890 阅读
文章标签:数据可视化前端图表库

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 调用会走完如下链路:

  1. 解析(parse):PluginController.setPlugins 调用 setExtensions,后者先通过 parseExtensions 将 string | object | function 三种形式的配置统一规范化为 { type, key } 结构,未指定 key 的自动生成(见 utils/extension.ts);
  2. 差异比对(diff):ExtensionController 基于 key 对旧配置与新配置做 arrayDiff,拆分为 enter / update / exit / keep 四类(见 registry/extension/index.ts);
  3. 创建(create):对新增的插件,通过 getExtension(category, type) 从扩展注册表中取出构造函数并实例化;若类型未注册,会输出告警 The extension ${type} of ${category} is not registered.(见 registry/extension/index.ts);
  4. 更新(update):对 update 与 keep 的插件调用 instance.update(extension) 合并新选项;
  5. 销毁(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 文档。

登录后查看全文
G6