airi 项目中的 VueUseuseCached用自定义比较器精细控制 ref 缓存更新的完整指南【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiuseCached是 VueUse 提供的响应式缓存工具它允许开发者用一个**自定义比较器custom comparator**来决定当源 ref 的值变化时缓存值究竟应该保留原样还是跟随更新。本文以 airi 仓库内的 VueUse 技能文档为主体结合仓库中vueuse/core的实际应用与shallowRef的使用模式系统讲解useCached的 API、类型体系、核心语义与实战落地方式帮助你用它替代手写的watch 条件赋值逻辑写出更简洁、可维护的 Vue 3 代码。一、useCached是什么useCached是 VueUse 中一个位于Utilities工具类分类下的组合式函数一句话概括它的作用Cache a ref with a custom comparator使用自定义比较器缓存一个 ref。它接收一个源 ref 和一个比较器函数返回一个新的 ref。返回的缓存 ref 不会盲目跟随源值变化而是先经过比较器判断只有比较器认为应该更新时缓存值才被同步为新的源值。在 .agents/skills/vueuse-functions/SKILL.md 的函数索引表中useCached的调用规则Invocation被标记为AUTO即在 Vue.js / Nuxt 项目中当需求匹配时应当自动考虑使用它而不是自己手写重复的缓存判断逻辑——这正是该技能文件倡导优先使用 VueUse composable 而非自造代码原则的直接体现。二、比较器Comparator签名与核心语义useCached的核心是第二个参数——比较器函数它的签名是(newSourceValue, cachedValue) boolean语义约定非常明确比较器返回true缓存保持不变keep the cache as-is比较器返回false缓存更新为新的源值update the cache to the new source value。理解这个语义反转非常关键它和Array.prototype.filter的保留直觉一致——返回true代表当前缓存值得保留返回false代表旧缓存应该被替换。如果你习惯写相等则更新的逻辑务必注意这里的方向是相反的。比较器的两个参数顺序也容易混淆第一个参数是新源值newSourceValue第二个才是当前缓存值cachedValue不要写反。三、完整使用示例与行为推演原文档给出了一个非常典型的对象缓存场景完整继承如下import { useCached } from vueuse/core import { shallowRef } from vue interface Data { value: number extra: number } const source shallowRefData({ value: 42, extra: 0 }) const cached useCached(source, (newSourceValue, cachedValue) newSourceValue.value cachedValue.value) source.value { value: 42, extra: 1, } console.log(cached.value) // { value: 42, extra: 0 } source.value { value: 43, extra: 1, } console.log(cached.value) // { value: 43, extra: 1 }逐步推演这个示例可以清晰看到比较器的工作过程初始状态source为{ value: 42, extra: 0 }缓存值随之初始化为同一份数据。第一次更新源值变为{ value: 42, extra: 1 }。此时比较器执行newSourceValue.value cachedValue.value即42 42返回true→缓存被保留仍然是{ value: 42, extra: 0 }。extra字段的变更被过滤掉了。第二次更新源值变为{ value: 43, extra: 1 }。比较器执行43 42返回false→缓存被更新成为{ value: 43, extra: 1 }。这个模式非常适合只关心对象中某个关键字段、忽略其他噪声字段的场景——例如服务端推送的 JSON 数据带有时间戳、版本号等高频变化字段但你只希望缓存值在业务主键value真正变化时才刷新。四、类型声明深度解读原文档给出的完整类型声明如下export interface UseCachedOptionsD extends boolean true extends ConfigurableDeepRefsD, WatchOptions {} export declare function useCachedT, D extends boolean true( refValue: RefT, comparator?: (newSourceValue: T, cachedValue: T) boolean, options?: UseCachedOptionsD, ): UseCachedReturnT, D export type UseCachedReturn T any, D extends boolean true, ShallowOrDeepRefT, D逐项拆解UseCachedOptionsD第三个可选参数options的类型它同时继承了ConfigurableDeepRefsD与 Vue 的WatchOptions。这意味着你既能控制深层/浅层响应式也能使用 Vuewatch的完整配置如flush、deep等。泛型D extends boolean true控制返回的 ref 是浅层shallowRef还是深层ref响应式默认true。UseCachedReturnT, D返回类型为ShallowOrDeepRefT, D即根据D的值决定返回ShallowRefT还是RefT。由于缓存值与源值默认保持相同的响应式层级返回类型也因此统一为Ref家族可以在模板和组合式函数中直接使用。五、与 VueUse 其他缓存/历史工具的辨析在决定使用useCached之前需要区分它与 VueUse 中几个容易混淆的邻近工具工具核心能力适用场景差异要点useCached用自定义比较器决定缓存是否跟随源 ref 更新只关心对象关键字段、过滤噪声更新更新策略完全由比较器自定义无历史记录useCloned响应式克隆一个 ref需要副本与源解耦、可手动sync()侧重克隆同步不提供比较器语义useMemoize按函数参数缓存计算结果并保持响应式昂贵计算结果的记忆化缓存键是参数与 ref 值缓存维度不同useRefHistory/useManualRefHistory追踪 ref 的变化历史撤销/重做、变更审计保留全部历史快照不丢弃更新usePrevious持有 ref 的上一个值需要上一次值做差值比较只存上一个值无过滤语义对应关系useCached属于选择性保留最新值useRefHistory属于保留全部历史usePrevious属于只留前一个。如果你的需求是变化了才更新、没变化就维持原样useCached是最贴合的工具如果需要回滚能力则应选择useRefHistory系列参考 useRefHistory.md 与 useManualRefHistory.md。六、在 airi 仓库中的落地场景airi 是自托管的 AI 陪伴应用支持实时语音、Minecraft 游玩覆盖 Web / macOS / Windows其前端大量使用 Vue 3 VueUse 生态。仓库证据如下多个前端应用均以pnpm catalog方式统一声明了vueuse/core依赖apps/stage-pocket/package.json、apps/stage-tamagotchi/package.json、apps/stage-web/package.json、apps/ui-server-auth/package.json、apps/component-calling/package.json中均为vueuse/core: catalog:说明 VueUse 是整个仓库前端共享的基础工具层。仓库中广泛使用shallowRef管理高频变化的状态。例如 permissions-panel.vue 中用shallowRef承载权限布尔状态controls-island-root.vue 中用shallowRefControlsIslandDock管理悬浮控制岛的停靠位置。由此可以推断useCached在 airi 这类项目中典型的适配场景实时语音/音频状态流音频采样、音量、设备状态等高频 ref参见 audio-input.ts 与 audio-record.ts往往携带大量中间变化可用比较器只保留用户关心的阈值级变化。模型/角色状态同步stage-pocket、stage-tamagotchi需要同步 3D 模型、Live2D 角色的状态对象当后端推送的状态中只有部分字段变化时用useCached过滤无关字段更新避免触发昂贵的渲染副作用。UI 配置面板controls-island-*.vue这类控制岛组件中的配置对象可用比较器忽略extra类的辅助字段只在核心参数变化时触发重绘。需要说明经检索当前仓库源码中尚未出现useCached的直接调用实例以上场景是基于仓库现有vueuse/core依赖、shallowRef使用模式与 composable 编码风格作出的合理推断落地时请以实际业务需求为准。七、使用建议与注意事项结合原文档语义与 VueUse 的工程实践给出以下使用要点配合shallowRef使用当源数据是对象/数组时优先用shallowRef承载并按需整体替换配合useCached的浅层缓存可显著减少深层响应式代理的开销VueUse 官方文档示例即采用shallowRef。比较器保持纯函数比较器应只做纯比较避免在其中写入副作用如修改缓存值否则可能引发不可预期的更新循环。返回值可直接用于模板UseCachedReturnT, D是标准的Ref/ShallowRef在template中会自动解包无需额外处理。需要历史时换工具如果保留旧值的同时还想支持撤销回滚请改用useRefHistory/useManualRefHistory如果只是记忆函数计算结果请使用useMemoize。遵循技能文件的 AUTO 规则按照 SKILL.md 的约定在 Vue.js / Nuxt 开发中遇到带过滤条件的 ref 缓存需求时应优先考虑useCached而非手写watch 条件赋值以保证代码的简洁性与可维护性。八、小结useCached用一个精炼的 API 解决了响应式世界里一个常见痛点如何有选择地缓存最新值。理解其比较器返回true保留、返回false更新的反向语义掌握ConfigurableDeepRefs与WatchOptions组成的选项体系并将它与useCloned、useMemoize、useRefHistory等邻近工具正确区分你就能在 airi 这类复杂 Vue 3 应用中写出更精准、更高效的响应式状态管理代码。完整的函数索引与调用规则可继续查阅 .agents/skills/vueuse-functions/SKILL.md 及 useCached.md 原文档。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考