Vue 3 的 toRef、toRefs 与 toRaw

toRef 让属性变成 ref#

toRef(state, 'name') 返回一个 ref，它的 .value 直接读写 state.name。两边是同一份数据，改任何一边另一边都跟着变。

1
const state = reactive({ name: '小明' })
2
const nameRef = toRef(state, 'name')
3

4
nameRef.value = '小红'
5
console.log(state.name)   // 小红
6

7
state.name = '小刚'
8
console.log(nameRef.value) // 小刚

它和 ref(state.name) 不一样。ref 收到的是一个普通字符串，包起来之后就和 state.name 断了联系；toRef 不存值，只是记下对象和属性名，每次都现取。

源对象是不是响应式决定视图更不更新#

toRef 只负责建立读写通道，视图更新与否取决于这条通道底下有没有依赖收集。

源是 reactive 对象时，读 .value 会走代理的 get，触发 track；写 .value 会走 set，触发 trigger，视图跟着更新。

源是普通对象时，读写就是普通的属性访问，没有代理介入，track 和 trigger 都不会发生。数据能改，但视图不会重新渲染。

属性不存在时也能用#

toRef(object, key) 这种写法下，即使源对象当前没有这个属性，也会返回一个可用的 ref。这样就能先处理可选属性，等它后面再出现。

toRefs 做不到这一点：它只遍历调用那一刻已存在的可枚举属性。

props 上的 ref 不能赋值#

把 props 的属性包成 ref 再传给组合式函数是很常见的用法：

1
useSomeFeature(toRef(props, 'foo'))

但 props 是只读的，给这个 ref 赋值等于直接改 prop，Vue 不允许。控制台会给出警告，需要可写的场景要改用带 set 的 computed。

toRefs 批量转换#

toRefs 把对象的每个属性都转成 ref，返回一个普通对象（传数组进去时返回的是数组）。写法上就是遍历一遍，逐个调用内部的属性转换函数。

1
// @__NO_SIDE_EFFECTS__
2
function toRefs(object) {
3
  if (__DEV__ && !isProxy(object)) {
4
    warn(`toRefs() expects a reactive object but received a plain one.`)
5
  }
6
  const ret = shared.isArray(object) ? new Array(object.length) : {}
7
  for (const key in object) {
8
    ret[key] = propertyToRef(object, key)
9
  }
10
  return ret
11
}

上面这段来自 Vue 3.5.43 的 packages/reactivity/src/ref.ts。它有三处容易被忽略的细节。

参数不是代理时，isProxy(object) 为假，开发环境会打印一条警告，提示 toRefs() 期望收到响应式对象。

返回值用 isArray(object) ? new Array(object.length) : {} 分配，所以传数组进去拿到的还是数组，不是普通对象。

循环体调用的是 propertyToRef，不是 toRef。3.5.43 里 propertyToRef 只做一件事：

1
function propertyToRef(source, key, defaultValue) {
2
  return new ObjectRefImpl(source, key, defaultValue)
3
}

枚举不到的属性拿不到 ref#

toRefs 的转换走 for...in，只遍历调用那一刻可枚举的属性。

所以后来才加上去的属性不会有对应的 ref，一开始就不存在的可选属性也不会有。这类属性要用 toRef 单独处理。

另一个后果是 toRefs 只做一层，嵌套对象内部转成的是指向那个对象的 ref，不是把内层属性也铺平。

ObjectRefImpl 的实现#

toRef 返回的对象由 ObjectRefImpl 构造，它不存值，只记下源对象和属性名。下面这个类来自 Vue 3.5.43 的 packages/reactivity/src/ref.ts。

