cytoscape.js 元素 scratch 清理指南：深入理解 ele.removeScratch() 的命名空间语义与 undefined 约定

cytoscape.js 元素 scratch 清理指南深入理解 ele.removeScratch() 的命名空间语义与 undefined 约定【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址: https://gitcode.com/gh_mirrors/cy/cytoscape.jsele.removeScratch(namespace)是 cytoscape.js 提供给集合与元素对象以及 core 实例的临时数据清理方法。本文围绕官方文档 removeScratch.md 的核心说明展开调用ele.removeScratch()后指定命名空间下的 scratchpad 对象会被置为undefined从而允许你在应用逻辑中放心使用有意义的null值。读完本文你将掌握 scratch 命名空间机制、removeScratch与scratch/data的差异、它在扩展layout、renderer中的真实用法以及如何利用undefined约定做健壮的临时状态管理。文档核心要点removeScratch 置 undefined 而非删除官方文档 removeScratch.md 的全文只有一句关键说明却是理解整个 scratch 机制最重要的约定Note thatele.removeScratch()sets the scratchpad object for the specified namespace toundefined. This allows you to use meaningfulnullvalues.即ele.removeScratch(namespace)并不会物理删除delete命名空间下的 scratch 对象而是把该命名空间的值设置为undefined。这意味着调用后再次ele.scratch(namespace)会得到undefined可用于判断该命名空间从未初始化/已清理而如果你曾经存储过一个真正表示空/无值的null它会被保留并区别于undefined——这正是允许使用有意义的null值的含义清理操作保留命名空间本身不触发对象属性删除带来的不可预期行为。该约定与ele.data()的删除行为一致底层实现中removeData同样采用将键值置为undefined而非删除键的方式见 src/define/data.mjs。scratch 是什么临时、不可序列化的元素关联数据要真正用好removeScratch先要理解它操作的对象——scratchpad。官方文档 scratch.md 给出了明确的使用定位临时且可能非 JSON 的数据扩展layout、renderer 等以自己注册的名字作为命名空间调用ele.scratch()。例如名为foo的扩展会使用命名空间foo应用级数据用下划线前缀规避冲突如果你想在应用层使用 scratch可以给命名空间加下划线前缀如ele.scratch(_foo)避免与名为foo的扩展冲突不进 JSON 输出ele.data()存储的数据会被ele.json()包含而ele.scratch()存储的数据不会因此 scratch 适合存放不可序列化的对象如函数、DOM 引用、Canvas 句柄等而不污染导出结果。从源码看scratch 与 data 共享同一套访问器工厂只是字段不同见 src/collection/data.mjs// data 字段 data: define.data( { field: data, allowBinding: true, allowSetting: true, ... } ) removeData: define.removeData( { field: data, event: data, triggerEvent: true, ... } ) // scratch 字段 scratch: define.data( { field: scratch, bindingEvent: scratch, allowBinding: true, allowSetting: true, settingEvent: scratch, settingTriggersEvent: true, triggerFnName: trigger, allowGetting: true, updateStyle: true } ) removeScratch: define.removeData( { field: scratch, event: scratch, triggerFnName: trigger, triggerEvent: true, updateStyle: true } )从源码结构看removeScratch复用了通用工厂define.removeData见 src/define/data.mjs其参数化的差异点在于参数data 的 removeDatascratch 的 removeScratchfielddatascratcheventdatascratchtriggerEventtruetruetriggerFnNametriggertriggerimmutableKeysid/source/target/parent不可删除无scratch 键均可清理可以看出removeScratch与removeData的差异仅在于作用字段不同前者清理_private.scratch后者清理_private.data。而removeScratch与removeRscratch渲染内部 scratch的区别则更大——rscratch不触发事件且不允许绑定见 src/collection/data.mjs是 renderer 专用的高性能临时存储应用层一般只使用scratch。调用签名与返回行为ele.removeScratch(namespace)与 core 层的cy.removeScratch(namespace)签名一致TypeScript 类型定义中均有声明见 index.d.ts 与 index.d.tsremoveScratch(namespace: string): this;行为要点参数为命名空间字符串如foo、_myApp可传入以空格分隔的多个命名空间复用removeDataImpl的names.split(/\s/)逻辑见 src/define/data.mjs传undefined不传参时会清空该对象上所有scratch 键将它们全部置为undefined见 src/define/data.mjs空字符串键会被跳过返回self保持链式调用ele.removeScratch(foo).scratch(bar, x)合法清理成功后触发scratch事件triggerEvent: trueupdateStyle: true会触发样式重算因为部分样式映射可能依赖 scratch 中的值。var cy cytoscape({ container: document.getElementById(cy), elements: [ { data: { id: j } } ] }); var j cy.$(#j); // 1. 写入命名空间 j.scratch(_foo, { count: 1 }); // 2. 读取 j.scratch(_foo); // { count: 1 } // 3. 清理该命名空间 j.removeScratch(_foo); // 4. 清理后再读undefined而非 null j.scratch(_foo); // undefined // 5. 不传参清空所有 scratch j.removeScratch();为什么置为 undefined比删除键更好这一设计来自removeDataImpl的实现细节src/define/data.mjsall[ i_a ]._private[ p.field ][ key ] undefined;而不是delete all[ i_a ]._private[ p.field ][ key ]。带来的实际收益语义可区分undefined表示未初始化 / 已清理null表示显式存储的空值。二者在if (x)、if (x ! undefined)等判断中有不同的语义这允许应用代码用null表达真实业务空值而不与未设置混淆对象结构稳定不删除属性键避免后续遍历Object.keys()时键集合发生变动对依赖 scratch 键集合的渲染逻辑更安全避免原型链污染风险相比delete赋值undefined不会暴露原型链上可能存在的同名属性。从源码结构可以推断这一约定同时覆盖 core 与 collection 两层cy.removeScratch()见 src/core/data.mjs与ele.removeScratch()见 src/collection/data.mjs使用相同的工厂与语义只是作用对象从单个图实例变为元素集合。实战在扩展与布局中的典型用法cytoscape.js 内置的 breadthfirst 布局就以breadthfirst作为命名空间使用 scratch 保存布局中间状态见 src/extensions/layout/breadthfirst.mjsconst getInfo ele ele.scratch(breadthfirst); const setInfo (ele, obj) ele.scratch(breadthfirst, obj);布局在迭代过程中把节点的层级信息写入 scratch结束后依赖removeScratch或新的写入来清理/覆盖临时状态。这印证了官方文档的定位扩展以注册名为命名空间使用 scratch。应用层推荐写法结合下划线前缀防冲突// 初始化一个命名空间 var st j.scratch(_myLayoutState, { stage: running, tick: 0 }); // 更新状态 j.scratch(_myLayoutState, { stage: done, tick: 42 }); // 判断是否仍有状态undefined 语义的关键用法 if (j.scratch(_myLayoutState) ! undefined) { // 状态尚在 } else { // 已被 removeScratch 清理 } // 业务上确实需要空值时用 null j.scratch(_myLayoutState, null); // 清理并回到 undefined j.removeScratch(_myLayoutState);测试用例也验证了 scratch 数据在元素移动move()等操作后仍能保持见 test/collection-graph-manipulation.mjs说明 scratch 是随元素生命周期稳定保存的临时存储适合布局、拖拽、交互中间态等场景。常见误区与注意事项误以为 removeScratch 会删除键实际上键仍在只是值为undefined。如果你依赖Object.keys(ele._private.scratch)判断命名空间数量需要注意这一点误用 null 代替 undefined 判断清理状态removeScratch后读值是undefined如果你主动存过null读到的就是null。二者是不同的状态这是该 API 设计刻意保留的能力忘记命名空间直接ele.scratch()拿到整个 scratchpad 对象再写入容易覆盖其他扩展包括内置 renderer的命名空间。官方文档明确警告be careful, since you could clobber over someone elses namespace见 scratch.md始终使用带前缀的命名空间才是安全做法与 removeData / removeRscratch 混淆ele.removeData(key)清理data字段会被json()导出且id/source/target/parent是不可变键、无法删除见 src/collection/data.mjsele.removeRscratch()清理渲染内部 scratch不触发事件是 renderer 内部专用见 src/collection/data.mjs应用层不应直接操作core 与 collection 都有该方法cy.removeScratch()作用于整个图实例ele.removeScratch()作用于单个元素或集合集合上会遍历所有元素逐一置undefined。小结ele.removeScratch(namespace)表面只是一个清理方法其背后是 cytoscape.js 精心设计的临时数据语义写入用ele.scratch(namespace, value)命名空间建议加下划线前缀避免与扩展冲突清理用ele.removeScratch(namespace)效果是将该命名空间置为undefined而非删除键区分空值undefined 未初始化/已清理null 显式空值二者语义可安全区分不污染导出scratch 数据不进json()适合存放不可序列化对象与布局中间态。配套可继续深入阅读仓库内的 scratch.md、removeScratch.md 文档以及 src/define/data.mjs、src/collection/data.mjs、src/core/data.mjs 三处源码即可完整掌握 cytoscape.js 的临时数据存取体系。【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址: https://gitcode.com/gh_mirrors/cy/cytoscape.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考