` 的用法与实现原理)
数据可视化【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址https://gitcode.com/gh_mirrors/cy/cytoscape.js点击查看免费下载cy.collection()是 cytoscape.js 中用于构建元素集合collection的核心方法。本文以官方文档 documentation/md/core/collection.md 为骨架结合仓库源码 src/core/search.mjs、src/collection/index.mjs 及测试用例 test/collection-building-and-filtering.mjs系统讲解该 API 的四种调用形式、removed与unique选项的语义、集合运算如union/merge的底层机制并给出可直接运行于实际项目中的代码示例。cy.collection()是什么在 cytoscape.js 中集合collection是节点node和边edge的容器支持链式调用、批量操作与集合运算。cy.collection()是 core 实例提供的集合工厂专门用于按需构建、累积和维护集合对象。官方文档对其定位只有一句话This function is useful for building up collections此函数对逐步构建集合非常有用。但它背后的实际行为远比一句话丰富。从 src/core/search.mjs 的实现看cy.collection( eles, opts )会根据第一个参数的类型走四条不同的分支调用形式参数类型返回结果cy.collection()无参数返回一个空的集合new Collection( this )cy.collection( selector )字符串等价于cy.$( selector )返回图中匹配选择器的元素cy.collection( eles )元素 / 集合调用eles.collection()返回对应集合cy.collection( jsonArray, opts )数组用 JSON 定义新建元素按opts决定是否加入图其中无参数与JSON 数组两种形式正是官方文档两个示例所演示的场景也是最常用的构建方式。示例一持续累积被点击的节点官方文档给出的第一个示例展示如何用一个集合累积记录所有被用户点击过的节点var collection cy.collection(); cy.nodes().on(click, function(e){ var clickedNode e.target; collection collection.union(clickedNode); });这里的关键链路是cy.collection()先创建空集合作为累积的起点监听所有节点的click事件e.target是被点击的节点元素通过collection.union(clickedNode)把新点击的节点并入集合并将结果重新赋给collection。union与merge的底层差异union属于非破坏性集合运算返回一个包含调用集合与参数集合全部元素的新集合而源码中与它共享逻辑的merge则是就地修改调用集合。在 src/collection/filter.mjs 中merge的实现要点是使用集合内部的map以元素 id 为键做去重判断let add !map.has( id )仅当 id 尚未存在时才把元素追加到this[ this.length ]并更新 map因此重复merge同一个元素不会产生重复项。同文件末尾的别名声明src/collection/filter.mjs则展示了union的多个等价写法fn[ u ] fn[ | ] fn[ ] fn.union fn.or fn.add;也就是说collection.union(clickedNode)也可以写成collection.add(clickedNode)、collection.or(clickedNode)甚至collection。开发者可以根据可读性选择任一别名。值得注意这个示例中的累积模式对remove事件并不感知。如果某个节点已被点击后从图中移除union前的旧集合仍持有该元素的引用。若需要严格同步图状态可以配合collection cy.nodes()或使用collection.intersect(cy.elements())过滤。示例二创建尚未加入图的元素集合官方文档的第二个示例展示了如何用 JSON 数组直接构建一个已处于removed状态的集合var removedCollection cy.collection([{ data: { id: a } }, { data: { id: b } }], { removed: true }); removedCollection.forEach(element { console.log(element.removed()); // true });执行结果是集合中每个元素的element.removed()都返回true表示这些元素并未出现在图渲染视图中只是作为可操作的对象存在。参数语义opts.removed与opts.uniquecy.collection( eles, opts )的第二个参数支持两个选项在 src/core/search.mjs 中被透传给Collection构造函数opts.removed为true时新创建的集合元素不会调用restore()加入图保持已移除状态不传或为false时元素创建后会被自动恢复加入图。opts.unique为true时构造过程按元素 id 去重重复 id 的元素只保留第一个。在 src/collection/index.mjs 的构造函数中这两项的行为可以逐一对应JSON 转元素当传入数组的首项是普通对象is.plainObject( elements[0] )且不是已有元素时会进入createdElements true分支src/collection/index.mjs若 JSON 中未提供data.id会自动用util.uuid()生成唯一 iddata.id util.uuid()若 id 与图中已有元素或本次列表内元素冲突该条 JSON 会被跳过continue避免 id 重复每条 JSON 被包装成new Element( cy, json, false )注意第三个参数false表示暂不恢复。是否入图构造函数末尾执行if( createdElements !removed ){ this.restore(); }src/collection/index.mjs。这正是removed: true与默认行为的唯一分水岭——只有removed为假时才会调用restore()把元素真正加入图。去重逻辑在填充内部数组的循环中if( !unique || !map.has(id) )决定是否收录该元素unique为true时同时维护_private.map的 id 索引src/collection/index.mjs。实际应用场景removed: true形态的典型用途包括预构建元素先用 JSON 定义一批元素经过数据校验、拓扑排序或过滤后再统一restore()加入图批量添加把元素集合暂存配合collection.remove()与collection.restore()实现临时隐藏/再次显示数据转移官方文档 documentation/md/core/add.md 提到若将某核心实例的元素集合指定到另一个核心实例会创建这些元素的副本从而实现实例间的元素迁移。关于示例代码的勘误说明官方文档原示例末尾的forEach回调中缺少闭合圆括号写作};。正确写法应为removedCollection.forEach(element { console.log(element.removed()); // true });forEach来自集合原型继承的数组迭代能力具体实现在 src/collection/iteration.mjs其行为与原生Array.prototype.forEach一致回调签名是( ele, i, eles )。集合对象的基础能力通过cy.collection()得到的对象是一个扩展了Array.prototype的集合类型。源码 src/collection/index.mjs 中明确写道let elesfn Element.prototype Collection.prototype Object.create(Array.prototype);这意味着集合与单个元素共享同一套原型方法注释为an element has the same functions as a collection从而支持统一的链式调用。围绕本文主题常用的基础能力包括长度与判空src/collection/iteration.mjsvar col cy.collection(); col.length; // 0 col.empty(); // true —— length 0 col.nonempty(); // false取元素src/collection/iteration.mjscol.eq(0); // 第 0 个元素越界时返回空集合而非 undefined col.first(); // 首个元素 col.last(); // 末个元素判断元素归属src/collection/comparators.mjscollection.contains(node); // 是否包含指定节点等价于 has collection.same(other); // 与另一集合的元素是否完全相同 collection.anySame(other); // 是否有交集其中same的实现包含三重优化先比较集合引用再比较长度最后对单元素集合比较元素引用全部通过后再逐个按 id 查 mapsrc/collection/comparators.mjs。集合运算全景union 家族的兄弟方法union并非孤立存在。在 src/collection/filter.mjs 的别名区可以看到完整的集合运算家族它们共同构成了构建集合的代数工具fn[ u ] fn[ | ] fn[ ] fn.union fn.or fn.add; // 并集 fn[ \\ ] fn[ ! ] fn[ - ] fn.difference fn.relativeComplement fn.subtract fn.not; // 差集 fn[ n ] fn[ ] fn[ . ] fn.and fn.intersection fn.intersect; // 交集 fn[ ^ ] fn[ () ] fn[ (-) ] fn.symmetricDifference fn.symdiff fn.xor; // 对称差集官方文档 documentation/md/core/batch.md 也将集合构建列为批处理场景的典型用法Building collections:eles.union(),eles.difference(),eles.intersection(), etc.。在实际项目中可以组合这些运算完成复杂筛选例如保存所有被点击的节点但排除其中已标记为隐藏的节点var clicked cy.collection(); cy.nodes().on(click, function(e){ var clickedNode e.target; // 并集累积 差集剔除指定 id clicked clicked.union(clickedNode).difference(cy.$(#node-to-exclude)); });测试用例对行为的验证仓库测试文件 test/collection-building-and-filtering.mjs 对空集合与merge行为给出了明确的断言可作为理解cy.collection()行为的佐证空集合test/collection-building-and-filtering.mjscy.collection()初始length 0、eles[0]不存在hasElementWithId(n1)返回false就地合并eles.merge( n1 )后length变为 1重复合并已存在的元素不会增加长度因为按 id 去重空交集test/collection-building-and-filtering.mjscy.$(#n1, #n2).intersect( cy.collection() ).empty()为true验证了空集合参与运算时符合集合代数预期。这些断言与 src/collection/index.mjs 中hasElementWithId、merge的实现一一对应说明本文所述行为均有可重复验证的测试保障。总结与注意事项cy.collection()是构建、累积集合的入口无参调用得到空集合传选择器、元素/集合、JSON 数组时行为各不相同见 src/core/search.mjs。传入 JSON 数组时opts.removed: true可创建不加入图、处于 removed 状态的元素集合省略该选项则元素创建后自动restore()入图src/collection/index.mjs。opts.unique: true按 id 去重id 缺省时自动生成与图中已有 id 冲突的条目会被忽略。累积节点等动态集合场景优先组合union/intersection/difference等别名丰富的集合运算对性能敏感、希望避免创建中间对象时可使用就地修改的merge/unmerge。集合与元素共享原型方法src/collection/index.mjsforEach、map、filter等迭代能力开箱即用且forEach的回调参数顺序为( ele, i, eles )。将cy.collection()与集合运算配合使用可以构建出从点击选点到临时元素管理再到实例间元素迁移的完整数据流是掌握 cytoscape.js 元素管理的基石 API。赞分享数据可视化【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址https://gitcode.com/gh_mirrors/cy/cytoscape.js点击查看免费下载相关推荐cytoscape.js 集合动画停止指南深入解析 eles.stop() 的参数、执行原理与实战用法cytoscape.js 集合动画停止指南深入解析 eles.stop 的参数、执行原理与实战用法 导读 在 cytoscape.js 中动画是交互与可视化数据可视化cytoscape.js 集合运算详解eles.symmetricDifference对称差的用法与实现原理cytoscape.js 集合运算详解eles.symmetricDifference对称差的用法与实现原理 导读 本文围绕 cytoscape.js 元数据可视化Cytoscape.js 集合全量匹配 allAre() 方法深度指南语法、实现原理与实战验证Cytoscape.js 集合全量匹配 allAre 方法深度指南语法、实现原理与实战验证 导读 eles.allAre 是 Cytoscape.js 集合数据可视化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
