logo

G6

  • 文档
  • API
  • 图表示例
  • 社区
  • 所有产品antv logo arrow
  • 5.0.47
  • 数据
  • 画布操作
  • 元素操作
  • 图实例
  • 绘制与渲染
  • 视口操作
  • 布局
  • 图配置项
  • 插件
  • 交互
  • 主题
  • 数据处理
  • 事件监听
  • 导出图片
  • 坐标转换

事件监听

上一篇
数据处理
下一篇
导出图片

Resources

Ant Design
Galacea Effects
Umi-React 应用开发框架
Dumi-组件/文档研发工具
ahooks-React Hooks 库

社区

体验科技专栏
seeconfSEE Conf-蚂蚁体验科技大会

帮助

GitHub
StackOverflow

more products更多产品

Ant DesignAnt Design-企业级 UI 设计语言
yuque语雀-知识创作与分享工具
EggEgg-企业级 Node 开发框架
kitchenKitchen-Sketch 工具集
GalaceanGalacean-互动图形解决方案
xtech蚂蚁体验科技
© Copyright 2025 Ant Group Co., Ltd..备案号:京ICP备15032932号-38

Loading...

事件系统概述

G6 提供了强大的事件机制,允许你响应图表中发生的各种交互行为。例如节点点击、边悬停、画布拖拽等。通过事件系统,你可以实现复杂的交互逻辑,提升用户体验。

事件分类

G6 中的事件大致可分为以下几类:

  1. 元素事件:与节点、边、Combo 相关的事件,如 node:click, edge:mouseenter
  2. 画布事件:与整个画布相关的事件,如 canvas:drag, canvas:zoom
  3. 生命周期事件:与图表生命周期相关的事件,如 beforerender, afterrender

事件命名规则

G6 的事件命名遵循 [对象]:[事件] 的格式,例如:

  • node:click - 节点点击事件
  • edge:mouseenter - 鼠标进入边的事件
  • canvas:drag - 画布拖拽事件

最佳实践:使用常量枚举

G6 提供了完整的事件常量枚举,强烈建议使用这些常量而非直接使用字符串事件名:

import { NodeEvent, EdgeEvent, CanvasEvent, GraphEvent } from '@antv/g6';
// 使用常量枚举监听事件
graph.on(NodeEvent.CLICK, handleNodeClick);
graph.on(EdgeEvent.POINTER_OVER, handleEdgeHover);
graph.on(CanvasEvent.DRAG, handleCanvasDrag);
graph.on(GraphEvent.AFTER_RENDER, handleAfterRender);

优势:

  • 类型安全,避免字符串拼写错误
  • 提供智能代码提示和自动完成

API 参考

Graph.on(eventName, callback, once)

监听指定的事件,当事件触发时执行回调函数。

on<T extends IEvent = IEvent>(eventName: string, callback: (event: T) => void, once?: boolean): this;

参数

参数描述类型默认值必选
eventName要监听的事件名称string-✓
callback事件触发时执行的回调函数(event: T) => void-✓
once是否只监听一次boolean-

返回值

  • 类型: this(Graph 实例)
  • 描述: 返回图实例本身,支持链式调用

示例

import { NodeEvent, EdgeEvent, CanvasEvent } from '@antv/g6';
// 监听节点点击事件
graph.on(NodeEvent.CLICK, (evt) => {
const { target } = evt; // 获取被点击节点的 ID
console.log(`节点 ${target.id} 被点击了`);
// 获取节点数据
const nodeData = graph.getNodeData(target.id);
console.log('节点数据:', nodeData);
// 修改节点状态
graph.setElementState(target.id, 'selected');
});
// 监听边的鼠标进入事件
graph.on(EdgeEvent.POINTER_OVER, (evt) => {
const { target } = evt;
graph.setElementState(target.id, 'highlight');
});
// 监听画布拖拽事件
graph.on(CanvasEvent.DRAG, (evt) => {
console.log('画布正在被拖拽');
});

Graph.once(eventName, callback)

一次性监听事件,事件触发一次后自动移除监听器。

once<T extends IEvent = IEvent>(eventName: string, callback: (event: T) => void): this;

参数

参数描述类型默认值必选
eventName要监听的事件名称string-✓
callback事件触发时执行的回调函数(event: T) => void-✓

