cytoscape.js 集合操作详解：eles.union() 合并元素集合的用法与底层实现

cytoscape.js 集合操作详解eles.union() 合并元素集合的用法与底层实现【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址: https://gitcode.com/gh_mirrors/cy/cytoscape.js本篇技术指南聚焦 cytoscape.js 中eles.union()这一集合构建 API讲解如何将两个元素集合Collection合并为一个去重的新集合以及如何直接传入选择器Selector完成集合合并。你将掌握union()及其全部别名u、add、or、|、的实战用法并了解它与intersection()、difference()、symmetricDifference()等兄弟 API 的区别最后通过源码src/collection/filter.mjs与单元测试test/collection-building-and-filtering.mjs理解其内部实现与去重原理。一、union() 是什么union()是 cytoscape.js 元素集合的并集运算它返回一个新的集合其中包含调用它的集合与传入集合中的所有元素重复元素只会出现一次自动去重。原集合不会被修改。在 cytoscape.js 中集合的构建与过滤是日常操作的核心能力union()属于该能力组中的成员官方文档统称其为building filtering构建与过滤操作。在 index.d.ts 的类型定义中它的完整签名如下type CollectionBuildingUnionFunc ( eles: CollectionArgument | CollectionArgument[] | Selector, ) CollectionReturnValue;可见union()接受三种参数形态参数类型说明CollectionArgument另一个元素集合Collection或单个元素/元素数组CollectionArgument[]元素数组Selector选择器字符串匹配当前图中符合条件的元素作为合并来源返回值CollectionReturnValue是新的集合不会影响调用方与传入集合。二、基础用法官方示例详解根据 documentation/md/collection/union.md 的示例union()有两种典型调用方式。2.1 与另一个集合合并var j cy.$(#j); var e cy.$(#e); j.union(e);这里cy.$(#j)与cy.$(#e)分别通过 ID 选择器取出图中的两个元素可以是节点也可以是边j.union(e)返回同时包含#j与#e的新集合。2.2 直接传入选择器cy.$(#j).union(#e);无需先单独获取元素union()内部会把选择器#e解析为当前图中匹配的元素集合再与调用方的集合做并集。这适合链式调用场景代码更简洁。2.3 与merge()的区别从语义上看union()与merge()原地合并容易混淆需要注意区别union()底层即add()返回新集合调用方集合保持不变merge()原地修改调用方集合把新元素追加进去返回调用方自身以支持链式调用。两者底层都通过元素 ID 映射进行去重判断但前者是纯函数式操作后者是原地操作。三、别名体系u / add / or / | / union()在源码层拥有一套完整的别名映射。见 src/collection/filter.mjs 中的注册逻辑let fn elesfn; fn[ u ] fn[ | ] fn[ ] fn.union fn.or fn.add;也就是说以下写法完全等价j.union(e); j.u(e); // 单字母缩写 j.add(e); // add 是 add 语义行为与 union 相同 j.or(e); // 逻辑或语义 j|; // 数学集合符号 j; // 加法语义在 index.d.ts 的接口定义中同样可以看到这些别名被完整声明union: CollectionBuildingUnionFunc; u: CollectionBuildingUnionFunc; add: CollectionBuildingUnionFunc; : CollectionBuildingUnionFunc; or: CollectionBuildingUnionFunc; |: CollectionBuildingUnionFunc;从源码结构看union的真正实现落在add()函数上。阅读 src/collection/filter.mjs 中add()的实现可以清晰看到去重逻辑add: function( toAdd ){ let cy this._private.cy; if( !toAdd ){ return this; } if( is.string( toAdd ) ){ let selector toAdd; toAdd cy.mutableElements().filter( selector ); } let elements this.spawnSelf(); for( let i 0; i toAdd.length; i ){ let ele toAdd[i]; let add !this.has(ele); if( add ){ elements.push(ele); } } return elements; }关键点有三个空参数短路未传参数时直接返回调用方集合选择器归一化传入字符串选择器时先用cy.mutableElements().filter(selector)将选择器解析为实际元素集合因此与选择器合并与与集合合并最终走同一逻辑去重保障用this.has(ele)判断元素是否已在结果中已存在的元素不再重复追加从而保证并集结果中每个元素只出现一次。四、与相邻集合运算 API 的对比union()不是孤立的cytoscape.js 在同一个能力组中提供了完整的集合代数运算。在 src/collection/filter.mjs 末尾可以看到一整套别名注册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; fn.complement fn.abscomp fn.absoluteComplement;对应的 API 一览API别名数学含义行为union()u、add、or、|、A ∪ B两集合的所有元素去重intersection()intersect、and、n、、.A ∩ B同时存在于两集合的元素difference()subtract、not、relativeComplement、\、!、-A − B调用方集合中不在另一集合中的元素symmetricDifference()symdiff、xor、^、()、(-)A △ B只在其中一个集合出现的元素absoluteComplement()abscomp、complement∁A全图中不在调用方集合中的元素它们的官方示例文档分别位于 documentation/md/collection/intersection.md、documentation/md/collection/absoluteComplement.md 及同目录下的difference.md、symmetricDifference.md。例如intersection()的典型场景是求两个节点邻居的交集var jNhd cy.$(#j).neighborhood(); var eNhd cy.$(#e).neighborhood(); jNhd.intersection( eNhd ); // 同时与 #j、#e 相邻的节点而union()的对应场景则是合并两组邻居得到所有相邻节点的并集var jNhd cy.$(#j).neighborhood(); var eNhd cy.$(#e).neighborhood(); jNhd.union( eNhd ); // 所有与 #j 或 #e 相邻的节点从实现细节看intersection()在传入选择器时是过滤语义直接this.filter(selector)而传入集合时遍历较短的集合配合has()判断以提升性能union()/add()则始终以调用方集合为基础追加去重。理解这些差异有助于在具体场景中选择最合适的 API。五、单元测试验证仓库的单元测试 test/collection-building-and-filtering.mjs 直接覆盖了union()的底层实现add()it(eles.add(), function(){ expect( n1.add(n2).length ).to.equal(2); expect( n1.add(n2).same( cy.$(#n1, #n2) ) ).to.be.true; });测试断言了add()即union()的两个关键性质n1.add(n2).length等于 2说明两个不同元素合并后产生包含两个元素的新集合n1.add(n2).same( cy.$(#n1, #n2) )为真说明合并结果与直接通过选择器#n1, #n2选出的集合同一same()判断两个集合是否包含完全相同的元素与顺序无关验证了去重与完整性。同文件中还有not()、intersect()、merge()等相邻运算的测试可一并作为阅读参考。六、实战建议与注意事项去重语义union()天然去重即使传入集合与调用方有大量重叠元素结果中每个元素也只会出现一次无需手动unique()不修改原集合union()返回新集合适合函数式链式调用若希望原地累积元素例如在循环中动态收集可改用merge()选择器与集合可混用两个参数形式的行为完全一致优先选择可读性更好的写法当选择器较复杂如node[weight 50], edge.special时直接传选择器通常更直观TypeScript 支持union()及其全部别名在 index.d.ts 中都有完整类型声明配合CollectionArgument | CollectionArgument[] | Selector联合类型参数可在 IDE 中获得完整的类型提示与校验性能底层去重基于集合内部维护的 ID 映射merge()中可见map.has(id)的用法按元素 ID 判断重复整体为线性开销适用于较大规模的图数据操作。【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址: https://gitcode.com/gh_mirrors/cy/cytoscape.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考