Cytoscape.js 核心 API 详解：使用 `cy.add()` 向图中动态添加节点与边

Cytoscape.js 核心 API 详解使用cy.add()向图中动态添加节点与边【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址: https://gitcode.com/gh_mirrors/cy/cytoscape.js本文围绕 Cytoscape.js 核心 API 中的cy.add()展开讲解如何以普通对象plain object或已有元素集合两种方式向图实例动态添加节点与边并深入解析元素 JSON 格式、group 自动推断、ID 校验、实例间元素转移等底层实现细节。读完本文你将掌握在运行时增补图元素的完整实战方案并理解其在源码src/core/add-remove.mjs中的真实处理逻辑。cy.add()是什么cy.add()是 Cytoscape.js 核心core提供的图操作 API用于向当前图实例中动态添加新的节点或边。它与初始化时通过elements选项一次性载入图数据的静态方式互补是构建交互式应用如用户手工建图、数据增量加载、图编辑工具时最常用的入口之一。从源码看cy.add()定义于 src/core/add-remove.mjs其返回值是包含所有成功添加元素的集合collection因此可以链式调用集合方法例如cy.add([ /* 元素 JSON */ ]).style(background-color, #f00);从普通对象添加元素与初始化完全一致的 JSON 格式cy.add()最典型的用法是传入普通对象。官方文档明确要求如果使用普通元素对象必须遵循初始化时使用的相同格式即 core/init.md 中elements选项的元素 JSON 规范完整格式可参考 notation.md 的 Elements JSON 一节。添加单个节点普通对象cy.add({ group: nodes, data: { weight: 75 }, position: { x: 200, y: 200 } });一次添加多个节点与边普通对象数组// can use reference to eles later var eles cy.add([ { group: nodes, data: { id: n0 }, position: { x: 100, y: 100 } }, { group: nodes, data: { id: n1 }, position: { x: 200, y: 200 } }, { group: edges, data: { id: e0, source: n0, target: n1 } } ]);上面的eles变量保存了返回的集合引用之后可以直接用它进行样式调整、选中、事件绑定等后续操作。元素 JSON 的关键字段每个元素对象可包含以下字段group与data.id为最核心部分字段类型说明groupnodes/edges元素类型可省略由源码自动推断见下文data对象元素数据id必填可省略源码会自动生成 UUID边的source/target必填指向源/目标节点 idposition{ x, y }节点的模型坐标省略时默认为(0, 0)renderedPosition{ x, y }以渲染像素指定位置源码会按(rpos - pan) / zoom换算成模型坐标classes数组或空格分隔字符串元素拥有的 class 名selected/selectable/locked/grabbable/pannable布尔交互状态均有默认值scratch对象存放临时、不可序列化的应用数据style/css对象样式覆盖bypass官方强烈建议仅在绝对必要时使用group 的自动推断元素构造器 src/collection/element.mjs 中实现了 group 自动推断逻辑当group未指定时若data.source与data.target均已定义则推断为边edges否则推断为节点nodes。测试用例 test/core-graph-manipulation.mjs 验证了仅给data: { id: new-edge, source: n1, target: n2 }即可自动创建边的行为cy.add({ data: { id: new-edge, source: n1, target: n2 } }); // 自动推断为边尽管可以省略group文档仍建议显式指定以便初始化出错时获得更清晰的调试信息。按 group 分组传入的便捷形式除平铺数组外cy.add()还支持按nodes/edges分组的对象形式源码 src/core/add-remove.mjs 会为每个元素自动补上group字段cy.add({ nodes: [ { data: { id: a } }, { data: { id: b } } ], edges: [ { data: { id: ab, source: a, target: b } } ] });ID 与边的合法性校验cy.add()在内部创建元素并执行restore()加入图元素池时会进行一系列校验全部实现在 src/collection/index.mjsID 自动生成data.id省略时自动生成 UUID数字 id 会被强制转换为字符串。ID 唯一性若图中已存在相同 id 的元素该元素将被跳过并打印错误Can not create second element with ID ...。边端点校验边的source/target缺失、为空或指向不存在的节点时该边会被拒绝并输出错误信息校验通过后边会建立与源/目标节点的双向引用_private.edges。位置兜底节点position缺失时自动补(0, 0)。相应的自动化测试覆盖于 test/core-graph-manipulation.mjs例如通过单个对象添加节点推断节点/边通过数组添加节点与边通过集合添加已移除元素等场景。添加已有元素集合实例内恢复与实例间复制cy.add()的第二个重要能力是接收已存在的元素或集合作为参数此时行为取决于这些元素属于哪个核心实例源码 src/core/add-remove.mjs同一实例直接调用eles.restore()将元素重新放入图池。典型场景是把通过cy.$(edge).remove()移除的边重新加回来对应测试见 test/core-graph-manipulation.mjs。不同实例通过ele.json()序列化每个元素再在新实例中重建从而实现元素在多个 Cytoscape.js 实例之间的有效迁移复制。例如将实例cy1中的全部元素复制到cy2var cy1 cytoscape({ container: document.getElementById(cy1), elements: [ /* ... */ ] }); var cy2 cytoscape({ container: document.getElementById(cy2) }); cy2.add( cy1.elements() ); // 不同实例 → 复制元素到 cy2需要说明的是cy.add(collection)中传入的 JSON 是通过 src/collection/index.mjs 的eles.json()导出的完整元素描述含 data、position、group、selected、locked、classes 等状态因此复制到新实例后这些属性会一并保留。从源码看cy.add()的完整执行链路综合 src/core/add-remove.mjs 与 src/collection/index.mjs一次cy.add(json)的内部流程可归纳为入参分流cy.add()依次判断参数是元素/集合is.elementOrCollection、数组、带nodes/edges的普通对象还是单个普通对象从而确定构造方式。构造元素由 src/collection/element.mjs 的Element构造器完成 group 推断、位置初始化、class 解析与样式 bypass 处理。批量 restore从 JSON 构造集合时一次性调用restore()依次完成 ID 规范化与唯一性校验、边端点校验、节点先于边的池化、复合节点父子关系建立、遍历缓存失效与样式更新最终触发add事件渲染器感知更新。这一链路保证了cy.add()与初始化载入在语义上完全一致也解释了为何文档强调普通对象必须遵循初始化格式。与相关 API 的组合使用cy.remove(eles)接受集合或选择器返回被移除元素的集合被移除元素可再次通过cy.add(eles)恢复到图中。eles.json()/eles.jsons()将元素导出为 JSON是实例间复制见上文以及cy.add()传参的底层数据来源。cy.elements()/cy.nodes()/cy.edges()获取当前图中的全部元素集合常与cy.add()配合做批量迁移。cy.batch()当需要大量添加元素且关心渲染性能时可将多次添加放入批处理中减少重复的样式计算与渲染通知。小结cy.add()是 Cytoscape.js 动态图操作的核心入口它既支持以初始化同款 JSON 格式批量添加节点与边也支持在同一实例内恢复已移除元素、在实例之间复制迁移元素。理解其背后的 group 推断、ID/端点校验与 restore 机制可以帮助你在构建图编辑、增量可视化等应用时写出更稳健的代码。【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址: https://gitcode.com/gh_mirrors/cy/cytoscape.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考