返回值

  • 类型: this(Graph 实例)
  • 描述: 返回图实例本身,支持链式调用

示例

import { GraphEvent, NodeEvent } from '@antv/g6';
// 监听图表首次加载完成事件,仅执行一次
graph.once(GraphEvent.AFTER_RENDER, () => {
console.log('图表首次渲染完成');
// 执行一次性的初始化操作
highlightImportantNodes();
});
// 等待用户第一次点击某个节点后执行操作
graph.once(NodeEvent.CLICK, (evt) => {
console.log('用户首次点击了节点:', evt.target.id);
showTutorialTip('您可以拖拽节点改变位置');
});

Graph.off()

移除全部事件监听器。

off(): this;

返回值

  • 类型: this(Graph 实例)
  • 描述: 返回图实例本身,支持链式调用

示例

// 移除所有事件监听器
graph.off();
console.log('已移除所有事件监听器');

Graph.off(eventName)

移除指定事件类型的所有监听器。

off(eventName: string): this;

参数

参数描述类型默认值必选
eventName要移除的事件名称string-✓

返回值

  • 类型: this(Graph 实例)
  • 描述: 返回图实例本身,支持链式调用

示例

import { NodeEvent } from '@antv/g6';
// 移除所有节点点击事件的监听器
graph.off(NodeEvent.CLICK);
console.log('已移除所有节点点击事件监听器');
// 在某个操作模式结束后,移除相关的临时事件监听
function exitEditMode() {
// 移除编辑模式下的所有监听器
graph.off(NodeEvent.DRAG_END);
graph.off(NodeEvent.DROP);
console.log('已退出编辑模式');
}

Graph.off(eventName, callback)

移除特定事件的特定回调函数。

off(eventName: string, callback: (...args: any[]) => void): this;

参数

参数描述类型默认值必选
eventName要移除的事件名称string-✓
callback要移除的回调函数(...args: any[]) => void-✓

返回值

  • 类型: this(Graph 实例)
  • 描述: 返回图实例本身,支持链式调用

示例

import { NodeEvent } from '@antv/g6';
// 定义回调函数
const handleNodeClick = (evt) => {
console.log('节点被点击:', evt.target.id);
};
// 添加监听器
graph.on(NodeEvent.CLICK, handleNodeClick);
// 之后在某个时机移除这个特定的监听器
graph.off(NodeEvent.CLICK, handleNodeClick);
console.log('已移除特定的节点点击事件监听器');

事件常量枚举

G6 提供了多种事件常量枚举,便于开发者使用规范的事件名称。以下是所有事件常量的详细说明:

节点事件 (NodeEvent)

常量名事件名描述
CLICKnode:click点击节点时触发
DBLCLICKnode:dblclick双击节点时触发
POINTER_OVERnode:pointerover指针移入节点时触发
POINTER_LEAVEnode:pointerleave指针离开节点时触发
POINTER_ENTERnode:pointerenter指针进入节点或其子元素时触发(不冒泡)
POINTER_MOVEnode:pointermove指针在节点上移动时触发
POINTER_OUTnode:pointerout指针离开节点时触发
POINTER_DOWNnode:pointerdown指针在节点上按下时触发
POINTER_UPnode:pointerup指针在节点上抬起时触发
CONTEXT_MENUnode:contextmenu节点上打开上下文菜单时触发
DRAG_STARTnode:dragstart开始拖拽节点时触发
DRAGnode:drag拖拽节点过程中触发
DRAG_ENDnode:dragend拖拽节点结束时触发
DRAG_ENTERnode:dragenter拖拽物进入节点时触发
DRAG_OVERnode:dragover拖拽物在节点上方时触发
DRAG_LEAVEnode:dragleave拖拽物离开节点时触发
DROPnode:drop在节点上放置拖拽物时触发

边事件 (EdgeEvent)