1
class ObjectRefImpl<T extends object, K extends keyof T> {
2
  public readonly __v_isRef = true
3

4
  public _value: T[K] = undefined!
5

6
  private _key: K
7
  private _raw: T
8
  private _shallow: boolean
9

10
  constructor(
11
    private readonly _object: T,
12
    key: K,
13
    private readonly _defaultValue?: T[K],
14
  ) {
15
    this._key = key
16
    this._raw = toRaw(_object)
17

18
    let shallow = true
19
    let obj: any = _object
20

21
    // 数组的整数下标不解包，其余情况逐层检查代理是否需要解包
22
    if (
23
      !shared.isArray(_object) ||
24
      shared.isSymbol(key) ||
25
      !shared.isIntegerKey(key)
26
    ) {
27
      do {
28
        shallow = !isProxy(obj) || isShallow(obj)
29
      } while (shallow && (obj = obj['__v_raw']))
30
    }
31

32
    this._shallow = shallow
33
  }
34

35
  get value(): T[K] {
36
    let val = this._object[this._key]
37
    if (this._shallow) {
38
      val = unref(val)
39
    }
40
    return (this._value = val === undefined ? this._defaultValue : val)
41
  }
42

43
  set value(newVal: T[K]) {
44
    // 浅层时属性本身可能是 ref，赋值要转发进去
45
    if (this._shallow && isRef(this._raw[this._key])) {
46
      const nestedRef = this._object[this._key]
47
      if (isRef(nestedRef)) {
48
        nestedRef.value = newVal
49
        return
50
      }
51
    }
52

53
    this._object[this._key] = newVal
54
  }
55

56
  get dep(): Dep | undefined {
57
    return getDepFromReactive(this._raw, this._key)
58
  }
59
}

这个类里有几个字段，简化版容易漏掉：

_raw：保存 toRaw(_object) 的结果，供 set value 和 dep 使用
_key：构造时传入的属性名
_shallow：这个 ref 是不是浅层的
_defaultValue：构造时传入的默认值，get value 取到 undefined 时回退到它

get value 在浅层情况下会先 unref(val)，所以属性本身是 ref 时会被解包。

set value 有一处分支：属性本身已经是 ref 且当前是浅层时，赋值会转发到那个内层 ref 的 .value，而不是替换属性。这个分支是 3.5.x 之后才加的。

dep 是一个 getter，通过 getDepFromReactive(this._raw, this._key) 到依赖表里找到该属性对应的 Dep。有了它，watch 这类需要拿到依赖对象的内部逻辑才有办法在 ref 上工作。

toRaw 取出原始对象#

toRaw 返回代理背后的原始对象。它读代理上的 __v_raw 标记，拿到之后递归继续取，直到某个值不再带标记为止。

1
// @__NO_SIDE_EFFECTS__
2
function toRaw(observed) {
3
  const raw = observed && observed['__v_raw']
4
  return raw ? toRaw(raw) : observed
5
}

递归这一层有实际意义。readonly 包在 reactive 外面时，代理会套两层，只有一路取到底才能拿到真正的原始对象。

拿到的原始对象不带代理，改它不会触发 trigger，视图不会更新。适合用在不想被追踪、需要交给第三方库、或者调试时对比数据的场景。

三个 API 对照#

API	返回什么	和源的关系
`toRef`	单个属性的 ref	双向同步，不存值
`toRefs`	每个属性一个 ref 的普通对象	双向同步，只覆盖调用时可枚举的属性
`toRaw`	原始对象本身	同一个引用，读写不触发响应式

当海风翻页时

toRef 让属性变成 ref#

源对象是不是响应式决定视图更不更新#

属性不存在时也能用#

props 上的 ref 不能赋值#

toRefs 批量转换#

枚举不到的属性拿不到 ref#

ObjectRefImpl 的实现#

toRaw 取出原始对象#

三个 API 对照#

Vue 3 学习笔记

继续阅读

换条路线

当海风翻页时

toRef 让属性变成 ref#

源对象是不是响应式决定视图更不更新#

属性不存在时也能用#

props 上的 ref 不能赋值#

toRefs 批量转换#

枚举不到的属性拿不到 ref#

ObjectRefImpl 的实现#

toRaw 取出原始对象#

三个 API 对照#

分享文章

沿着主题读

换条路线