使用 cy.autolock() 全局锁定 Cytoscape.js 节点API 用法、底层实现与实战指南【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址: https://gitcode.com/gh_mirrors/cy/cytoscape.js本文围绕 Cytoscape.js 核心 API 中的cy.autolock()展开讲解如何通过一行调用把画布中所有节点统一置于“锁定”状态禁止拖拽、禁止移动、布局时保持原位并深入源码剖析其查询时覆盖override机制与逐节点lock()/unlock()的区别。读完本文你将掌握 autolock 的读写用法、初始化配置方式、TypeScript 类型签名以及它在拖拽、位置设置、布局与动画中的真实影响范围可直接应用于图谱可视化中的只读展示、演示锁定和交互约束场景。一、autolock 是什么autolock是 Cytoscape.js 在核心core层面提供的全局开关当它为true时所有节点都被视为已锁定无论这些节点各自的锁定状态如何。它相当于一个“一键锁全图”的开关常用于将图谱切换为只读展示模式禁止用户拖动节点在布局或动画执行前固定所有节点位置结合用户交互事件如按钮、菜单动态切换画布的可编辑性。官方文档documentation/md/core/autolock.md给出的用法极为简洁——启用与禁用各一行代码// 启用所有节点自动锁定 cy.autolock( true ); // 禁用恢复节点各自的锁定状态 cy.autolock( false );下文将围绕这两个调用展开结合仓库源码说明其背后的完整行为。二、API 用法详解1. Setter 与 Getter 双模式从源码src/core/viewport.mjs可以看到autolock是一个典型的 getter/setter 双模式方法autolock: function( bool ){ if( bool ! undefined ){ this._private.autolock bool ? true : false; } else { return this._private.autolock; } return this; // chaining },传入参数bool ! undefined时为 setter内部将任意真值归一化为true、假值归一化为false存入this._private.autolock并返回this支持链式调用不传参数时为 getter直接返回当前开关值布尔类型。因此以下写法都是合法的// 启用 cy.autolock( true ); // 禁用假值同样生效 cy.autolock( false ); cy.autolock( 0 ); // 读取当前状态 const isAutolocked cy.autolock(); // true / false // 链式调用 cy.autolock( true ).center().fit();2. 默认值为 false初始化时该开关默认关闭。在src/core/index.mjs中可以看到默认值解析逻辑autolock: defVal( false, options.autolock, options.autolockNodes ),其中defVal在未显式提供时返回第一个参数false即默认不启用全局锁定。3. TypeScript 类型签名仓库自带类型声明index.d.ts给出了完整的 TS 签名可帮助类型安全的调用autolock(): boolean; // getter获取是否自动锁定 autolock(bool?: boolean): this; // setter设置后返回实例本身同时初始化选项在index.d.ts中声明为autolock?: boolean默认值为false。三、初始化时配置 autolock除了在运行时调用方法也可以在创建实例时通过初始化选项直接开启const cy cytoscape({ container: document.getElementById(cy), // 创建后所有节点即为锁定状态 autolock: true, elements: [ { data: { id: a } }, { data: { id: b } }, { data: { id: ab, source: a, target: b } } ] });从src/core/index.mjs的源码可见初始化选项同时兼容新旧两种写法options.autolock与options.autolockNodes。其中autolockNodes是历史遗留的向后兼容别名——在src/core/viewport.mjs末尾有明确的别名注册// backwards compatibility corefn.autolockNodes corefn.autolock;新代码建议统一使用autolockautolockNodes仅用于兼容旧版本迁移场景。四、底层实现原理查询时覆盖override机制要理解cy.autolock(true)的真实效果关键在于它并不会遍历并修改每个节点内部存储的locked字段而是采用“查询时覆盖”策略。1. 逐节点锁定的开关定义在src/collection/switch-functions.mjs中节点的locked状态通过defineSwitchSet定义defineSwitchSet( { field: locked, overrideField: function( ele ){ return ele.cy().autolock() ? true : undefined; }, on: lock, off: unlock } );这段代码揭示了两个关键点每个节点真正存储的字段是ele._private.lockedoverrideField钩子会在每次读取ele.locked()时先被调用如果cy.autolock()返回真值则直接返回true此时无论节点内部的_private.locked是什么值ele.locked()都报告为已锁定当autolock关闭时返回undefined此时回退到节点自身的_private.locked个体状态。2. 与逐节点 lock() / unlock() 的关系对应的逐节点方法同样由该文件生成官方文档示例见documentation/md/collection/lock.md与documentation/md/collection/unlock.mdcy.$(#j).lock(); // 仅锁定单个节点 j cy.$(#j).unlock(); // 解锁单个节点 j两者的区别非常重要cy.autolock(true)是全局开关只翻转标志位不触发任何lock事件也不改变各节点_private.locked的存量值ele.lock()/ele.unlock()是个体操作会修改节点状态并派发lock/unlock事件影响样式更新当autolock开启时由于 override 优先级更高对单个节点调用unlock()表面上不会产生任何可见效果——ele.locked()依然返回true反过来autolock只会强制“锁定”无法解除某个已被个体锁定的节点override 只返回true或undefined永远不会返回false。可以推断autolock 更适合做全局级“总闸”而逐节点 lock/unlock 用于精细的个体控制二者组合时以 autolock 的锁定覆盖为准。五、autolock 开启后的实际影响范围ele.locked()为真时Cytoscape.js 的渲染器与各核心模块会同步禁止与该节点相关的位移操作。以下是源码中可验证的影响点1. 禁止用户拖拽渲染器的拖拽判定直接检查锁定状态见src/extensions/renderer/base/load-listeners.mjsBRp.nodeIsDraggable function( node ){ return ( node node.isNode() !node.locked() node.grabbable() ); };开启 autolock 后所有节点locked()恒为真因此nodeIsDraggable恒为false用户无法用鼠标拖动任何节点。这正是把 autolock 用于“只读演示模式”的直接依据。2. 禁止通过 API 移动位置src/collection/dimensions/position.mjs中的beforePositionSet与canSet检查同样以锁定为准canSet: function( ele ){ return !ele.locked(); }这意味着在 autolock 开启时调用node.position({ x, y })或node.positions()批量设置位置都会被静默跳过。3. 布局算法跳过锁定节点多个内置布局都会尊重锁定状态grid 布局src/extensions/layout/grid.mjs对locked()为真的节点直接返回false不为其计算新位置preset 布局src/extensions/layout/preset.mjs同样跳过锁定节点使“重新执行 preset 布局”不会打乱手动摆放的位置cose 布局src/extensions/layout/cose.mjs将n.locked()的结果存入临时节点的isLocked字段在力导向迭代中把锁定节点当作固定锚点处理。因此在 autolock 开启状态下运行cy.layout()节点会保持在原有位置仅其余可动节点参与布局计算。4. 动画跳过位置插值src/core/animation/step.mjs中位置型动画的每一帧都会检查锁定if( endPos isEles !self.locked() ){ // 计算并写入新位置 }即node.animate({ position: { x, y } })这类位置动画在 autolock 开启时不会生效但其他样式属性如颜色、尺寸动画不受影响。5. 选择器支持 :locked / :unlockedsrc/selector/state.mjs定义了基于锁定状态的状态选择器{ selector: :locked, matches: function( ele ){ return ele.locked(); } }, { selector: :unlocked, matches: function( ele ){ return !ele.locked(); } }由于ele.locked()会反映 autolock 的覆盖结果开启 autolock 后cy.nodes(:locked)会命中全部节点而cy.nodes(:unlocked)将为空集——可以借此在代码中判断全局锁定是否生效。六、通过 cy.json() 批量读写autolock 也属于cy.json()可读写的“视图配置字段”之一。在src/core/index.mjs中它被列在批量配置字段清单内let fields [ minZoom, maxZoom, zoomingEnabled, userZoomingEnabled, panningEnabled, userPanningEnabled, boxSelectionEnabled, autolock, autoungrabify, autounselectify, multiClickDebounceTime ];因此你可以一次性读写多个视图配置// 读取当前全部配置含 autolock const cfg cy.json(); console.log( cfg.autolock ); // 批量配置同时启用全局锁定与全局禁止抓取 cy.json({ autolock: true, autoungrabify: true });这在保存/恢复画布视图配置如 localStorage 持久化或场景快照时非常实用。七、完整实战示例下面是一个把 autolock 与按钮交互结合的可运行示例骨架import cytoscape from cytoscape; const cy cytoscape({ container: document.getElementById(cy), elements: [ { data: { id: n1 } }, { data: { id: n2 } }, { data: { id: e1, source: n1, target: n2 } } ], style: [ { selector: node, style: { background-color: #6fb1fc } } ] }); // 切换到只读模式锁定所有节点 document.getElementById(lockAll).addEventListener(click, () { cy.autolock( true ); // 开启后所有节点均被覆盖为锁定 console.log( cy.nodes(:locked).length ); // 2 }); // 切换回可编辑模式 document.getElementById(unlockAll).addEventListener(click, () { cy.autolock( false ); console.log( cy.autolock() ); // false }); // 读取状态并配合 UI 切换 document.getElementById(toggle).addEventListener(click, () { cy.autolock( !cy.autolock() ); });八、注意事项与最佳实践不产生事件cy.autolock(true)只翻转核心标志位不会逐节点派发lock/unlock事件也不会触发样式重算对比switch-functions.mjs中ele.lock()会调用updateStyle()并派发事件。如需监听锁定变化应自己监听该调用点。只锁不松autolock 只能将“未锁定”节点覆盖为锁定不能解除已个体锁定的节点要精细控制某个节点的可编辑性请配合ele.lock()/ele.unlock()。影响位置类操作开启后拖拽、position()/positions()、位置动画以及依赖位移的布局grid、preset、cose 等都会对全图节点失效但缩放、平移视口以及非位置类样式动画不受影响。新旧 API 命名options.autolockNodes与cy.autolockNodes()为兼容旧版的别名建议统一使用autolock。只读模式推荐组合实际项目中常将cy.autolock(true)与cy.autoungrabify(true)禁止抓取见index.d.ts、cy.autounselectify(true)组合使用构建完整的只读视图。相关资源索引API 文档documentation/md/core/autolock.md核心实现src/core/viewport.mjs含向后兼容别名src/core/viewport.mjs初始化默认值与cy.json()字段清单src/core/index.mjs、src/core/index.mjs覆盖式锁定机制src/collection/switch-functions.mjs类型声明index.d.ts逐节点锁定文档documentation/md/collection/lock.md、documentation/md/collection/unlock.md锁定相关的拖拽判定src/extensions/renderer/base/load-listeners.mjs位置限制src/collection/dimensions/position.mjs布局跳过src/extensions/layout/grid.mjs、src/extensions/layout/preset.mjs、src/extensions/layout/cose.mjs动画检查src/core/animation/step.mjs:locked/:unlocked选择器src/selector/state.mjs【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址: https://gitcode.com/gh_mirrors/cy/cytoscape.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考