Cytoscape.js 核心事件 API：深入掌握 cy.one() 一次性事件监听

数据可视化【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址https://gitcode.com/gh_mirrors/cy/cytoscape.js点击查看免费下载导读cy.one()是 Cytoscape.js 核心对象core提供的一次性事件监听方法它为指定事件注册一个回调该回调最多只触发一次触发后即被自动移除。本文以 documentation/md/core/one.md 为主线结合 src/core/events.mjs、src/emitter.mjs 等源码实现系统讲解cy.one()的用法、参数、事件选择器、命名空间、别名方法及其与cy.on()、cy.pon()的关系并给出可直接运行的实战示例帮助你精准控制事件生命周期。1. cy.one() 是什么一次性事件监听在 Cytoscape.js 中core 对象是访问图数据与交互能力的入口参见 core 概述。与持续监听的cy.on()不同cy.one()注册的处理器在首次命中事件后自动解除绑定后续相同事件再次发生时不再回调。cy.one(tap, node, function(){ console.log(tap!); }); cy.$(node).eq(0).trigger(tap); // tap! cy.$(node).eq(1).trigger(tap); // nothing b/c already tapped上面这段来自官方文档的示例完整展示了两种典型行为第一次对节点触发tap时回调执行并打印tap!第二次触发时由于该一次性处理器已被移除控制台不再有任何输出。该行为在 src/core/events.mjs 中由one()实现one: function( events, selector, callback ){ this.emitter().one( events, argSelector(selector), callback ); return this; },注意cy.one()返回 core 自身因此支持链式调用。同时 core 还提供了once()作为one()的别名见 src/core/events.mjs二者行为完全一致。2. 方法签名与参数说明cy.one( events, selector, callback )与cy.on()的签名完全兼容均支持以下参数参数类型说明是否必填eventsString事件类型字符串可包含命名空间如tap、tap.foo多个事件用空格分隔如tap dbltap是selectorString | null可选的元素选择器用于过滤从元素冒泡到 core 的事件传入null或省略时监听所有事件否callbackFunction事件触发时执行的回调函数接收事件对象为第一个参数是events字符串的解析逻辑在 src/emitter.mjs 中定义内部通过正则^([^.])(\.(?:[^.]))?$拆分出事件类型与命名空间。也就是说cy.one(tap.foo, ...)注册的是命名空间为foo的tap事件这类事件可以通过removeListener按命名空间精确移除详见下文第 5 节。3. 结合选择器过滤冒泡事件Cytoscape.js 的图事件遵循事件冒泡机制元素上发生的事件会先冒泡到其复合父节点最终冒泡到 core见 事件冒泡说明。因此cy.one()的selector参数用于在 core 层面过滤来源——只响应来自匹配该选择器的元素的事件。例如只想监听「来自node类型元素」的首次点击cy.one(tap, node, function(evt){ var node evt.target; // 事件来源元素 console.log(tapped node.id()); });也可以进一步收窄到具体 id 或样式条件比如只响应#foo节点或[weight 100]的边。选择器匹配的底层实现在 src/core/events.mjs当监听器带有qualifier即 selector时eventMatches会要求事件目标必须是元素且满足selector.matches(eventObj.target)同时回调的this上下文会被绑定到事件来源元素而非 core 本身——这一点与带选择器的cy.on()完全一致便于直接在回调里操作触发事件的元素。对应地元素集合上也提供eles.one()与eles.once()一次性监听见 src/collection/events.mjs区别在于eles.one()会为集合中每个元素分别注册一次性监听eles.once()则借助onceCollection在首次触发时从集合上统一移除两者细节略有差异但使用方式相同。4. 事件对象回调中能拿到什么cy.one()回调的第一个参数是标准事件对象参见 事件对象字段说明常用字段包括cy对应的 Cytoscape.js core 实例引用target事件的起源者——可能是某个元素也可能是 core 自身背景被点击时type事件类型字符串如tapnamespace事件命名空间字符串如footimeStamp事件发生的 Unix 毫秒时间戳。对于用户输入类事件还额外携带position模型坐标、renderedPosition渲染坐标与originalEvent原生事件对象。结合target与选择器可以区分「点击了节点」与「点击了空白背景」cy.one(tap, function(evt){ if (evt.target cy) { console.log(点击了背景仅响应一次); } else { console.log(点击了元素 evt.target.id() 仅响应一次); } });5. 与 on / pon / removeListener 的分工协作5.1cy.on()持续监听cy.on()注册的事件会持续生效直到被removeListener显式移除或实例销毁。若某段逻辑需要持续响应事件应使用 cy.on() 文档 中的写法cy.on(tap, node, function(evt){ var node evt.target; console.log(tapped node.id()); });5.2cy.pon()Promise 化的一次性监听如果希望在「首次事件到来」时获得一个 Promise例如把初始化逻辑编排进异步流程可使用cy.pon()/cy.promiseOn()见 cy.promiseOn() 文档cy.pon(tap).then(function( event ){ console.log(tap promise fulfilled); });从实现看pon本质上是one的 Promise 包装它在 src/define/events.mjs 中注册一次性回调事件触发时先解除绑定再resolve事件对象因此每个 Promise 只会被兑现一次。5.3cy.removeListener()按需解除即使是一次性监听也常需要「反悔」的场景。cy.removeListener()支持按事件类型、命名空间、选择器与回调函数组合精确移除见 cy.removeListener() 文档// 移除所有 tap 监听含一次性监听 cy.removeListener(tap); // 只移除指定的那个 handler var handler function(){ console.log(called handler); }; cy.one(tap, handler); cy.removeListener(tap, handler);其匹配逻辑见 src/emitter.mjs仅当事件类型或使用通配符*、命名空间、qualifier 与 callback 均匹配时才删除若在事件分发过程中移除监听器内部会先拷贝监听列表emitting ! 0时避免迭代过程中数组变动引发错乱。5.4cy.emit()手动触发事件cy.emit()用于手动派发事件并携带附加参数见 cy.emit() 文档可用于测试一次性监听逻辑或驱动自定义事件cy.on(tap, function(evt, f, b){ console.log(tap, f, b); }); cy.emit(tap, [foo, bar]);同样地cy.one()注册的监听也会被cy.emit()触发一次后自动移除因此可以用它快速验证一次性行为。5.5 方法别名一览src/define/events.mjs 为上述 API 提供了便捷别名方便不同习惯的开发者使用标准方法别名onaddListener、listen、bindremoveListeneroff、unlisten、unbindemittriggerone/once—core 上once即onepromiseOnpon6. 一次性监听的源码原理one 标志位与自动清理理解cy.one()为什么「只触发一次」关键在于 src/emitter.mjs 的两处实现注册阶段——p.one复用p.on并注入{ one: true }配置src/emitter.mjsp.one function( events, qualifier, callback, conf ){ return this.on( events, qualifier, callback, conf, { one: true } ); };派发阶段——在真正调用回调之前若监听器带有one标志先从监听器列表中剔除自身src/emitter.mjsif( listener.conf listener.conf.one ){ self.listeners self.listeners.filter( l l ! listener ); }这意味着「自动移除」发生在回调执行之前即使回调内部再次触发同一事件也不会产生递归式重复调用。这种设计让cy.one()天然适合初始化钩子、引导提示、一次性动画启动等只应执行一次的交互逻辑。7. 实战场景示例7.1 首次点击后才开始初始化利用cy.one(ready)在实例就绪后执行一次性初始化源码内部也大量采用这一模式如 src/core/index.mjs 中通过cy.one(layoutready, ...)链式编排初始化流程const cy cytoscape({ container: document.getElementById(cy), elements: [ /* 节点与边数据 */ ] }); cy.one(ready, function(){ console.log(实例已就绪开始初始化业务逻辑); cy.layout({ name: cose }).run(); });7.2 首次命中节点后显示引导提示cy.one(tap, node, function(evt){ showTooltip(你已经点击了节点 evt.target.id() 接下来可以拖拽它试试); });7.3 等待下一次渲染完成再导出图片cy.one(render, function(){ console.log(渲染完成可以调用 cy.png() 导出截图); cy.png({ full: true, scale: 2 }); });8. 小结cy.one()是 Cytoscape.js 事件体系中最常用的「一次性钩子」与cy.on()共用相同的(events, selector, callback)签名与选择器冒泡过滤机制通过 emitter 层的one标志位在回调执行前自动解除绑定保证只触发一次与cy.pon()Promise 化、cy.removeListener()精确解绑、cy.emit()手动触发组合可覆盖绝大多数事件生命周期管理需求相关实现与文档可在 src/core/events.mjs、src/emitter.mjs、src/collection/events.mjs 及 documentation/md/events.md 中进一步查阅。在「初始化一次」「首次交互引导」「等待某状态就绪」等场景下优先考虑cy.one()能让代码更简洁、行为更可预期。赞分享数据可视化【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址https://gitcode.com/gh_mirrors/cy/cytoscape.js点击查看免费下载相关推荐cytoscape.js 事件 Promise 化深入解析 promiseOn() 与 pon() 的一次性事件监听机制cytoscape.js 事件 Promise 化深入解析 promiseOn 与 pon 的一次性事件监听机制 导读 本文围绕 cytoscape.js 的数据可视化Cytoscape.js 核心事件监听 cy.on() 完全指南事件绑定、冒泡与实战用法Cytoscape.js 核心事件监听 cy.on 完全指南事件绑定、冒泡与实战用法 Cytoscape.js 是一个用于图可视化与分析的图论网络库。在交数据可视化Playwright 事件系统详解等待事件、监听器增删与一次性监听器Playwright 事件系统详解等待事件、监听器增删与一次性监听器 Playwright 提供了一套统一的“事件驱动”编程模型页面上的网络请求、弹窗po测试开发工具浏览器控制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考