常量名事件名描述
CLICKedge:click点击边时触发
DBLCLICKedge:dblclick双击边时触发
POINTER_OVERedge:pointerover指针移入边时触发
POINTER_LEAVEedge:pointerleave指针离开边时触发
POINTER_ENTERedge:pointerenter指针进入边或其子元素时触发(不冒泡)
POINTER_MOVEedge:pointermove指针在边上移动时触发
POINTER_OUTedge:pointerout指针离开边时触发
POINTER_DOWNedge:pointerdown指针在边上按下时触发
POINTER_UPedge:pointerup指针在边上抬起时触发
CONTEXT_MENUedge:contextmenu边上打开上下文菜单时触发
DRAG_ENTERedge:dragenter拖拽物进入边时触发
DRAG_OVERedge:dragover拖拽物在边上方时触发
DRAG_LEAVEedge:dragleave拖拽物离开边时触发
DROPedge:drop在边上放置拖拽物时触发

Combo事件 (ComboEvent)

常量名事件名描述
CLICKcombo:click点击Combo时触发
DBLCLICKcombo:dblclick双击Combo时触发
POINTER_OVERcombo:pointerover指针移入Combo时触发
POINTER_LEAVEcombo:pointerleave指针离开Combo时触发
POINTER_ENTERcombo:pointerenter指针进入Combo或其子元素时触发(不冒泡)
POINTER_MOVEcombo:pointermove指针在Combo上移动时触发
POINTER_OUTcombo:pointerout指针离开Combo时触发
POINTER_DOWNcombo:pointerdown指针在Combo上按下时触发
POINTER_UPcombo:pointerup指针在Combo上抬起时触发
CONTEXT_MENUcombo:contextmenuCombo上打开上下文菜单时触发
DRAG_STARTcombo:dragstart开始拖拽Combo时触发
DRAGcombo:drag拖拽Combo过程中触发
DRAG_ENDcombo:dragend拖拽Combo结束时触发
DRAG_ENTERcombo:dragenter拖拽物进入Combo时触发
DRAG_OVERcombo:dragover拖拽物在Combo上方时触发
DRAG_LEAVEcombo:dragleave拖拽物离开Combo时触发
DROPcombo:drop在Combo上放置拖拽物时触发

画布事件 (CanvasEvent)

常量名事件名描述
CLICKcanvas:click点击画布空白处时触发
DBLCLICKcanvas:dblclick双击画布空白处时触发
POINTER_OVERcanvas:pointerover指针移入画布时触发
POINTER_LEAVEcanvas:pointerleave指针离开画布时触发
POINTER_ENTERcanvas:pointerenter指针进入画布或其子元素时触发(不冒泡)
POINTER_MOVEcanvas:pointermove指针在画布上移动时触发
POINTER_OUTcanvas:pointerout指针离开画布时触发
POINTER_DOWNcanvas:pointerdown指针在画布上按下时触发
POINTER_UPcanvas:pointerup指针在画布上抬起时触发
CONTEXT_MENUcanvas:contextmenu画布上打开上下文菜单时触发
DRAG_STARTcanvas:dragstart开始拖拽画布时触发
DRAGcanvas:drag拖拽画布过程中触发
DRAG_ENDcanvas:dragend拖拽画布结束时触发
DRAG_ENTERcanvas:dragenter拖拽物进入画布时触发
DRAG_OVERcanvas:dragover拖拽物在画布上方时触发
DRAG_LEAVEcanvas:dragleave拖拽物离开画布时触发
DROPcanvas:drop在画布上放置拖拽物时触发
WHEELcanvas:wheel在画布上滚动鼠标滚轮时触发

图表生命周期事件 (GraphEvent)

