G6 图实例生命周期管理:Graph.destroy() 深度解析与实战指南
G6 图实例生命周期管理:Graph.destroy() 深度解析与实战指南
导读
graph.destroy() 是 G6(JavaScript 图可视化框架)中负责销毁图实例、释放全部资源的核心生命周期方法。本指南以官方 API 文档 packages/site/docs/api/graph.zh.md 为骨架,深入源码剖析其内部销毁顺序、事件钩子与底层清理机制,并给出 SPA 页面切换、热更新等真实场景下的最佳实践。读完本文,你将掌握如何安全地销毁图实例、如何监听销毁生命周期事件,以及如何避免"销毁后再操作"这一最常见的资源泄漏与报错陷阱。
一、API 速览:签名、语义与使用场景
1.1 方法签名
Graph.destroy() 是 Graph 类公开的实例方法,签名如下:
destroy(): void;
- 返回值:
void,销毁过程是同步的,调用结束后实例即不可用。 - 所属类别:在源码注释中标为
@apiCategory instance(实例生命周期类 API),见 packages/g6/src/runtime/graph.ts。 - 官方文档原文:图实例 API 文档 中将其列为
Graph.destroy()章节,并明确指出:"销毁当前图实例,释放与图实例相关的所有资源"。
1.2 语义要点
官方文档强调两个关键约束:
- 销毁后不可再进行任何操作——一旦调用
destroy(),该实例上的render()、setData()、addData()等所有 API 均不再可用; - 如需重新使用,必须重新创建图实例——G6 不提供"复活"机制,正确做法是
new Graph(...)一个新实例。
1.3 官方建议的使用场景
- 关闭图表/切换视图时:用户关闭图表面板或从图页面切换到其他页面时,调用
destroy()释放画布、事件监听等资源,避免后台残留无效渲染与监听器; - 重新创建图实例前:在需要重建图时,先销毁旧实例,防止多个实例叠加造成内存泄漏与事件重复绑定。
二、源码级原理:destroy() 到底销毁了什么
2.1 入口实现
destroy() 的完整实现在 packages/g6/src/runtime/graph.ts:
public destroy(): void {
emit(this, new GraphLifeCycleEvent(GraphEvent.BEFORE_DESTROY));
const { layout, animation, element, model, canvas, behavior, plugin } = this.context;
plugin?.destroy();
behavior?.destroy();
layout?.destroy();
animation?.destroy();
element?.destroy();
model.destroy();
canvas?.destroy();
this.options = {};
// @ts-expect-error force delete
this.context = {};
this.off();
globalThis.removeEventListener?.('resize', this.onResize);
this.destroyed = true;
emit(this, new GraphLifeCycleEvent(GraphEvent.AFTER_DESTROY));
}
从实现可以看出,一次 destroy() 调用会按固定顺序清理七大运行时模块:
| 清理顺序 | 模块 | 销毁内容 |
|---|---|---|
| 1 | plugin |
所有插件(Tooltip、Minimap、Contextmenu、History 等) |
| 2 | behavior |
所有交互行为及其绑定的键盘/鼠标事件 |
| 3 | layout |
布局引擎(含力导等迭代动画的停止) |
| 4 | animation |
动画执行器与未完成的动画任务 |
| 5 | element |
画布上的全部元素(节点、边、Combo 及容器) |
| 6 | model |
数据模型中的全部节点与边数据 |
| 7 | canvas |
画布实例、图层、相机与 landmark 动画 |
随后清空 options 与 context、解除全部事件监听、移除全局 resize 监听,最后将 destroyed 标志置为 true。
2.2 各模块销毁的实现细节
- 动画模块(packages/g6/src/runtime/animation.ts):先调用
this.stop()停止所有进行中的动画,再清空动画集合与任务队列,防止动画回调在销毁后继续访问已释放的上下文。 - 画布模块(packages/g6/src/runtime/canvas.ts):遍历所有图层,先
camera.cancelLandmarkAnimation()取消相机 landmark 动画,再销毁每个图层画布,避免相机动画在销毁后仍触发渲染。 - 数据模块(packages/g6/src/runtime/data.ts):从 model 中取出全部节点与边,依次
removeEdges/removeNodes彻底移除数据,随后清空运行时上下文。 - 元素模块(packages/g6/src/runtime/element.ts):先
clear()清空元素,再销毁元素容器(container),从渲染树上真正移除。 - 行为模块(packages/g6/src/runtime/behavior.ts):从画布容器上移除
keydown/keyup等键盘监听,防止行为在实例销毁后仍然响应全局事件。
2.3 销毁后的"安全阀"机制
destroy() 的最后一步将 destroyed 置为 true(packages/g6/src/runtime/graph.ts)。该标志在渲染入口 prepare() 中被检查(packages/g6/src/runtime/graph.ts):
private async prepare(): Promise<void> {
// 等待同步任务执行完成,避免 render 后立即调用 destroy 导致的问题
await Promise.resolve();
if (this.destroyed) {
// 如果图实例已经被销毁,则不再执行任何操作
console.error(format('The graph instance has been destroyed'));
return;
}
...
}
也就是说,即使因异步时序问题在 render() 之后立刻调用了 destroy(),后续的绘制任务也会被 destroyed 检查拦下并打印错误提示,而不会继续操作已释放的上下文——这是框架层面的一个防御性保护。
三、生命周期事件:在销毁前后执行自定义逻辑
3.1 事件常量
destroy() 在开始和结束时会各派发一次图生命周期事件,常量定义在 packages/g6/src/constants/events/graph.ts:
BEFORE_DESTROY = 'beforedestroy', // 销毁开始之前
AFTER_DESTROY = 'afterdestroy', // 销毁结束之后
事件对象为 GraphLifeCycleEvent,其构造函数明确接受 GraphEvent.BEFORE_DESTROY 与 GraphEvent.AFTER_DESTROY 作为合法事件类型(见 packages/g6/src/utils/event/events.ts),并继承自统一的 BaseEvent。
3.2 监听销毁事件
import { Graph, GraphEvent } from '@antv/g6';
const graph = new Graph({ container: 'container', data: {...} });
graph.on(GraphEvent.BEFORE_DESTROY, () => {
console.log('图实例即将销毁,可在此执行最后的资源回收(如断开 WebSocket、保存状态)');
});
graph.on(GraphEvent.AFTER_DESTROY, () => {
console.log('图实例已销毁,可在此清理外层引用、通知页面刷新视图');
});
graph.destroy();
典型用法:在 BEFORE_DESTROY 中把图当前视口(getViewport())、元素状态等持久化到本地或服务端,供下次重建实例时恢复;在 AFTER_DESTROY 中解除业务层对 graph 的引用,帮助 GC 回收。
四、实战:单页应用中的销毁与重建
4.1 标准销毁流程
在 Vue / React 等单页应用中,页面卸载时是调用 destroy() 的最佳时机。以组件卸载场景为例:
class GraphPage {
private graph: Graph | null = null;
mount() {
this.graph = new Graph({
container: document.getElementById('graph-container')!,
data: { nodes: [...], edges: [...] },
behaviors: ['drag-canvas', 'zoom-canvas'],
plugins: ['tooltip', 'minimap'],
});
this.graph.render();
}
unmount() {
// 关闭图表/切换视图时释放资源
this.graph?.destroy();
this.graph = null; // 释放外层引用,便于垃圾回收
}
remount() {
// 重新使用时创建新实例
this.mount();
}
}
4.2 销毁后不可操作的验证
仓库测试用例 packages/g6/tests/bugs/continuous-invoke.spec.ts 验证了这一行为:
it('continuous invoke', () => {
const graph = createGraph({});
const fn = jest.fn(async () => {
graph.destroy();
await graph.render();
});
expect(fn).rejects.toThrow();
});
该测试证明:销毁后立即调用 render() 会抛出异常(异步操作被拒绝)。因此在业务代码中,不要在 destroy() 之后链式调用任何 API,所有后续操作都应基于新创建的实例。
4.3 与 clear() 的区分
destroy() 与 clear() 容易混淆,二者的区别在于:
| 方法 | 行为 | 实例是否可复用 |
|---|---|---|
graph.clear() |
仅清空画布元素与数据,保留实例与配置 | ✅ 可继续 setData / render |
graph.destroy() |
销毁实例全部资源,实例不可再用 | ❌ 必须 new Graph 重建 |
clear() 的实现见 packages/g6/src/runtime/graph.ts:只做 model.setData({})、model.clearChanges() 与 element.clear(),不触碰插件、行为与画布本身。
五、常见问题与最佳实践清单
5.1 常见误区
- 销毁后继续调用 API:会触发
The graph instance has been destroyed错误(由prepare()中的destroyed检查抛出),且行为不可预测; - 重复创建实例而不销毁旧实例:多个实例叠加会同时注册
resize监听、重复渲染,造成内存与性能浪费; - 在异步回调中延迟销毁:渲染、布局、动画均为异步流程,若在回调中销毁,需确保流程已结束或依赖
destroyed标志的防御逻辑; - 忘记移除外层引用:即使调用
destroy(),业务层仍持有 graph 引用时,实例无法被垃圾回收。
5.2 最佳实践
- 组件
unmount/ 页面卸载钩子中调用destroy(),并将引用置空; - 通过
BEFORE_DESTROY/AFTER_DESTROY事件完成状态持久化与外部资源清理; - 需要"重新加载"图时,遵循"销毁旧实例 → 创建新实例"的固定流程,而不是尝试复用已销毁对象;
- 如需频繁清空重绘(如数据刷新),优先使用
clear()+setData(),避免不必要的实例重建开销; - 大型图(成千上万元素)销毁后,可在
AFTER_DESTROY回调中主动释放外部引用,加速内存回收。
六、关联资源导航
- API 文档:图实例 Graph.destroy()
- 核心实现:packages/g6/src/runtime/graph.ts
- 生命周期事件常量:packages/g6/src/constants/events/graph.ts
- 事件对象定义:packages/g6/src/utils/event/events.ts
- 销毁后调用验证用例:packages/g6/tests/bugs/continuous-invoke.spec.ts
- 各运行时模块销毁实现:runtime/animation.ts、runtime/canvas.ts、runtime/data.ts、runtime/element.ts、runtime/behavior.ts