Cytoscape.js 元素 scratch 数据存储：在元素上安全保存非 JSON 临时数据的完整指南

数据可视化【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址https://gitcode.com/gh_mirrors/cy/cytoscape.js点击查看免费下载导读ele.scratch()是 Cytoscape.js 为每个元素节点与边提供的一块临时便签区用于保存不便进入ele.data()的、不可序列化的运行时数据。本指南以官方文档 scratch.md 为主体结合仓库源码src/define/data.mjs、src/collection/data.mjs等与真实布局扩展用法帮助你掌握 scratch 的读写姿势、命名空间约定、事件行为与removeScratch()清理手段并理解它与data()、json()、渲染器专用rscratch的本质区别。一、scratch 是什么元素的临时便签区官方文档对ele.scratch()的定位非常明确它是一个用于存储临时数据、且允许存放非 JSON 数据的函数。与元素常规数据接口ele.data()相比scratch 的核心差异在于序列化边界通过ele.data()写入的数据会被ele.json()输出即会进入元素的 JSON 快照参与导出、保存等流程通过ele.scratch()写入的数据不会被ele.json()包含因此可以放心地在上面保存函数引用、DOM 节点、渲染缓存、布局中间态等不可序列化的对象。这个特性让 scratch 成为扩展extension保存内部状态的天然容器布局、渲染器等扩展都以自身注册名作为命名空间在元素上读写 scratch互不干扰。二、API 形态与基础读写scratch 在元素集合层面提供两种方法scratch()与removeScratch()。其完整签名与行为如下。1.eles.scratch()不带任何参数调用返回整个 scratch 对象即该元素_private.scratch的引用var j cy.$(#j); // 整个 scratchpad // 注意直接取整个对象时你可能会覆盖掉别人的命名空间 // 或者干脆忘记使用命名空间——官方文档明确提示要小心 var fooScratch j.scratch()._foo {}; // ... 之后你可以随意修改 fooScratch以键名方式读取单个命名空间// 从元素上读取命名空间 _foo前提是之前已经写入过 var fooScratch j.scratch(_foo); // ... 之后你可以随意修改 fooScratch以键名 值方式写入命名空间// 把命名空间 _foo 设置为一个对象写入元素 // 官方文档推荐这种写法更安全 var fooScratch j.scratch(_foo, {}); // ... 之后你可以随意修改 fooScratch2.eles.removeScratch(names)用于删除 scratch 中指定键支持空格分隔的多个键名不带参数时清空全部 scratch 键j.removeScratch(_foo); // 删除单个命名空间 j.removeScratch(_foo _bar); // 同时删除多个命名空间 j.removeScratch(); // 清空整个 scratch 对象从源码实现看src/collection/data.mjsremoveScratch由define.removeData生成删除后同样会触发scratch事件。3. 链式调用与集合级操作scratch()和removeScratch()都保持了 Cytoscape.js 的链式调用惯例。值得强调的是它们定义在**元素集合elesfn**上因此对集合调用时会对集合中的每一个元素逐一写入/读取——读取时只取集合中第一个元素的结果写入时则批量生效cy.$(node).scratch(_visited, true); // 给所有节点打标记 cy.$(node).scratch(_visited); // 读取返回第一个节点的值 cy.$(node).removeScratch(_visited); // 批量清除三、命名空间约定扩展名与下划线前缀官方文档给出了明确的命名空间约定这是使用 scratch 最重要的规范扩展extensions——布局、渲染器等——使用ele.scratch()时必须以自身注册名作为命名空间。例如名为foo的扩展应使用命名空间foo// 某扩展内部 ele.scratch(foo, someState); // 以注册名 foo 为命名空间应用层代码app-level data——如果你的业务代码也想借用 scratch 保存自己的临时数据请给命名空间加上下划线前缀以避开扩展名。例如在你的应用中应使用ele.scratch(_foo)这样就不会与名为foo的扩展产生冲突// 你的应用代码下划线前缀避免与扩展 foo 冲突 j.scratch(_foo, {});这套约定与扩展注册机制是对应的Cytoscape.js 的扩展在注册时使用唯一的名字如layout.breadthfirst各扩展在自己的命名空间内读写 scratch等于在元素身上划出了一块块互不侵犯的私有领地。四、源码级原理scratch 是如何实现的1. 数据定义与 data() 同构的字段访问器在 src/collection/data.mjs 中scratch由define.data()工厂函数生成scratch: define.data( { field: scratch, // 读写目标是元素 _private.scratch 字段 bindingEvent: scratch, // 可绑定 scratch 事件传函数给 scratch() 时 allowBinding: true, allowSetting: true, settingEvent: scratch, // 写入后触发 scratch 事件 settingTriggersEvent: true, triggerFnName: trigger, allowGetting: true, updateStyle: true // 写入后触发样式更新 } ),可以看到它和data一样走define.data模板唯一的差别是field: scratch。核心实现位于 src/define/data.mjs逻辑要点如下键名含点号.时支持路径读写源码中name.indexOf(.) ! -1时会把键名交给 lodash 的toPath/get/set处理例如j.scratch(foo.bar.baz, v)会按路径写入深层对象传入普通对象时为批量扩展模式j.scratch({ a: 1, b: 2 })会把多个键一次性并入 scratch传入函数时为事件绑定模式j.scratch(function(){ ... })等价于j.on(scratch, fn)监听 scratch 变更事件所有分支最终都return self维持链式调用。元素创建时scratch 的初始值在 src/collection/element.mjs 中初始化scratch: params.scratch || {}即可以随元素初始化参数注入初始 scratch 内容。2. 核心cy层面同样可用scratch不仅在元素层面可用核心对象cy上也有同名方法。在 src/core/data.mjs 中cy.scratch()与cy.removeScratch()的配置与元素版完全一致同样触发scratch事件、同样updateStyle: true。因此需要在整个画布层面保存临时状态如当前工具模式、全局缓存标记时可以直接使用cy.scratch(_myKey, value)。3. 事件行为由于settingTriggersEvent: true无论通过元素还是核心调用scratch(name, value)写入数据后都会触发名为scratch的事件。可以这样监听cy.on(scratch, node, function(evt){ console.log(node scratch changed, evt.target.id()); });4. 写入会触发样式重算注意scratch配置中updateStyle: true意味着每次scratch()写入后都会调用元素的updateStyle()。虽然 scratch 本身不参与样式映射但这一行为意味着频繁的 scratch 写入会带来额外的样式更新开销——高频写入的临时数据应优先考虑rscratch见下文。五、真实扩展用法breadthfirst 布局的 scratch 实战scratch 并非空谈仓库内置的广度优先布局就是活生生的例子。在 src/extensions/layout/breadthfirst.mjs 中布局直接封装了一对 scratch 读写助手const getInfo ele ele.scratch(breadthfirst); const setInfo (ele, obj) ele.scratch(breadthfirst, obj);布局运行期间把每个节点的计算状态写入breadthfirst命名空间见 src/extensions/layout/breadthfirst.mjssetInfo( ele, { index: i, // 节点在所在深度层内的序号 depth: d // 节点所处的 BFS 深度 } );后续通过getInfo(ele)取回{ depth, index }来调整层级、排序这正是布局在元素上暂存算法中间态的典型范式。由此可以提炼出扩展使用 scratch 的标准套路// 扩展内部以自身名字为命名空间读写 const NS myLayout; // 你的扩展注册名 // 写入 ele.scratch(NS, { status: pending, order: i }); // 读取 const info ele.scratch(NS); // 清理布局结束时 ele.removeScratch(NS);六、测试验证scratch 数据随元素移动而保留scratch 数据与元素的关联是否稳定仓库测试 test/collection-graph-manipulation.mjs 给出了明确答案。测试覆盖了四组场景边在move({ source: n3 })重设起点后原始类型bar与对象类型 scratch 数据都保持不变节点在move({ parent: n1 })改挂父节点后原始类型与对象类型 scratch 数据同样保持不变。这说明 scratch 作为元素_private的一部分会随元素的生命周期含移动、重组等操作持久保留可以在布局/渲染流程的多个阶段之间安全传递状态。七、与 data()、json()、rscratch 的边界1.scratchvsdata维度ele.data()ele.scratch()序列化会被ele.json()输出不会被ele.json()输出适用数据需要随图导出/持久化的业务数据运行时临时、不可序列化数据函数、缓存、中间态命名空间无强制约定键名即字段约定以扩展名或_前缀命名空间触发事件datascratch官方文档特别强调ele.data()存储的数据会进入ele.json()而ele.scratch()存储的数据不会见 json.md 可查看 JSON 导出详情。因此临时存放不可序列化数据正是 scratch 的存在意义。2.scratchvsrscratch除了公开的scratch元素内部还有一块渲染器专用的rscratchrenderer scratch。在 src/collection/data.mjs 中可以看到其配置差异巨大rscratch: define.data( { field: rscratch, allowBinding: false, // 不允许绑定事件 allowSetting: true, settingTriggersEvent: false, // 写入不触发任何事件 allowGetting: true } ),rscratch不触发事件、不触发样式更新是渲染器存放高频几何/坐标缓存的专用区域例如 rendered-style.mjs 中通过_p.rscratch存取渲染时样式结果。如果你需要保存高频更新的渲染级临时数据rscratch是比scratch更轻量的选择但它是渲染器内部设施应用层应优先使用公开的scratch。八、最佳实践小结扩展代码始终以自身注册名为命名空间如ele.scratch(foo, ...)应用代码用下划线前缀的命名空间如ele.scratch(_foo, ...)避免与扩展冲突避免裸取整个 scratch 对象j.scratch()返回整块引用直接往里塞键容易覆盖他人数据官方示例也提醒be careful优先使用j.scratch(_key, value)的命名空间写入只存临时、非序列化数据需要随json()导出或跨会话持久化的数据请走ele.data()见 data.md及时清理使用removeScratch()见 removeScratch.md在布局/扩展结束时清理不再需要的命名空间避免内存中残留引用高频写入用rscratchscratch每次写入会触发scratch事件与updateStyle()高频路径可考虑渲染器级的rscratch。相关资源官方文档scratch.md元素级实现src/collection/data.mjs核心级实现src/core/data.mjs底层工厂src/define/data.mjs真实扩展用例src/extensions/layout/breadthfirst.mjs回归测试test/collection-graph-manipulation.mjs赞分享数据可视化【免费下载链接】cytoscape.jsGraph theory (network) library for visualisation and analysis项目地址https://gitcode.com/gh_mirrors/cy/cytoscape.js点击查看免费下载相关推荐Cytoscape.js 元素数据管理完全指南ele.data()、removeData() 与 scratch() 深度解析Cytoscape.js 元素数据管理完全指南ele.data 、removeData 与 scratch 深度解析 导读 在 Cytoscape.js 中数据可视化RxDB Local Documents 完整指南在 RxDatabase 与 RxCollection 上存储无 Schema 的本地元数据RxDB Local Documents 完整指南在 RxDatabase 与 RxCollection 上存储无 Schema 的本地元数据 Local D数据库NoSQL嵌入式数据库实时数据库BioPandas完全指南如何在pandas DataFrames中高效处理分子结构数据BioPandas完全指南如何在pandas DataFrames中高效处理分子结构数据 BioPandas是一款专为结构生物学打造的Python库它能将P创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考