toref的核心作用是从响应式对象中安全提取单个属性并保持双向响应性：修改toref创建的引用或原对象属性，双方同步更新；适用于解构、传参等需保留响应性的场景。

在 Vue 3 中，toRef 的核心作用是：从响应式对象（如 reactive 或 ref）中**安全地提取某个属性，且保持该属性的响应性**。它不是简单复制值，而是创建一个指向原属性的“引用”，修改它会同步影响源对象。

什么时候必须用 toRef？

当你需要把响应式对象的某个属性单独传给子组件、组合函数或解构使用，又不想丢失响应性时，toRef 就是标准解法。直接解构会导致响应性丢失：

Ainative Vue Sdk

使用 `@ainative/vue-sdk` 为 Vue 3 应用添加 AI 聊天功能。适用于以下场景：(1) 安装 `@ainative/vue-sdk`，(2) 在 Vue 组件中使用 `useChat` 组合式函数，(3) 提供……

下载

• ❌ 错误示例（丢失响应性）：
  const { count } = reactive({ count: 0 }); —— count 变成普通数字，修改它不会触发视图更新
• ✅ 正确做法：
  

  const state = reactive({ count: 0 });<br>const countRef = toRef(state, 'count');

  —— countRef 是个 Ref，有 .value，且与 state.count 同步

toRef 和 toRefs 的区别

toRef 处理单个属性，toRefs 是批量版，适合解构整个响应式对象：

• toRef(obj, 'name') → 返回单个 Ref
• toRefs(obj) → 返回一个对象，每个 key 都是对应的 Ref，可安全解构：
  const { name, age } = toRefs(state);
• 注意：toRefs 只对 reactive 对象有效；对 ref 调用 toRefs 没意义（它本身已是 Ref）

和 ref、shallowRef 的关键区别

toRef 不创建新响应式数据，只是建立“桥梁”：

• ref(10) 创建独立响应式变量，修改它不影响其他地方
• toRef(obj, 'x') 创建的 Ref 与 obj.x 共享底层依赖，读写都联动
• 即使 obj.x 后续被重新赋值为新响应式对象，toRef 创建的引用仍能自动追踪（因为它是基于 property key 的响应式绑定）

实际使用建议

• 在 setup() 或组合式函数中，优先用 toRefs 解构 reactive 对象，再按需传递给子组件 props 或其他函数
• 避免对非响应式对象（如普通 object、props 默认值）调用 toRef，否则返回的是只读的普通 Ref，不具双向响应
• 如果目标属性可能不存在，toRef(obj, 'missing') 会返回一个初始值为 undefined 的 Ref，但不会报错——需自行判断存在性

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！