G6 事件系统完全指南：从 Graph/Canvas/Element 事件监听到底层分发机制

数据可视化前端图表库【免费下载链接】G6♾ A Graph Visualization Framework in JavaScript.项目地址https://gitcode.com/gh_mirrors/g6/G6点击查看免费下载G6antv/g6的事件系统是在底层图形渲染引擎 G 为主线结合仓库源码事件常量定义、Graph 运行时实现、BehaviorController 事件转发、插件与测试用例系统讲解 G6 事件分类、监听/解绑/手动触发的完整 API以及事件对象的结构与底层分发原理帮助你掌握在 G6 中实现节点点击、画布拖拽、生命周期钩子等交互逻辑的完整方案。OverviewG6 事件系统概览G6 的事件系统并非从零实现而是基于 GAntV 图形渲染引擎的事件系统封装而成在其之上扩展了更全面的事件类型和更方便的事件绑定/解绑方法。从源码结构看这一封装主要体现在两个层面事件常量枚举G6 将所有事件名以枚举形式集中定义在 packages/g6/src/constants/events/index.ts 中并通过 packages/g6/src/exports.ts 对外导出CanvasEvent、ComboEvent、CommonEvent、ContainerEvent、EdgeEvent、GraphEvent、HistoryEvent、NodeEvent等枚举开发者可以从antv/g6直接引入使用。统一的监听 APIGraph实例继承自EventEmitter见 packages/g6/src/runtime/graph.tson/once/off/emit四个方法在 Graph 上对外暴露实际委托给antv/event-emitter完成底层的事件注册与派发。事件分类Graph、Canvas 与 ElementG6 的事件类型主要分为以下三大类Graph 事件图实例事件与整个图实例生命周期相关的事件例如渲染完成事件、更新事件等Canvas 事件画布事件与画布相关的事件例如画布点击、画布拖拽等Element 事件元素事件发生在元素对象上的事件例如节点拖拽、边点击等。下面分别展开说明。Graph 事件GraphEventGraph 事件与图实例的整个生命周期绑定例如beforecanvasinit画布初始化前、beforerender/afterrender渲染开始前/完成后、beforelayout/afterlayout布局前后、beforedestroy/afterdestroy销毁前后等。完整的 Graph 事件清单可参见 packages/site/docs/api/event.en.md 中的 Graph 生命周期事件GraphEvent章节。以监听图渲染完成事件为例import { Graph, GraphEvent } from antv/g6; const graph new Graph({ // 图配置 }); graph.on(GraphEvent.AFTER_RENDER, () { // 渲染完成后的回调 console.log(graph rendered); });为什么监听 AFTER_RENDER 很重要从 packages/g6/src/runtime/graph.ts 的render()实现可以看到render是异步方法内部会执行数据更新、元素绘制、布局官方注释明确指出render 为异步方法如果需要在 render 后执行一些操作可以使用await graph.render()或者监听 GraphEvent.AFTER_RENDER 事件。源码在渲染流程开头emit(this, new GraphLifeCycleEvent(GraphEvent.BEFORE_RENDER))第 1198 行在所有绘制、布局、自适应完成后emit(this, new GraphLifeCycleEvent(GraphEvent.AFTER_RENDER))第 1213 行。因此监听AFTER_RENDER是拿到图已就绪信号的最可靠方式。Canvas 事件CanvasEventCanvas 事件与画布本身相关例如canvas:click点击画布空白区域、canvas:drag拖拽画布、canvas:wheel滚轮缩放等。完整清单参见 packages/site/docs/api/event.en.md 的 Canvas 事件CanvasEvent章节。监听画布点击事件import { Graph, CanvasEvent } from antv/g6; const graph new Graph({ // 图配置 }); graph.on(CanvasEvent.CLICK, (event) { // 点击画布空白区域 console.log(canvas clicked); });Element 事件NodeEvent / EdgeEvent / ComboEventElement 事件主要指在元素对象上触发的事件例如节点的拖拽事件、边的点击事件。元素分为三类节点node、边edge与 Combocombo对应的事件枚举为NodeEvent节点事件EdgeEvent边事件ComboEventCombo 事件与 Canvas 事件的监听方式一致例如监听节点的拖拽事件、边的点击事件import { Graph, NodeEvent, EdgeEvent, ComboEvent } from antv/g6; const graph new Graph({ // 图配置 }); graph.on(NodeEvent.DRAG, (event) { // 节点拖拽中 }); graph.on(EdgeEvent.CLICK, (event) { // 边被点击 }); graph.on(ComboEvent.CLICK, (event) { // Combo 被点击 });事件命名规范与常量枚举G6 的事件名遵循[object]:[event]的命名格式例如node:click—— 节点点击事件edge:mouseenter—— 鼠标移入边事件canvas:drag—— 画布拖拽事件G6 为每一类事件提供了完整的常量枚举定义于 packages/g6/src/constants/events/ 目录下的node.ts、edge.ts、combo.ts、canvas.ts、graph.ts、common.ts、container.ts、history.ts、animation.ts官方 API 文档强烈推荐使用这些常量而非直接书写字符串事件名其优势在于类型安全避免事件名字符串拼写错误智能提示在 IDE 中可获得自动补全与代码提示。节点事件NodeEvent源码见 packages/g6/src/constants/events/node.ts常量名事件名说明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:contextmenu在 Combo 上打开右键菜单时触发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源码见 packages/g6/src/constants/events/canvas.ts常量名事件名说明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源码见 packages/g6/src/constants/events/graph.ts常量名事件名说明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渲染器变更之后触发这些生命周期事件在源码中被真实派发例如render()中派发BEFORE_RENDER/AFTER_RENDERpackages/g6/src/runtime/graph.ts布局控制器在 packages/g6/src/runtime/layout.ts 中派发BEFORE_LAYOUT/AFTER_LAYOUT/BEFORE_STAGE_LAYOUT/AFTER_STAGE_LAYOUT视口控制器在 packages/g6/src/runtime/viewport.ts 中派发BEFORE_TRANSFORM/AFTER_TRANSFORM。容器事件与通用事件ContainerEvent容器事件keydown按下键盘、keyup抬起键盘与画布容器 DOM 绑定由BehaviorController通过container.addEventListener转发见 packages/g6/src/runtime/behavior.ts。CommonEvent通用事件不带前缀、可监听全局的事件如click、dblclick、pointermove、wheel、pinch多指捏合等完整枚举见 packages/g6/src/constants/events/common.ts。当事件命中某个元素时G6 会同时派发带前缀事件node:click与不带前缀的通用事件click因此可以用CommonEvent.CLICK做事件委托详见下文事件委托。事件监听与解绑 APIG6 提供了以下四个事件相关 APIon、off、once、emit其实现委托自antv/event-emitter见 packages/g6/src/runtime/graph.ts且均返回thisGraph 实例支持链式调用。on添加事件监听const handler (event) { // 事件处理逻辑 }; graph.on(event_name, handler);带类型参数与 once 标志的完整签名onT extends IEvent IEvent(eventName: string, callback: (event: T) void, once?: boolean): this;一个结合 API 文档的实战示例packages/site/docs/api/event.en.mdimport { NodeEvent, EdgeEvent, CanvasEvent } from antv/g6; // 监听节点点击事件 graph.on(NodeEvent.CLICK, (evt) { const { target } evt; // 被点击节点的 id console.log(Node ${target.id} was clicked); // 获取节点数据 const nodeData graph.getNodeData(target.id); console.log(Node data:, nodeData); // 修改节点状态 graph.setElementState(target.id, selected); }); // 监听边 hover 事件 graph.on(EdgeEvent.POINTER_OVER, (evt) { const { target } evt; graph.setElementState(target.id, highlight); }); // 监听画布拖拽事件 graph.on(CanvasEvent.DRAG, (evt) { console.log(Canvas is being dragged); });off移除事件监听graph.off(event_name, handler);当不传任何参数时将移除所有事件监听graph.off();off有三种重载形式见 packages/g6/src/runtime/graph.tsoff()—— 移除全部事件监听off(eventName)—— 移除指定事件的全部监听off(eventName, callback)—— 移除指定事件的指定回调。import { NodeEvent } from antv/g6; // 移除所有节点点击事件监听 graph.off(NodeEvent.CLICK); // 移除指定回调 const handleNodeClick (evt) { console.log(Node clicked:, evt.target.id); }; graph.on(NodeEvent.CLICK, handleNodeClick); // 在合适时机移除该监听 graph.off(NodeEvent.CLICK, handleNodeClick);once一次性事件监听添加一次性事件监听事件触发后监听器会自动移除graph.once(event_name, handler);适合首次渲染后做一次性初始化、等待用户首次交互等场景import { GraphEvent, NodeEvent } from antv/g6; // 首次渲染完成后只执行一次 graph.once(GraphEvent.AFTER_RENDER, () { console.log(Chart rendered for the first time); highlightImportantNodes(); }); // 用户首次点击节点后给出引导提示 graph.once(NodeEvent.CLICK, (evt) { console.log(User clicked a node for the first time:, evt.target.id); showTutorialTip(You can drag nodes to change their position); });emit手动触发事件如果需要手动触发事件可以使用emit方法graph.emit(event_name, { // 事件数据 });emit的典型用途是测试与状态模拟G6 官方测试用例 packages/g6/tests/unit/behaviors/click-select.spec.ts 中正是通过graph.emit(NodeEvent.CLICK, { target: { id: 0 }, targetType: node })来模拟节点点击从而驱动click-select行为进行快照断言。这说明事件对象至少需要携带target与targetType字段才能被下游逻辑正确识别。事件对象结构大多数事件回调会收到一个事件对象其中包含以下常用属性类型定义见 packages/g6/src/types/event.ts属性说明target触发事件的元素节点 / 边 / Combo / 画布targetType触发事件的元素类型node \| edge \| combo \| canvasoriginalTarget触发事件的原始图形通常是元素内部的某个 shapecurrentTarget当前触发事件的对象originalEvent原始浏览器事件对象事件对象的类型体系为IEvent联合类型包含IGraphLifeCycleEvent、IAnimateEvent、IElementLifeCycleEvent、IViewportEvent、IPointerEvent、IWheelEvent、IKeyboardEvent、IDragEvent。其中拖拽类事件额外携带dx、dy本次拖拽的位移增量IPointerEvent基于 G 的FederatedPointerEvent扩展保留了原生指针事件的全部字段。结合这些属性可以精确控制交互行为import { CommonEvent } from antv/g6; // 统一处理所有元素的点击事件 graph.on(CommonEvent.CLICK, (evt) { const { targetType, target } evt; if (targetType node) { console.log(Clicked on node:, target.id); } else if (targetType edge) { console.log(Clicked on edge:, target.id); } else { console.log(Clicked on canvas blank area); } });底层原理事件是如何分发到 Graph 上的理解事件系统的底层分发机制有助于排查问题。从源码看浏览器原生事件到 G6 事件的流转由BehaviorController完成关键实现在 packages/g6/src/runtime/behavior.ts注册原生监听forwardEvents()第 33-66 行在画布容器上监听keydown/keyup通过forwardContainerEvents直接转发并在画布的document上监听click、dblclick、pointerover、pointermove、drag、drop、wheel等一整套通用事件。解析事件目标forwardCanvasEvents第 68-126 行调用工具函数eventTargetOf命中事件目标。该函数定义在 packages/g6/src/utils/event/index.ts它从事件命中的图形shape沿parentElement向上遍历判断是否属于节点 / 边 / Combo分别调用isNode/isEdge/isCombo判断返回{ type: node | edge | combo | canvas, element }。带前缀派发G6 将事件同时派发为带前缀事件与通用事件即graph.emit(${targetType}:${type}, stdEvent)与graph.emit(type, stdEvent)第 102-103 行。这正是graph.on(NodeEvent.CLICK)与graph.on(CommonEvent.CLICK)都能收到点击事件的原因。双击detail 2和右键button 2也会被特殊处理为dblclick与contextmenu事件第 106-125 行。容器的键盘事件forwardContainerEvents第 128-130 行直接把keydown/keyup转发为ContainerEvent.KEY_DOWN/KEY_UP。生命周期事件图生命周期类事件则由各运行时控制器graph / layout / viewport 等通过emit(graph, new GraphLifeCycleEvent(...))主动派发事件载体类定义在 packages/g6/src/utils/event/events.ts其中GraphLifeCycleEvent、AnimateEvent、ElementLifeCycleEvent、ViewportEvent均继承自BaseEvent。实战技巧链式调用由于on/once/off都返回 Graph 实例可以连续注册多个事件import { NodeEvent, EdgeEvent, CanvasEvent } from antv/g6; graph .on(NodeEvent.CLICK, handleNodeClick) .on(EdgeEvent.CLICK, handleEdgeClick) .on(CanvasEvent.WHEEL, handleCanvasZoom);事件委托利用事件冒泡机制可以在父级统一处理子元素事件G6 默认同时派发通用事件import { CommonEvent } from antv/g6; graph.on(CommonEvent.CLICK, (evt) { const { targetType, target } evt; if (targetType node) { console.log(Clicked on node:, target.id); } else if (targetType edge) { console.log(Clicked on edge:, target.id); } else { console.log(Clicked on canvas blank area); } });插件中的事件生命周期管理G6 内置插件大量使用graph.on/graph.off完成事件绑定与解绑。以 Tooltip 插件 packages/g6/src/plugins/tooltip.ts 为例它根据trigger配置hover或click动态生成事件映射表getEvents()在bindEvents()中逐个graph.on(eventName, handler)在unbindEvents()/update()时逐个graph.off(eventName, handler)以避免重复绑定。这种绑定前先解绑的模式值得在自定义逻辑中借鉴——尤其是在动态切换监听行为时务必成对使用on/off防止内存泄漏与重复回调。使用常量枚举而非字符串所有事件都应优先使用GraphEvent、CanvasEvent、NodeEvent、EdgeEvent、ComboEvent、CommonEvent、ContainerEvent等枚举常量既可获得类型检查与 IDE 提示也能规避字符串拼写错误。小结G6 的事件系统以 G 图形引擎为底座通过统一的事件常量枚举packages/g6/src/constants/events/、Graph 实例上的on/once/off/emitAPI 以及BehaviorController的底层事件转发将图生命周期、画布交互与元素交互三类事件完整地暴露给开发者。掌握本文的事件分类、常量清单、事件对象结构与分发原理即可在 G6 项目中实现从点击节点改状态到渲染完成后初始化的各类交互逻辑。更完整的 API 参数与逐事件说明可继续查阅 packages/site/docs/api/event.en.md。赞分享数据可视化前端图表库【免费下载链接】G6♾ A Graph Visualization Framework in JavaScript.项目地址https://gitcode.com/gh_mirrors/g6/G6点击查看免费下载相关推荐canvas-editor事件系统完全解析从基础监听到底层原理canvas editor事件系统完全解析从基础监听到底层原理 canvas editor作为一款基于Canvas/SVG的富文本编辑器其强大而灵活的事件系前端UI组件富文本终极Cloudreve插件钩子开发指南从事件监听到底层实现的完整教程终极Cloudreve插件钩子开发指南从事件监听到底层实现的完整教程 Cloudreve是一款功能强大的自托管云盘系统支持多种存储提供商。本文将带你深入了解后端对象存储G6 事件系统完全指南事件监听 API 与常量枚举实战G6 事件系统完全指南事件监听 API 与常量枚举实战 G6 为 JavaScript 图可视化应用提供了完整的事件机制支持响应节点点击、边悬停、画布拖拽等数据可视化前端图表库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考