前言
在 Vue 3 的组合式 API 中，reactive 为我们提供了强大的深度响应式能力。然而，很多开发者在享受解构（Destructuring）带来的代码简洁感时，往往会掉进一个“响应式丢失”的陷阱。
为了解决这个问题，Vue 3 官方提供了 toRef 和 toRefs 两个工具函数。今天我们就来彻底聊聊它们的作用、区别以及在 <script setup> 中的实战用法。
1. 痛点：为什么不能直接解构？
在 JavaScript 中，解构赋值对于基本数据类型（如数字、字符串）是值拷贝。
<script setup>
import { reactive } from 'vue'const state = reactive({count: 0
})// ❌ 错误做法：响应式丢失！
// 此时 count 只是一个单纯的数字 0，它脱离了 state 对象的追踪
let { count } = stateconst add = () => {count++ // 视图不会更新，state.count 也不会变
}
</script>为了既能享受解构的便利，又不丢失响应式连接，toRef 和 toRefs 闪亮登场。
2. toRefs：批量转换的利器
toRefs 的作用是将一个响应式对象（reactive）转换为一个普通对象，但这个普通对象的每个属性都是指向原始对象属性的 ref。
适用场景
当你希望在模板中直接使用属性名（如 count 而不是 state.count），且需要解构整个对象时。
代码示例
<script setup>
import { reactive, toRefs } from 'vue'const state = reactive({count: 0,title: '我的计数器'
})// ✅ 使用 toRefs 处理后再解构
const { count, title } = toRefs(state)const increment = () => {// 注意：解构出来的是 ref 对象，逻辑层需要使用 .valuecount.value++
}
</script><template><div><h1>{{ title }}</h1><p>当前数值：{{ count }}</p><button @click="increment">点击增加</button></div>
</template>3. toRef：精准提取单个属性
toRef 则是为响应式对象中的某一个属性创建一个 ref。
适用场景
- 只需提取对象中的一个属性。
- 当该属性在源对象中可能不存在时（它会创建一个可用的引用）。
- 将父组件传入的
props中的某个属性转换后传给其他函数。
代码示例
<script setup>
import { reactive, toRef } from 'vue'const user = reactive({name: '张三',age: 18
})// ✅ 只提取 age 属性
const ageRef = toRef(user, 'age')const growUp = () => {ageRef.value++ // 依然保持与 user.age 的同步
}
</script>4. 核心区别：一图胜千言
| 特性 | toRef |
toRefs |
|---|---|---|
| 参数 | (object, key) |
(object) |
| 返回值 | 单个 ref |
包含多个 ref 的普通对象 |
| 操作对象 | 针对对象中的某个特定键 | 针对对象中的所有键 |
| 主要用途 | 属性传递、可选属性处理 | 简化模板变量、安全解构 |
5. 深度思考：为什么不直接用 ref()？
这是面试中常问的问题。看下面的对比：
const state = reactive({ count: 0 })// 方式 A
const countA = ref(state.count) // 方式 B
const countB = toRef(state, 'count')- 方式 A (
ref)：相当于ref(0)。它创建了一个全新的响应式对象，与state.count彻底断开了联系。修改countA，state.count不会变。 - 方式 B (
toRef)：它只是做了一层引用连接。修改countB.value，原对象state.count也会同步修改。
6. 最佳实践总结
- 组合式函数（Composables）的返回：在编写自定义 Hook 时，推荐返回
...toRefs(state)，这样外部解构时非常方便且不会丢失响应式。 - Props 处理：当需要修改 Props 的某个属性（通过 emit）或将其传递给另一个逻辑函数时，使用
toRef(props, 'xxx')。 - **谨记
.value**：一旦使用了这两个工具，在<script setup>的逻辑部分操作变量时，千万别忘了加.value。