toRef 是 Vue 3 中用于从响应式对象提取单个属性并保持双向响应性的工具函数，返回一个与原属性同步的 ref，适用于传参、组合式函数暴露字段及避免解构失响应等场景。

toRef 是 Vue 3 Composition API 中用于从响应式对象中“提取”单个属性并保持其响应式的工具函数。它不创建新副本，而是建立对原对象某属性的引用链接，修改 toRef 返回的 ref 会同步影响源对象，反之亦然。

什么时候该用 toRef？

当你需要把响应式对象（如 reactive 或 props）里的某个字段单独当作 ref 使用，又希望它和原数据保持双向同步时，toRef 就很合适。常见于：

• 将 reactive 对象的某个字段传给子组件（配合 defineProps 的 withDefaults 或 v-bind 展开）
• 在组合函数中暴露某个特定字段，而不暴露整个响应式对象
• 避免因解构导致响应性丢失（例如 const { count } = state 会失去响应性，而 const count = toRef(state, 'count') 不会）

toRef 和 toRefs 的区别

toRef 针对单个属性，返回一个 ref；toRefs 则批量处理整个响应式对象的所有顶层属性，返回一个包含多个 ref 的对象。两者都维持响应性，但适用粒度不同：

• toRef(obj, 'name') → 得到一个 ref，值等于 obj.name，且与 obj.name 同步
• toRefs(obj) → 得到 { name: ref(obj.name), age: ref(obj.age) }，适合整体解构

典型使用示例

假设有一个 reactive 用户状态：

vue-component-analyzer

递归分析 Vue 项目组件依赖，从入口文件生成组件层级图，支持 Vue 2/3，输出组件名、文件路径和属性。适用于分析组件结构、排查依赖或了解项目架构。

下载

立即学习“前端免费学习笔记（深入）”；

const user = reactive({ name: 'Alice', age: 28 })

想单独操作 name 并确保响应性：

• const nameRef = toRef(user, 'name') —— nameRef.value 变化时，user.name 自动更新
• 可直接传给子组件：<Child :name="nameRef" />，子组件接收的是 ref，内部修改会影响父级 user.name
• 也可用于 watch：watch(nameRef, (newVal) => console.log(newVal))

注意点：toRef 不适用于普通对象

toRef 依赖源对象是响应式的（reactive、ref 或 Vue 创建的响应式代理）。对普通 JS 对象调用 toRef 不会建立响应链接，只是返回一个普通 ref：

• ❌ const plain = { x: 1 }; const xRef = toRef(plain, 'x') → xRef.value 修改不会影响 plain.x
• ✅ const state = reactive({ x: 1 }); const xRef = toRef(state, 'x') → 同步生效