Vue3响应式数据实战：ref vs toRef vs toRefs，你真的会用吗？

原创

于 2026-03-08 10:20:15 发布 · 408 阅读

标签

#Vue3 #响应式 #前端开发 #Composition API #ViewUI

Vue3响应式数据实战：ref vs toRef vs toRefs，你真的会用吗？

在Vue 3的Composition API世界里，ref、toRef和toRefs这三个API就像工具箱里不同规格的螺丝刀，看似都能拧螺丝，但用错了场景，要么使不上劲，要么把螺丝拧花。很多开发者，尤其是从Vue 2迁移过来或者刚接触Composition API的朋友，常常会陷入选择困难：这个数据我到底该用哪个API来声明？为什么有时候用.value，有时候又不用？toRef和toRefs看起来很像，区别到底在哪？

这篇文章不会重复官方文档的干瘪定义，而是从实战场景和性能心智模型出发，通过一系列具体的代码对比和背后的原理剖析，帮你彻底理清这三者的适用边界。我们会探讨如何根据数据来源（本地状态、Props、异步数据）、数据结构（原始值、对象、嵌套对象）以及使用场景（模板、组合函数、状态管理）来做出最合适的选择，从而写出更清晰、更高效、更易于维护的Vue 3代码。

1. 理解核心：响应式引用的本质差异

在深入对比之前，我们必须建立一个正确的认知：ref、toRef和toRefs虽然都创建了“响应式引用”，但它们创建的“引用”性质截然不同。这种差异直接决定了它们的使用方式和适用场景。

1.1 `ref`：创建独立的响应式容器

你可以把 ref 想象成一个自带包装盒的礼物。无论你放进去的是什么（一个字符串、一个数字，甚至是一个复杂的对象），ref 都会为这个值创建一个全新的、独立的响应式包装。这个包装盒（即 ref 对象）有一个 .value 属性，用来存取里面的实际礼物。

import { ref } from 'vue';

// 包装一个原始值
const count = ref(0);
console.log(count.value); // 0
count.value++; // 修改需要通过 .value

// 包装一个对象
const user = ref({ name: 'Alice', age: 25 });
console.log(user.value.name); // Alice
user.value.age = 26; // 修改嵌套属性

关键特性：

独立性：ref 创建的是一个全新的响应式对象，与原始数据源（如果传入的是对象）是“深拷贝”后的关系吗？不完全是，它是对传入值的响应式代理，但容器本身是独立的。
.value 访问：在 JavaScript 中，你必须通过 .value 来读写其内部值。这是 ref 最显著的语法特征。
适用场景：最适合用于声明组件的本地响应式状态，尤其是当这个状态的初始值可能很简单，或者来源不确定（如异步获取）时。

注意：在模板中，ref 会被自动解包，你无需书写 .value。这是 Vue 提供的语法糖，但在 <script setup> 或 setup() 函数内的 JS/TS 逻辑中，.value 是必须的。

1.2 `toRef`：建立到源对象属性的单向链接

toRef 的作用完全不同。它不为数据创建新的包装盒，而是为源响应式对象（通常是 reactive 创建的对象）的某个特定属性，制作一个“提手”或“指针”。这个提手（toRef 返回的对象）指向源对象属性的存储位置。

import { reactive, toRef } from 'vue';

const state = reactive({ name: 'Bob', score: 100 });

// 为 `state.name` 创建一个引用（指针）
const nameRef = toRef(state, 'name');

console.log(nameRef.value); // 'Bob'
// 通过指针修改，源对象会同步变化
nameRef.value = 'Charlie';
console.log(state.name); // 'Charlie'

// 反之亦然，修改源对象，指针指向的值也变
state.name = 'David';
console.log(nameRef.value); // 'David'

关键特性：

链接性/非独立性：toRef 创建的引用与源对象的特定属性保持链接。修改任何一方，另一方都会同步更新。它不持有数据的所有权，只是数据的“访问代理”。
.value 访问：同样需要通过 .value 访问，但其 .value 的 getter/setter 直接操作源对象的属性。
核心用途：主要用于将 reactive 对象的某个属性单独提取出来，传递给需要 ref 格式参数的组合式函数或进行解构，同时保持响应性。