Cytoscape.js 布局（Layout）体系详解：从内置算法到自定义扩展

Cytoscape.js 布局Layout体系详解从内置算法到自定义扩展【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址: https://gitcode.com/gh_mirrors/cy/cytoscape.js布局Layout是 Cytoscape.js 中负责为图中每个节点计算坐标的核心机制它决定了一幅图最终呈现的形态、节点的疏密以及边连线的长度。本指南以官方布局文档为主线结合本仓库的源码实现系统讲解布局的扩展机制、内置布局、选项体系、子图运行方式、无头实例下的边界约束以及布局生命周期事件帮助你掌握选对布局、调好参数、跑对子图的完整实战能力。一、布局的职责为图中的节点计算位置Cytoscape.js 官方文档documentation/md/layout/intro.md开门见山布局的功能是为图中的节点设置坐标。它不负责渲染样式、不负责交互只回答一个问题——这个节点应该放在哪里。这一点决定了布局 API 的形态你传给它的是一组元素节点 边它返回的是每个节点的新位置。从源码看这一步最终落在 src/collection/layout.mjs 的layoutPositions()上它负责把某个位置计算函数的结果批量应用到节点上并统一处理动画、缩放fit、平移pan以及layoutstart/layoutready/layoutstop等事件的触发。也就是说所有内置布局共用一个落地管线彼此不同的只是位置怎么算。二、布局是扩展不修改库本身也能新增布局文档明确指出布局是 Cytoscape.js 的扩展extension因此任何人都可以编写一个布局而无需修改库本身。这一设计在源码中有完整印证。布局扩展的注册与包装逻辑位于 src/extension.mjs当你通过cytoscape.use()注册一个布局时框架会将其包装成统一的Layout构造器自动补齐_private内部状态与事件监听器存储run()与start()的互相生成定义其一即可另一方会自动补齐统一的stop()若开启animate会先停止所有动画再触发layoutstop基于 Emitter 的on/one/once/emit/removeListener等事件接口且布局事件会冒泡到核心Core实例bubble: true父对象为cy。内置布局的注册表在 src/extensions/layout/index.mjsCytoscape.js 默认内置了 8 种布局布局名算法思想选项文档breadthfirst广度优先分层布局breadthfirst.mdcircle圆形排列circle.mdconcentric同心圆排列concentric.mdcose力导向物理模拟支持复合节点cose.mdgrid等间距网格排列grid.mdnull不改变节点位置null.mdpreset使用手动指定的位置preset.mdrandom视口内随机位置random.md扩展生态中还存在cose-bilkent、fcose、dagre、elk等由社区维护的布局扩展本仓库 documentation/demos 下有对应示例它们通过cytoscape.use()注册后即可与内置布局一样通过name使用。三、选择布局options.name与两个布局工厂函数文档特别强调必须通过options.name指定要运行的布局。查看 src/core/layout.mjs 的cy.layout()实现可以确认这一校验是硬性的options为空时直接报错Layout options must be specified to make a layoutoptions.name缺失时报错A \name must be specified to make a layout通过cy.extension(layout, name)查找注册的布局找不到时报错No such layout ... Did you forget to import it and cytoscape.use() it?。最基础的用法const layout cy.layout({ name: random }); layout.run();与cy.layout()等价的是cy.makeLayout()与cy.createLayout()源码中三个名字互为别名见 src/core/layout.mjs。它们返回一个布局实例你可以调用run()/start()/stop()也可以在上面挂事件监听。另外在初始化initialisation时也可以通过layout选项直接指定初始布局与传入cy.layout()的是同一套选项对象const cy cytoscape({ container: document.getElementById(cy), elements: [ /* 节点与边数据 */ ], layout: { name: cose, animate: true, fit: true, padding: 30 } });四、布局算法与边长控制文档指出每种布局都有自己的节点定位算法算法决定了图的整体形态与边的长度算法的行为可以通过选项定制因此边长可以由布局选项控制。这一节的实操要点如下力导向物理模拟布局如cose一般提供edge weight边权重选项权重越大边两端节点越倾向于靠拢从而影响相对边长边长还会受spacingFactor间距因子、angle角度等选项以及重叠规避overlap avoidance逻辑影响不同布局对边长的控制精度不同——例如grid、circle这类确定性几何布局边长由排列方式间接决定而cose这类物理布局则通过力学模型逼近目标边长。从源码看spacingFactor与transform两个通用选项在 src/collection/layout.mjs 有统一的实现spacingFactor会以节点包围盒bounding box中心为基准把每个位置按因子向中心缩放transform则是形如(node, position) position的转换函数常用于调整离散布局的流动方向例如把分层布局从横向改为纵向。这两个选项适用于所有经由layoutPositions()落地的布局属于跨布局的通用控制手段。五、在子图上运行cy.layout()与eles.layout()的差异文档明确区分了两个入口的作用范围cy.layout()作用于图中的全部元素eles.layout()作用于你指定的元素子集。这一区别在源码中非常清晰。cy.layout()在解析元素时若传入options.eles为字符串则按选择器cy.$(options.eles)查询否则取options.eles或默认的全集cy.$()见 src/core/layout.mjs而eles.layout()则直接把调用集合作为eles传给cy.makeLayout()见 src/collection/layout.mjs。还有一个容易被忽视的要点元素自身的状态不影响其是否参与布局。文档以不可见节点为例——只要节点在布局的元素集合内即使它是不可见的visibility: hidden或display: none相关样式布局依然会为其重新计算位置。也就是说布局只关心集合里有没有它不关心它现在长什么样。这与 style 文档 中的可见性控制是正交的两件事。eles.layout()的价值在于处理复杂场景最典型的是为每个连通分量分别运行不同的布局// 为每个连通分量运行不同的布局 eles.components().forEach((comp, i) { comp.layout({ name: i % 2 0 ? circle : grid, animate: true }).run(); });六、无头headless实例与boundingBox文档特别提醒运行无头实例headless时可能需要显式指定boundingBox告诉布局它可以把节点放在哪个区域而在有渲染rendered实例中边界通常可以从 HTML 容器元素的大小推断出来。boundingBox支持两种格式见 src/extensions/layout/random.mjs 的注释{ x1, y1, x2, y2 }绝对坐标形式{ x1, y1, w, h }起点 宽高形式。以random布局为例它的默认边界就是整个视口x1: 0, y1: 0, w: cy.width(), h: cy.height()节点在边界内随机取整坐标见 src/extensions/layout/random.mjs。在无头环境下没有 DOM 容器可推断边界因此必须靠boundingBox显式约束否则布局可能退回到默认的全零或视口尺寸假设导致节点位置不可预期。另一个与尺寸相关的通用选项是nodeDimensionsIncludeLabels默认false它为 true 时布局会把节点标签尺寸计入节点宽高适用于需要严格按含标签尺寸排布的场景实现见 src/collection/layout.mjs。该实现还会把宽高为 0 的节点尺寸规整为 1避免外部布局出现除零错误。七、布局生命周期layoutstart/layoutready/layoutstop布局是有生命周期的。相关细节记录在 documentation/md/layout/run.md与源码行为完全对应异步continuous布局layout.run()只是启动布局计算在后台持续进行同步discrete布局则在run()返回前就完成计算布局启动时触发layoutstart事件布局完成或被停止例如调用layout.stop()时触发layoutstop事件。以random这类离散布局为例run()内部调用eles.nodes().layoutPositions(...)后立即同步返回layoutPositions()会在计算前先发出layoutstart随后按顺序发出layoutready与layoutstop见 src/collection/layout.mjs。而开启animate: true时layoutstop会等待所有节点动画与fit动画的Promise全部完成后才触发。监听布局事件有三种方式官方推荐优先用回调选项// 方式一options 回调推荐 cy.layout({ name: grid, ready: () { /* 布局就绪 */ }, stop: () { /* 布局完成或停止 */ } }).run(); // 方式二实例事件监听 const layout cy.layout({ name: circle }); layout.on(layoutstart, () console.log(start)); layout.on(layoutstop, () console.log(stop)); layout.run(); // 方式三手动停止 layout.stop();由于布局实例本身就是 Emitter它还支持on/one/once/emit/removeListener/promiseOn等完整事件接口对应 documentation/md/layout/on.md、one.md、emit.md、promiseOn.md、removeListener.md。此外如 documentation/md/layout/manipulation.md 所述布局对象提供了一组可用于编程控制的函数使其能够支持比一次性运行更复杂的行为例如暂停、恢复、复用同一个布局实例而不仅仅是运行一次就丢弃。八、内置布局速览每个内置布局都有独立的选项文档均以默认值标注了每个选项。这里给出速览供快速选型random在视口或boundingBox内随机放置节点适合快速预览与调试见 random.mdgrid把节点排列为间距均匀的网格适合规整的小型图见 grid.mdpreset按你手动指定的位置放置节点适合复用已有坐标数据见 preset.mdcircle/concentric圆形与同心圆排列适合中心辐射型拓扑breadthfirst按广度优先的层级关系排列适合树状与层级结构coseCompound Spring Embedder基于物理模拟的力导向布局对复合节点compound node图有专门支持计算速度快且效果良好见 cose.mdcose-bilkent等社区扩展是其算法的演进版本代价是计算开销更大null不移动任何节点适合只想保留原始坐标的场景。九、继续深入相关文档与源码索引布局通用说明documentation/md/layout/intro.md布局运行与生命周期documentation/md/layout/run.md、stop.md、manipulation.md各内置布局选项documentation/md/layouts 目录下的 8 个选项文档布局工厂实现src/core/layout.mjs、src/collection/layout.mjs扩展注册机制src/extension.mjs内置布局注册表src/extensions/layout/index.mjs位置落地与通用选项实现src/collection/layout.mjs布局实例代码样例src/extensions/layout/random.mjs掌握name必填、子集可控、边界可约束、事件可监听这四个要点你就能在任何 Cytoscape.js 项目中自如地选用、组合与定制布局让图以期望的形态呈现。【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址: https://gitcode.com/gh_mirrors/cy/cytoscape.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考