人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载导读createRef是 VueUse 响应式Reactivity工具集中一个轻量而实用的工厂函数其核心职责只有一个根据deep布尔参数返回一个浅层响应式的ShallowRefT或一个深响应式的RefT。在 airi 这类以 Vue 3 Electron / Web 多端形态承载实时语音、弹幕、聊天与舞台渲染的复杂前端仓库中深层对象监听的开销与浅引用带来的性能收益往往需要按场景取舍createRef正是把这一决策收敛为一个带类型推导的函数调用的理想工具。读完本文你将掌握createRef的完整类型签名、deep参数的语义边界以及它在大规模 Vue 3 项目中与shallowRef的配合方式与适用场景。createRef 是什么一个参数决定深浅的引用工厂createRef的函数签名极简接收一个初始值value与可选的deep布尔参数返回类型为CreateRefReturnT, D——即要么是ShallowRefT要么是RefT。文档对其的官方描述是Returns adeepReforshallowRefdepending on thedeepparam.也就是说createRef本身并不发明新的响应式语义而是将 Vue 3 原生ref深响应与shallowRef浅响应的选择逻辑封装为一个显式、可读、可类型推导的入口。这一点从它的类型定义可以看得很清楚export type CreateRefReturn T any, D extends boolean false, ShallowOrDeepRefT, D export type ShallowOrDeepRef T any, D extends boolean false, D extends true ? RefT : ShallowRefTShallowOrDeepRef是一个典型的条件类型conditional type当D为字面量true时返回RefT否则包括未传参时的默认false返回ShallowRefT。这意味着返回值类型会随着调用参数被精确推断createRef(1)在类型层面就是ShallowRefnumber而createRef(1, true)就是Refnumber如下方官方文档示例所展示import { createRef } from vueuse/core import { isShallow, ref } from vue const initialData 1 const shallowData createRef(initialData) const deepData createRef(initialData, true) isShallow(shallowData) // true isShallow(deepData) // falseisShallow是 Vue 3.4 提供的运行时判定 API此处恰好充当了运行时验证shallowData是浅引用deepData是深引用。deep 参数语义何时浅、何时深deep参数决定的是值变化时的追踪粒度而不是响应式本身的有无——两者都是响应式引用区别在于内部值createRef(value)或createRef(value, false)返回ShallowRefT。.value的整体替换会被追踪但对.value内部嵌套属性如value.obj.key ...的修改不会触发更新。适用于大型对象、频繁整体替换的引用如 DOM 元素、组件实例、频繁重建的复杂数据结构。createRef(value, true)返回RefT。与 Vue 原生ref等价会对对象内部嵌套属性做深层次响应式代理适用于需要深度响应的小型状态对象。从__NO_SIDE_EFFECTS__注解可以看出该函数是纯构建逻辑、无任何副作用可以放心在模块顶层或热更新环境中重复调用。官方类型声明中的示例注释对四种调用形态做了完整罗列/** * example createRef(1) // ShallowRefnumber * example createRef(1, false) // ShallowRefnumber * example createRef(1, true) // Refnumber * example createRef(string) // ShallowRefstring * example createRefA|B(A, true) // RefA|B * * param value * param deep * returns the deepRef or shallowRef * * __NO_SIDE_EFFECTS__ */ export declare function createRefT any, D extends boolean false( value: T, deep?: D, ): CreateRefReturnT, D值得注意的细节是T默认是any但可以通过显式泛型收窄如createRefA|B(A, true)得到RefA|B让联合类型在深浅两种引用上都被完整保留。完整类型声明与条件类型推导将文档中的类型声明整体展开可以归纳出三个层次CreateRefReturnT, D对外暴露的返回类型别名本质是ShallowOrDeepRefT, DShallowOrDeepRefT, D核心条件类型D extends true分支给出RefT否则给出ShallowRefTcreateRefT, D函数重载签名value: T、deep?: D未传deep时D落入默认值false从而默认返回浅引用。这种设计在 TypeScript 使用者视角的价值在于调用处无需任何类型断言返回值就能与 Vue 的watch、templateRef、toValue等 API 正确对接。例如把createRef(initialData)的结果传给一个只接受ShallowRef的参数编译器可以精确校验。在 airi 仓库中的工程实践印证createRef所属的 VueUse 库在 airi 仓库中是全量依赖的基础设施。根目录的 pnpm-workspace.yaml 中通过 catalog 统一固定了vueuse/core与vueuse/shared的版本为^14.4.0从apps/component-calling、apps/stage-tamagotchi、apps/stage-web到packages/stage-ui、packages/electron-vueuse等十余个应用与包均通过vueuse/core: catalog:引用例如 apps/stage-tamagotchi/package.json、packages/stage-ui/package.json保证了整个 monorepo 内 VueUse 行为的一致。虽然仓库内没有直接以createRef(...)字样调用其用途常被shallowRef直接替代但shallowRef的浅响应模式在整个 airi 前端代码中被大量使用恰好印证了createRef默认分支所服务的场景在 packages/electron-vueuse/src/composables/use-electron-mouse-in-element.ts 中鼠标坐标、元素包围盒等高频更新的数值状态全部使用shallowRef(0)、shallowRef(true)初始化——这类值每次都是整体替换elementX.value elX深响应毫无必要浅引用避免了无谓的深度代理开销在 apps/stage-tamagotchi/src/renderer/components/InteractiveArea.vue 中语音录制状态voicePending、voiceActive这类布尔开关同样用shallowRef(false)承载在 apps/stage-tamagotchi/src/renderer/composables/use-chat-feed-expiry.ts 中驱动消息过期计算的时钟now被声明为shallowRef(Date.now())每次仅通过.value 整体替换时间戳。这些真实用例可以视为createRef(value)与createRef(value, false)的等价展开说明在「高频整体替换 无嵌套追踪需求」的场景下浅引用是 airi 前端工程中被验证过的合理默认选择而需要深响应时显式传入true即可无需改换 API。与 VueUse Reactivity 家族其他成员的协作定位在 VueUse 的 Reactivity 分类中createRef与若干函数在概念上相邻理解它们的差异有助于在编码时做出正确选择函数清单与调用规则见 .agents/skills/vueuse-functions/SKILL.mdrefDefault为 ref 附加默认值当.value为undefined时回退到默认值——解决的是「值缺失」问题与createRef解决的「追踪深度」问题正交toReactive将对象型 ref 转换为 reactive实现「可整体替换的响应式对象」——它面向对象解包场景而createRef面向引用创建场景toRef将 value / ref / getter 归一化为 ref 或 computed——注意 VueUse 版toRef与 Vue 原生toRef行为不同前者接受原始值与 getter、不接受object keyextendRef为 ref 附加额外属性模板中不可见ref 值会被自动解包——与createRef组合使用时可以先createRef得到深浅合适的引用再extendRef附加元数据createGlobalState把状态提升到全局作用域跨 Vue 实例复用其内部工厂函数同样常以shallowRef构建状态如const count shallowRef(0)与createRef的浅引用理念一脉相承。从决策链看需要跨实例共享、持久化时优先createGlobalStateuseStorage需要为现有引用附加数据时用extendRef而「新建一个引用、并且明确知道追踪深度」这一最小需求正是createRef的定位。使用建议与最佳实践综合文档语义与 airi 仓库的工程实践可以归纳出以下选型建议默认值偏好浅引用createRef(value)的默认行为就是浅引用这与 VueUse 一贯「默认最小开销」的设计取向一致。如果你的状态每次都是整体赋值如时间戳、坐标、布尔开关、DOM 引用直接使用默认分支即可无需手动传false。显式深响应当状态对象需要被深度修改并触发视图更新例如嵌套的配置对象、表单模型时显式传createRef(value, true)并在类型层面获得RefT。利用类型推导借助ShallowOrDeepRef条件类型让deep参数参与返回类型计算避免手写联合类型或类型断言增强可维护性。在 monorepo 中保持一致airi 通过 pnpm-workspace.yaml 的 catalog 将vueuse/core固定在^14.4.0使用createRef时应确认目标包已声明vueuse/core: catalog:依赖参见各应用与包的package.json确保运行时行为与本文示例一致。运行时自检若需在测试中验证深浅语义可用 Vue 的isShallow断言如官方示例所示这一能力在 airi 的 vitest 测试体系中可直接复用。小结createRef是 VueUse Reactivity 工具箱中一个「小而准」的工厂函数它把 Vue 3 的深浅响应选择收敛为单一deep参数并通过条件类型让返回类型随调用精确推导。无论是 airi 中高频更新的鼠标坐标、语音开关与时钟这类浅引用场景还是需要深度追踪的复杂状态对象createRef都提供了一条可读、可维护、类型安全的统一入口是 Vue 3 响应式建模中值得纳入日常工具箱的基础工具。赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐VueUse 的 createRef按需创建深/浅响应式引用Ref 与 ShallowRef 的统一入口VueUse 的 createRef按需创建深/浅响应式引用Ref 与 ShallowRef 的统一入口 导读 createRef 是 VueUse 工具前端VueUse createRef 使用指南一个参数切换深层与浅层响应式引用VueUse createRef 使用指南一个参数切换深层与浅层响应式引用 导读 createRef 是 VueUseVue 3 组合式工具集中一个轻量级前端VueUse reactify 深入解析把普通函数转换为响应式函数VueUse reactify 深入解析把普通函数转换为响应式函数 reactify 是 VueUseVue 3 组合式工具库中位于 Reactivity前端上一篇OpenProject 风险管理实战指南用工作包、工作流与项目模板构建可复用的风险登记册下一篇4步上手res-downloader资源嗅探与批量下载指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考