常量名事件名描述
BEFORE_CANVAS_INITbeforecanvasinit画布初始化之前触发
AFTER_CANVAS_INITaftercanvasinit画布初始化之后触发
BEFORE_SIZE_CHANGEbeforesizechange视口尺寸变更之前触发
AFTER_SIZE_CHANGEaftersizechange视口尺寸变更之后触发
BEFORE_ELEMENT_CREATEbeforeelementcreate元素创建之前触发
AFTER_ELEMENT_CREATEafterelementcreate元素创建之后触发
BEFORE_ELEMENT_UPDATEbeforeelementupdate元素更新之前触发
AFTER_ELEMENT_UPDATEafterelementupdate元素更新之后触发
BEFORE_ELEMENT_DESTROYbeforeelementdestroy元素销毁之前触发
AFTER_ELEMENT_DESTROYafterelementdestroy元素销毁之后触发
BEFORE_ELEMENT_TRANSLATEbeforeelementtranslate元素平移之前触发
AFTER_ELEMENT_TRANSLATEafterelementtranslate元素平移之后触发
BEFORE_DRAWbeforedraw绘制开始之前触发
AFTER_DRAWafterdraw绘制结束之后触发
BEFORE_RENDERbeforerender渲染开始之前触发
AFTER_RENDERafterrender渲染完成之后触发
BEFORE_ANIMATEbeforeanimate动画开始之前触发
AFTER_ANIMATEafteranimate动画结束之后触发
BEFORE_LAYOUTbeforelayout布局开始之前触发
AFTER_LAYOUTafterlayout布局结束之后触发
BEFORE_STAGE_LAYOUTbeforestagelayout流水线布局过程中每个阶段开始前触发
AFTER_STAGE_LAYOUTafterstagelayout流水线布局过程中每个阶段结束后触发
BEFORE_TRANSFORMbeforetransform可视区域变化之前触发
AFTER_TRANSFORMaftertransform可视区域变化之后触发
BATCH_STARTbatchstart批处理操作开始时触发
BATCH_ENDbatchend批处理操作结束时触发
BEFORE_DESTROYbeforedestroy图表销毁前触发
AFTER_DESTROYafterdestroy图表销毁后触发
BEFORE_RENDERER_CHANGEbeforerendererchange渲染器变更之前触发
AFTER_RENDERER_CHANGEafterrendererchange渲染器变更之后触发

容器事件 (ContainerEvent)

常量名事件名描述
KEY_DOWNkeydown键盘按键按下时触发
KEY_UPkeyup键盘按键抬起时触发

通用事件 (CommonEvent)

这些是不带前缀的事件,可用于监听全局事件:

常量名事件名描述
CLICKclick点击任何元素时触发
DBLCLICKdblclick双击任何元素时触发
POINTER_OVERpointerover指针移入任何元素时触发
POINTER_LEAVEpointerleave指针离开任何元素时触发
POINTER_ENTERpointerenter指针进入任何元素或其子元素时触发(不冒泡)
POINTER_MOVEpointermove指针在任何元素上移动时触发
POINTER_OUTpointerout指针离开任何元素时触发
POINTER_DOWNpointerdown指针在任何元素上按下时触发
POINTER_UPpointerup指针在任何元素上抬起时触发
CONTEXT_MENUcontextmenu任何元素上打开上下文菜单时触发
DRAG_STARTdragstart开始拖拽任何元素时触发
DRAGdrag拖拽任何元素过程中触发
DRAG_ENDdragend拖拽任何元素结束时触发
DRAG_ENTERdragenter拖拽物进入任何元素时触发
DRAG_OVERdragover拖拽物在任何元素上方时触发
DRAG_LEAVEdragleave拖拽物离开任何元素时触发
DROPdrop在任何元素上放置拖拽物时触发
KEY_DOWNkeydown键盘按键按下时触发
KEY_UPkeyup键盘按键抬起时触发
WHEELwheel滚动鼠标滚轮时触发
PINCHpinch多点触控屏幕上双指捏合或张开时触发

使用技巧

链式调用

G6 的事件 API 支持链式调用,可以连续注册多个事件:

import { NodeEvent, EdgeEvent, CanvasEvent } from '@antv/g6';
// 使用常量枚举+链式调用
graph.on(NodeEvent.CLICK, handleNodeClick).on(EdgeEvent.CLICK, handleEdgeClick).on(CanvasEvent.WHEEL, handleCanvasZoom);

事件代理

你可以利用事件冒泡机制,在父元素上监听所有子元素的事件:

import { CommonEvent } from '@antv/g6';
// 统一处理所有元素的点击事件
graph.on(CommonEvent.CLICK, (evt) => {
const { targetType, target } = evt;
if (targetType === 'node') {
console.log('点击了节点:', target.id);
} else if (targetType === 'edge') {
console.log('点击了边:', target.id);
} else {
console.log('点击了画布空白处');
}
});

事件对象属性

大多数事件的回调函数会接收一个事件对象,包含以下常用属性:

  • target - 触发事件的元素
  • targetType - 触发事件的元素类型(node/edge/combo/canvas)
  • originalTarget - 原始的触发事件的图形
  • currentTarget - 当前触发事件的对象
  • originalEvent - 原始的浏览器事件对象

通过这些属性,你可以精确地控制交互行为。