Meteor ReactiveDict 完全指南基于 Tracker 的响应式键值对状态管理【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteorReactiveDict 是 Meteor 客户端内置的一个通用响应式数据源它存储任意键值对每个 key 独立响应set一个 key 会精确失效那些调用过get该 key 的 Tracker 计算如Tracker.autorun、Blaze 模板 helper。本文以官方文档 docs/source/api/reactive-dict.md 为主线结合 packages/reactive-dict 的完整源码与测试讲解安装方式、全部 API构造、set/setDefault/get/equals/all/clear/delete/destroy、Hot Code Push 数据迁移机制及其底层实现原理帮助你用它管理组件内部状态如列表当前选中项、聊天室 ID、UI 过滤器等写出最小失效、最高效的响应式代码。ReactiveDict 是什么一个 ReactiveDict 存储一组任意键值对适合用来管理组件内部的临时状态例如“当前选中的列表项”。它与Session的能力基本一致响应式get、set、equals但它是模块化的字典对象可以自由创建任意多个实例。它的核心特性是按 key 粒度响应每个 key 都是独立的响应式数据源。根据响应式数据源的常规约定调用set(currentList, x)会失效所有曾在该 key 上调用过get(currentList)的计算。这意味着如果你在 Blaze 模板 helper 中调用ReactiveDict#get(currentList)那么只要ReactiveDict#set(currentList, x)被调用模板就会自动重新渲染——你不需要手动订阅、手动触发刷新一切由 Tracker 依赖系统自动完成。注意ReactiveDict 的locus是Client即它只在客户端可用。不要在服务端代码中依赖它作为状态容器。安装在项目根目录运行meteor add reactive-dictreactive-dict包的元信息定义在 packages/reactive-dict/package.js它强依赖tracker、ejson、ecmascript三个包并弱依赖mongo与reload两个包弱依赖意味着“若项目已加载这些包则可用否则不影响使用”。具体来说弱依赖mongo用于在equals中识别并比较Mongo.ObjectID弱依赖reload用于在 Hot Code Push 时保存与恢复数据详见下文迁移机制一节。构造 ReactiveDictconst state new ReactiveDict();构造函数签名new ReactiveDict([name], [initialValue])。两个参数均可选nameString可选命名该字典。一旦提供名称字典内容会在 Hot Code Push 客户端代码更新时被保存下来跨热更新持久化。initialValueObject可选字典的初始默认值。从源码reactive-dict.js可以看到构造函数内部的细节未命名时直接用_setObject(dictData)写入初始数据但不会注册迁移命名时typeof dictName string仅当Meteor.isClient才执行迁移逻辑服务端在 reload 期间会因重复名称报错调用_registerDictForMigrate注册迁移并尝试_loadMigratedDict恢复上次热更新保存的数据若没有已迁移数据则写入initialValue兼容旧版本0.9.1 及更早若第一参数是对象而非字符串则视为migrationData直接写入其他类型的非法参数会抛出Invalid ReactiveDict argument: ...。构造完成后内部会建立三组响应式依赖reactive-dict.jsallDeps一个全局Tracker.Dependency服务于all()keyDepskey - Dependency的映射服务于get(key)keyValueDepskey - serializedValue - Dependency的二级映射服务于equals(key, value)。正是这套“一 key 一依赖、一值一依赖”的结构实现了按 key 的最小粒度失效。set写入值并触发失效const state new ReactiveDict(); state.set(currentRoomId, random); Tracker.autorun(() { Meteor.subscribe(chatHistory, { room: state.get(currentRoomId) }); }); // 下面这行会让上面 autorun 中的函数重新执行 // 从而把 chatHistory 订阅切换到房间 general。 state.set(currentRoomId, general);set(key, value)会写入该 key 的值并失效所有依赖它的计算——包括调用过get(key)的模板触发重绘与Tracker.autorun计算。对象批量写入set还支持传入一个对象等价于对每个 key 分别调用一次setconst state new ReactiveDict(); state.set({ a: foo, b: bar });set 的底层行为从源码看reactive-dict.jsset的关键逻辑是重载判定若第一参数是对象且第二参数为undefined则视为批量写入调用_setObject逐 keyset这一点借鉴了 BackboneModel#set的写法序列化存储所有值内部都经过stringify处理——undefined序列化为字符串undefined其余值用EJSON.stringify序列化。因此 ReactiveDict 可以存储 EJSON 支持的任何值对象、数组、Date 等读取时再经parseEJSON.parse还原新旧值比较只有value ! oldSerializedValue或 key 原本不存在时才触发allDeps.changed()同时失效该 key 对应的keyDeps[key]以及keyValueDeps[key]上的新旧两个值依赖。写入相同值不会触发任何失效这是 ReactiveDict 高效的关键之一构造阶段keyDeps尚未初始化写入初始数据时不会误触发依赖。setDefault只在 key 未设置时写入const state new ReactiveDict(); state.setDefault(count, 0);setDefault(key, value)与该 key 尚未被设置过时写入值否则完全等同于set一样不生效。它同样支持对象批量形式。源码实现reactive-dict.js很简单仅当!hasOwn.call(this.keys, key)时才调用set。注意测试 reactive-dict-tests.js 验证了一个细节set(B, undefined)之后再setDefault(B, default)也不会覆盖因为 keyB已存在。setDefault尤其适合用在初始化代码中配合命名字典 Hot Code Push 迁移可以避免每次应用新版本加载时都重新初始化状态例如用户上次选择的主题、上次查看的房间只有首次加载时才会写入默认值。get读取值并建立依赖const state new ReactiveDict(); state.get(currentList);get(key)返回该 key 当前存储的值。若在响应式计算内部调用则下次该 key 被set时计算会被失效并重跑。返回值是值的克隆如果存的是对象或数组直接修改返回值的属性不会影响字典内部存储的数据。一个完整可运行的 Blaze 组合示例源自官方文档!-- main.html -- template namemain pWeve always been at war with {{theEnemy}}./p button classchange-enemyChange Enemy/button /template// main.js Template.main.onCreated(function () { this.state new ReactiveDict(); this.state.set(enemy, Eastasia); }); Template.main.helpers({ theEnemy() { const inst Template.instance(); return inst.state.get(enemy); } }); Template.main.events({ click .change-enemy(event, inst) { inst.state.set(enemy, Eurasia) } }); // 点击按钮后页面会变为 Weve always been at war with Eurasia这个例子展示了 ReactiveDict 在 Blaze 中最典型的用法在onCreated中创建实例并初始化在 helper 中get建立响应式依赖在事件处理器中set触发重渲染。由于依赖按 key 精确跟踪只有enemy这个 key 对应的 helper 会重跑页面其余部分不受影响。delete删除单个 keyconst state new ReactiveDict(); state.set(foo, bar); state.delete(foo);delete(key)删除该 key 并失效所有相关监听者get、equals、all的计算都会被通知。源码reactive-dict.js返回布尔值didRemovekey 存在且被删除时返回truekey 不存在时返回false且不触发任何失效。测试 reactive-dict-tests.js 验证了这一点。equals标量精确比较减少无效失效const state new ReactiveDict() // ... state.get(key) value state.equals(key, value)如果 value 是标量上面两个表达式的结果相同。但推荐使用第二个equals(key, value)只在值“变为该值”或“从该值变为其他值”时才失效计算因此触发更少的失效模板重绘程序更高效。equals有严格的参数限制value 必须是标量即string | number | boolean | null | undefined另外允许Date实例以及当mongo包已加载时的Mongo.ObjectID实例。传入对象或可能包含对象的数组会抛出ReactiveDict.equals: value must be scalar。原因在源码注释中有明确说明reactive-dict.jsJSON.stringify不保证对象键的排列顺序无法对对象值产生规范化的序列化结果因而无法确定keyValueDeps[key]中该存哪个依赖条目。如需对对象做响应式相等比较可使用EJSON.equals(reactiveDict.get(key), value)。其实现还包含一个内存优化equals在使用keyValueDeps[key][serializedValue]时通过Tracker.onInvalidate注册清理回调当某依赖不再有订阅者时立即删除对应条目避免长期运行后内存无界增长O(n) 内存n 为历史上见过的值个数。all获取全部键值对const state new ReactiveDict(); state.all(); // - { ... }all()以普通对象返回全部键值对。若在响应式计算内调用任何 key被set时该计算都会失效它依赖的是allDeps而不是单个keyDeps。同样返回的是每个值的克隆直接修改返回值不会影响字典内部数据。需要说明的是set(key, undefined)后该 key 依然存在all()中会包含该 key值为undefined这一点由测试 reactive-dict-tests.js 明确验证只有delete或clear才会真正移除 key。clear 与 destroy清空与销毁const state new ReactiveDict(); state.clear(); state.destroy();clear()移除所有键值对并通知所有监听者get、equals、all对应的计算全部失效。源码reactive-dict.js会同时触发allDeps.changed()并对每个旧 key 触发keyDeps与keyValueDeps的变更。destroy()等价于clear()之后再从迁移注册表中移除该字典若其有名称阻止它在后续 Hot Code Push 中被迁移保存。测试 reactive-dict-tests.js 展示了完整生命周期同名字典在客户端且reload包存在时重复创建会抛出Duplicate ReactiveDict name: ...destroy之后即可再次创建同名实例。深入原理Hot Code Push 数据迁移这是 ReactiveDict 最实用的高级能力给构造函数传 name内容即可跨 Hot Code Push 客户端代码更新保存。其实现位于 packages/reactive-dict/migration.js与reload包协作完成注册ReactiveDict._registerDictForMigrate(dictName, dict)将命名字典登记进_dictsToMigratename - ReactiveDict若同名重复注册直接抛出Duplicate ReactiveDict name错误。采集通过Package.reload.Reload._onMigrate(reactive-dict, fn)注册迁移回调在热更新前把所有已注册字典的数据经_getMigrationData()得到的原始序列化键值表打包成{dicts: dataToMigrate}交给reload包保存。恢复新代码加载时Reload._migrationData(reactive-dict)取回上次保存的数据存入_migratedDictData命名字典构造时通过_loadMigratedDict(dictName)取出并直接作为keys使用不再二次序列化一次性加载后即删除该记录。需要强调的是迁移逻辑只在Meteor.isClient Package.reload时生效未安装reload包时这一切静默跳过。结合setDefault的用法你可以在新版本加载时既不覆盖用户上次的状态又能为首次出现的 key 提供默认值。TypeScript 支持reactive-dict随包提供了完整的类型声明 packages/reactive-dict/reactive-dict.d.ts通过package-types.json声明typesEntry在 package.js 中以addAssets方式随包分发。泛型类ReactiveDictO EJSONable提供了constructor(name?: string, initialValue?: PartialO)setP extends keyof O(key: P, value?: O[P])及对象重载set(object: PartialO)setDefault的同名双重重载getP extends keyof O(key: P): O[P] | undefinedequals(key, value: string | number | boolean | undefined | null): booleanall(): PartialO、clear(): void、delete(key): boolean、destroy(): void这意味着你可以声明一个类型化的状态字典例如new ReactiveDict{ currentRoomId: string; muted: boolean }()在编译期获得 key 与值的类型检查。测试与可靠性该包的行为由完整的 Tinytest 测试套件 packages/reactive-dict/reactive-dict-tests.js 覆盖包括set到undefined后 key 仍存在、setDefault不覆盖以多种参数形式对象、命名 初始值、undefined 初始值初始化all()在响应式计算中的自动更新clear()、delete(key)、destroy()对各响应式监听者get/equals/all的失效行为以及返回布尔值的正确性同名命名字典的重复注册错误与destroy后的重建。与 reactive-var 的取舍ReactiveDict 与reactive-var包单值响应式容器同属 Meteor 的响应式状态工具。差别在于ReactiveVar只管理一个值而 ReactiveDict 管理一组命名的键值对并且每个 key 独立响应。当你需要同时维护多个相关的 UI 状态如筛选条件、选中项、分页参数时一个命名 ReactiveDict 通常比多个 ReactiveVar 更清晰官方 READMEpackages/reactive-dict/README.md也把“与 reactive-var 统一”列为未来工作方向。小结与最佳实践按需最小失效在 helper 中优先用get在条件判断场景用equals在需要整体快照时用all避免用all()取代get(key)否则会失去按 key 精确失效带来的性能优势。初始化用setDefault配合命名字典 Hot Code Push 迁移让状态跨版本更新保持稳定。写相同值不触发失效set内部按序列化字符串比较重复设置相同值不会引起重渲染。清理生命周期组件销毁时调用destroy()既能清空数据也能释放迁移注册避免“Duplicate ReactiveDict name”错误并防止状态泄漏到下次热更新。类型化使用在 TypeScript 项目中利用泛型ReactiveDictO获得完整的 key 类型提示。参考文件官方 API 文档docs/source/api/reactive-dict.md核心实现packages/reactive-dict/reactive-dict.js迁移机制packages/reactive-dict/migration.js类型声明packages/reactive-dict/reactive-dict.d.ts测试套件packages/reactive-dict/reactive-dict-tests.js包定义packages/reactive-dict/package.js包说明packages/reactive-dict/README.md【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
