事件监听

事件系统概述

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

事件分类

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

1. 元素事件：与节点、边、Combo 相关的事件，如 node:click, edge:mouseenter
2. 画布事件：与整个画布相关的事件，如 canvas:drag, canvas:wheel
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;

参数

返回值

• 类型： 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;

参数

返回值

• 类型： 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;

参数

返回值

• 类型： 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;

参数

返回值

• 类型： 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)

边事件 (EdgeEvent)

Combo事件 (ComboEvent)

画布事件 (CanvasEvent)

图表生命周期事件 (GraphEvent)

容器事件 (ContainerEvent)

通用事件 (CommonEvent)

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

使用技巧

链式调用

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 - 原始的浏览器事件对象

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