vue3 toref和torefs的使用及区别

最新推荐文章于 2025-04-28 08:47:20 发布

原创最新推荐文章于 2025-04-28 08:47:20 发布

· 2.2k 阅读

13 ·

版权

文章标签：

#前端 #javascript #vue.js

vue3学习笔记专栏收录该内容

19 篇文章

订阅专栏

本文介绍了Vue中的toRef和toRefs函数，分别用于将响应式对象的单个属性或整个对象转换为Ref对象，以便于读写和保持数据同步。toRef处理单个属性，toRefs处理整个对象，两者在不同场景下提供灵活性和便利性。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

一. toRef

toRef 函数可以将一个响应式对象的属性转换为一个独立的 ref 对象。
返回的是一个指向源对象属性的 ref 引用，任何对该引用的修改都会同步到源对象属性上。
使用 toRef 时需要传入源对象和属性名作为参数。

先看这个转换单个字段的 toRef API ，了解了它的用法之后，再去看 toRefs 就很容易理解了。
API 类型和基本用法
toRef API 的 TS 类型如下：

// `toRef` API 的 TS 类型
function toRef<T extends object, K extends keyof T>(
  object: T,
  key: K,
  defaultValue?: T[K]
): ToRef<T[K]>

// `toRef` API 的返回值的 TS 类型
type ToRef<T> = T extends Ref ? T : Ref<T>

通过接收两个必传的参数（第一个是 reactive 对象, 第二个是要转换的 key ），返回一个 Ref 变量，在适当的时候也可以传递第三个参数，为该变量设置默认值。
以上文声明好的 userInfo 为例，如果想转换 name 这个字段为 Ref 变量，只需要这样操作：

const name = toRef(userInfo, 'name')
console.log(name.value) // Petter

等号左侧的 name 变量此时是一个 Ref 变量,所以之后在读取和赋值时，就需要使用 name.value 来操作，在重新赋值时会同时更新 name 和 userInfo.name 的值：

// 修改前先查看初始值
const name = toRef(userInfo, 'name')
console.log(name.value) // Petter
console.log(userInfo.name) // Petter

// 修改 Ref 变量的值，两者同步更新
name.value = 'Tom'
console.log(name.value) // Tom
console.log(userInfo.name) // Tom

// 修改 Reactive 对象上该属性的值，两者也是同步更新
userInfo.name = 'Jerry'
console.log(name.value) // Jerry
console.log(userInfo.name) // Jerry

这个 API 也可以接收一个 Reactive 数组，此时第二个参数应该传入数组的下标：

// 这一次声明的是数组
const words = reactive(['a', 'b', 'c'])

// 通过下标 `0` 转换第一个 item
const a = toRef(words, 0)
console.log(a.value) // a
console.log(words[0]) // a

// 通过下标 `2` 转换第三个 item
const c = toRef(words, 2)
console.log(c.value) // c
console.log(words[2]) // c

设置默认值
如果 Reactive 对象上有一个属性本身没有初始值，也可以传递第三个参数进行设置（默认值仅对 Ref 变量有效）：

interface Member {
  id: number
  name: string
  // 类型上新增一个属性，因为是可选的，因此默认值会是 `undefined`
  age?: number
}

// 声明变量时省略 `age` 属性
const userInfo: Member = reactive({
  id: 1,
  name: 'Petter',
})

// 此时为了避免程序运行错误，可以指定一个初始值
// 但初始值仅对 Ref 变量有效，不会影响 Reactive 字段的值
const age = toRef(userInfo, 'age', 18)
console.log(age.value)  // 18
console.log(userInfo.age) // undefined

// 除非重新赋值，才会使两者同时更新
age.value = 25
console.log(age.value)  // 25
console.log(userInfo.age) // 25

数组也是同理，对于可能不存在的下标，可以传入默认值避免项目的逻辑代码出现问题：

const words = reactive(['a', 'b', 'c'])

// 当下标对应的值不存在时，也是返回 `undefined`
const d = toRef(words, 3)
console.log(d.value) // undefined
console.log(words[3]) // undefined

// 设置了默认值之后，就会对 Ref 变量使用默认值， Reactive 数组此时不影响
const e = toRef(words, 4, 'e')
console.log(e.value) // e
console.log(words[4]) // undefined

二. toRefs

toRefs 函数可以将一个响应式对象转换为一个普通的对象，该对象的每个属性都是独立的 ref 对象。
返回的对象可以进行解构，每个属性都可以像普通的 ref 对象一样访问和修改，而且会保持响应式的关联。
toRefs 的使用场景主要是在将响应式对象作为属性传递给子组件时，确保子组件可以正确地访问和更新这些属性。

API 类型和基本用法

function toRefs<T extends object>(
  object: T
): {
  [K in keyof T]: ToRef<T[K]>
}

type ToRef = T extends Ref ? T : Ref<T>

与 toRef 不同， toRefs 只接收了一个参数，是一个 reactive 变量。

interface Member {
  id: number
  name: string
}

// 声明一个 Reactive 变量
const userInfo: Member = reactive({
  id: 1,
  name: 'Petter',
})

// 传给 `toRefs` 作为入参
const userInfoRefs = toRefs(userInfo)

此时这个新的 userInfoRefs 变量，它的 TS 类型就不再是 Member 了，而应该是：

// 导入 `toRefs` API 的类型
import type { ToRefs } from 'vue'

// 上下文代码省略...

// 将原来的类型传给 API 的类型
const userInfoRefs: ToRefs<Member> = toRefs(userInfo)

也可以重新编写一个新的类型来指定它，因为每个字段都是与原来关联的 Ref 变量，所以也可以这样声明：

// 导入 `ref` API 的类型
import type { Ref } from 'vue'

// 上下文代码省略...

// 新声明的类型每个字段都是一个 Ref 变量的类型
interface MemberRefs {
  id: Ref<number>
  name: Ref<string>
}

// 使用新的类型进行声明
const userInfoRefs: MemberRefs = toRefs(userInfo)

当然实际上日常使用时并不需要手动指定其类型， TypeScript 会自动推导，可以节约非常多的开发工作量。

和 toRef API 一样，这个 API 也是可以对数组进行转换：

const words = reactive(['a', 'b', 'c'])
const wordsRefs = toRefs(words)

此时新数组的类型是 Ref[] ，不再是原来的 string[] 类型。
解构与赋值
转换后的 Reactive 对象或数组支持 ES6 的解构，并且不会失去响应性，因为解构后的每一个变量都具备响应性。

// 为了提高开发效率，可以直接将 Ref 变量直接解构出来使用
const { name } = toRefs(userInfo)
console.log(name.value) // Petter

// 此时对解构出来的变量重新赋值，原来的变量也可以同步更新
name.value = 'Tom'
console.log(name.value) // Tom
console.log(userInfo.name) // Tom

这一点和直接解构 Reactive 变量有非常大的不同，直接解构 Reactive 变量，得到的是一个普通的变量，不再具备响应性。

这个功能在使用 Hooks 函数非常好用（在 Vue 3 里也叫可组合函数， Composable Functions ），还是以一个计算器函数为例，这一次将其修改为内部有一个 Reactive 的数据状态中心，在函数返回时解构为多个 Ref 变量：

import { reactive, toRefs } from 'vue'

function useCalculator() {
  const obj = reactive({
    num: 0,
    step: 10,
  })
  function add() {
    obj.num += state.step
  }
  return {
    ...toRefs(obj),
    add,
  }
}