Vue 3 响应式进阶：掌握 toRef 与 toRefs，告别解构陷阱

前言

在 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 } = state

const 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 对象，逻辑层需要使用 .value
  count.value++
}
</script>

<template>
  <div>
    <h1>{{ title }}</h1>
    <p>当前数值：{{ count }}</p>
    <button @click="increment">点击增加</button>
  </div>
</template>

---

3. toRef：精准提取单个属性

toRef 则是为响应式对象中的某一个属性创建一个 ref。

适用场景

1. 只需提取对象中的一个属性。
2. 当该属性在源对象中可能不存在时（它会创建一个可用的引用）。
3. 将父组件传入的 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. 最佳实践总结

1. 组合式函数（Composables）的返回：在编写自定义 Hook 时，推荐返回 ...toRefs(state)，这样外部解构时非常方便且不会丢失响应式。
2. Props 处理：当需要修改 Props 的某个属性（通过 emit）或将其传递给另一个逻辑函数时，使用 toRef(props, 'xxx')。
3. 谨记.value：一旦使用了这两个工具，在 <script setup> 的逻辑部分操作变量时，千万别忘了加 .value。