Vue 3 源码阅读笔记：ref.ts

文章目录一、文件概览二、核心数据结构1. Ref 接口定义三、核心函数实现1. isRef - 类型守卫2. r[ReactiveFlags.IS_REF]详解一、 r[ReactiveFlags.IS_REF] 是什么意思二、这个标记是怎么来的三、为什么需要这个标记四、完整的标记系统五、为什么用不 Symbol 而用字符串六、手写简化版来理解七、总结2. ref - 主入口函数源码解析2.1 [T] extends [Ref] 详解2.2 条件分支一IfAnyT, RefT, T详解2.3 条件分支二RefUnwrapRefT, UnwrapRefT | T详解3. shallowRef - 浅层响应式 ref 的实现一、文件概览元数据说明文件路径packages/reactivity/src/ref.ts核心功能实现 Vue 3 的 ref 相关 API依赖模块vue/shared,./dep,./reactive导出 APIref,shallowRef,isRef,unref,toRef,toRefs,customRef,triggerRef二、核心数据结构1. Ref 接口定义export interface RefT any, S T { get value(): T // 读取时返回类型 T set value(_: S) // 写入时接受类型 S默认等于 T [RefSymbol]: true // 唯一类型标记用于类型识别 }我的理解使用两个泛型参数T和S是为了支持只读场景S never[RefSymbol]: true是一个类型层面的标记编译后消失为什么这样设计这样可以精确控制 ref 的读写类型比如计算属性可以是只读的三、核心函数实现1. isRef - 类型守卫export function isRef(r: any): r is Ref { return r ? r[ReactiveFlags.IS_REF] true : false }源码解析类型谓词r is Ref告诉 TypeScript如果返回 true则 r 是 Ref 类型内部标记ReactiveFlags.IS_REF __v_isRef每个 ref 实例上都有这个属性为什么不用 instanceof因为对象可能被 Proxy 代理原型链会丢失笔记// 使用示例 const count ref(0) console.log(isRef(count)) // true console.log(isRef(100)) // false2.r[ReactiveFlags.IS_REF]详解一、r[ReactiveFlags.IS_REF]是什么意思1. 基本概念// packages/reactivity/src/constants.ts export enum ReactiveFlags { SKIP __v_skip, IS_REACTIVE __v_isReactive, IS_READONLY __v_isReadonly, IS_SHALLOW __v_isShallow, RAW __v_raw, IS_REF __v_isRef, }r[ReactiveFlags.IS_REF] true // 等价于 r[__v_isRef] true这行代码的意思是检查对象r上是否有__v_isRef**这个属性并且它的值是否为 **true。2. 为什么用__v_isRef这种奇怪的属性名__v_是 Vue 内部属性的命名约定v 代表 Vue这样做是为了避免和用户自定义的属性名冲突用户几乎不可能恰好定义一个叫__v_isRef的属性二、这个标记是怎么来的在RefImpl类中设置的// packages/reactivity/src/ref.ts class RefImplT { private _value: T public dep?: Dep undefined // 重点在这里这个标记是在创建 ref 时自动添加的 public readonly [ReactiveFlags.IS_REF] true // -- 就是这里 constructor(value: T) { this._value value } get value() { trackRefValue(this) return this._value } set value(newVal) { if (hasChanged(newVal, this._value)) { this._value newVal triggerRefValue(this) } } }每个 ref 对象在创建时都会被自动加上 __v_isRef: true 这个属性。三、为什么需要这个标记1. 快速识别 ref 对象// 假设没有这个标记怎么判断是不是 ref function isRef(r: any) { // 方法1检查构造函数但 Proxy 代理后不行 // 方法2检查有没有 value 属性但普通对象也可能有 value // 方法3检查内部属性最可靠 return r r.__v_isRef true }2. 运行时快速判断const count ref(0) const obj { value: 100 } // 普通对象碰巧也有 value console.log(isRef(count)) // true因为有 __v_isRef console.log(isRef(obj)) // false没有 __v_isRef console.log(isRef(null)) // false3. 在响应式系统中做特殊处理// 在 reactive 中遇到 ref 时会自动解包 function reactive(target) { return new Proxy(target, { get(target, key, receiver) { const res Reflect.get(target, key, receiver) // 重点如果获取到的值是一个 ref自动返回 .value if (isRef(res)) { return res.value // 自动解包 } return res } }) } // 使用时的效果 const count ref(0) const state reactive({ count: count // 传入 ref }) console.log(state.count) // 0直接拿到值不需要 .value // 这全靠 __v_isRef 标记来判断四、完整的标记系统Vue 用了多个类似的标记export enum ReactiveFlags { SKIP __v_skip, // 跳过响应式转换 IS_REACTIVE __v_isReactive, // 是否是 reactive 对象 IS_READONLY __v_isReadonly, // 是否是 readonly 对象 IS_SHALLOW __v_isShallow, // 是否是 shallow 对象 RAW __v_raw, // 获取原始对象 IS_REF __v_isRef, // 是否是 ref 对象 }其他标记的使用// reactive 对象也有自己的标记 class ReactiveProxy { public readonly [ReactiveFlags.IS_REACTIVE] true public readonly [ReactiveFlags.RAW] this.target // ... } // 使用 const state reactive({ count: 0 }) console.log(state[ReactiveFlags.IS_REACTIVE]) // true console.log(isReactive(state)) // true内部就是检查这个标记五、为什么用不 Symbol 而用字符串你可能会想为什么不用 Symbol 而用字符串// 理论上可以用 Symbol export const IS_REF Symbol(vue.isRef) // 但 Vue 选择了字符串为什么字符串的好处可序列化字符串可以在 JSON 中传输调试友好__v_isRef在控制台直接可见跨框架边界如果 ref 传到其他框架字符串属性仍然存在简单可靠兼容性更好// 控制台直接查看 const count ref(0) console.log(count) // 可以直接看到 __v_isRef: true // 如果是 Symbol控制台显示 [Symbol()]: true可读性差六、手写简化版来理解// 1. 定义标记常量 const IS_REF __v_isRef // 2. 实现 ref class MyRefT { private _value: T // 添加标记 readonly [IS_REF] true constructor(value: T) { this._value value } get value() { return this._value } set value(newVal) { this._value newVal } } // 3. 实现 isRef function isRef(r: any): boolean { return r r[IS_REF] true } // 4. 使用 const myRef new MyRef(100) console.log(isRef(myRef)) // true const normalObj { value: 100 } console.log(isRef(normalObj)) // false七、总结问题答案r[ReactiveFlags.IS_REF]是什么访问 ref 对象上的内部标记__v_isRef为什么要判断这个属性快速、可靠地判断一个对象是不是 ref为这个属性哪里来的RefImpl类在创建实例时自动添加的为什么不用instanceofProxy 代理后会丢失原型链而且跨 iframe 不工作为什么用字符串可序列化、调试友好、简单可靠通俗理解这就像给每个 ref 对象贴了一个我是 ref的防伪标签。isRef函数就是检查这个标签存不存在、是不是真。这种方式比instanceof更可靠因为即使对象被 Proxy 代理、被传到不同的 iframe、甚至被序列化后再解析这个字符串属性依然存在。2. ref - 主入口函数export function refT( value: T, ): [T] extends [Ref] ? IfAnyT, RefT, T : RefUnwrapRefT, UnwrapRefT | T export function refT any(): RefT | undefined export function ref(value?: unknown) { return createRef(value, false) // 第二个参数 false 表示非浅层 ref }源码解析重载作用第一个处理传入值的情况防止嵌套 ref第二个处理不传参的情况创建值为 undefined 的 ref实现体统一调用 createRef重点理解[T] extends [Ref]检查 T 是否已经是 Ref 类型避免创建RefRefIfAnyT, RefT, T如果 T 是 any返回 Ref否则返回 T 本身UnwrapRefT递归解包嵌套的 ref2.1 [T] extends [Ref] 详解[T] extends [Ref] 是什么意思它是TS的条件类型意思是判断类型 T 是否是 Ref 类型。1. 基本语法[T] extends [Ref] ? A : B2. 为什么用[T]而不是T目的避免联合类型的分发做严格的一次性判断// 如果直接写 T extends Ref type Test1T T extends Ref ? true : false // 当 T string | Ref 时会分别判断 // string extends Ref? false // Ref extends Ref? true // 结果boolean联合类型 // 用 [T] extends [Ref] type Test2T [T] extends [Ref] ? true : false // 当 T string | Ref 时作为整体判断 // [string | Ref] 是不是 [Ref] 的子类型否 // 结果false2.2 条件分支一IfAnyT, RefT, T详解我的追问为什么[T] extends [Ref]为true不就说明T是Ref类型了吗为什么还需要判断T是否是any并给any类型包装Ref这样不会造成重复包装吗关键在于[T] extends [Ref]为 true 时T可能是Ref也可能是any为什么会有 any 的情况// 场景传入 any const value: any 123 const refAny ref(value) // T any // 此时判断 [any] extends [Ref] 是 true 还是 falseTypeScript 中 any 的特殊性// any 可以赋值给任何类型 let x: any 123 let y: string x // ✅ 允许any 可以赋值给 string // 所以 type Test [any] extends [Ref] ? true : false // true // 因为 any 可以当作 Ref 来用尽管实际不是用代码验证// 写个简单的类型测试 type IsRefT [T] extends [Ref] ? true : false // 测试1真正的 ref type Test1 IsRefRefnumber // true ✅ // 测试2any type Test2 IsRefany // true ✅any 万能匹配 // 测试3普通类型 type Test3 IsRefnumber // false type Test4 IsRefstring // false问题就在这里any会让[T] extends [Ref]也返回 trueIfAny 的作用// IfAny 的定义来自 vue/shared type IfAnyT, Y, N 0 extends (1 T) ? Y : N // 这是一个判断 T 是否是 any 的类型工具如果不判断 any// 假设没有 IfAny直接返回 T function badRefT(value: T): [T] extends [Ref] ? T : RefT { // ... } const value: any 123 const result badRef(value) // 返回类型any // 类型丢失我们不知道这是个 ref 了为什么不能直接返回 Ref// 如果直接返回 RefT function badRefT(value: T): [T] extends [Ref] ? RefT : RefT { // ... } // 问题1传入真正的 ref 时 const count ref(0) const result badRef(count) // RefRefnumber ❌ 嵌套了 // 问题2传入 any 时 const val: any 123 const result2 badRef(val) // Refany ✅ 这个是对的 // 问题3传入普通值时 const num 123 const result3 badRef(num) // Refnumber ✅ 这个也是对的所以需要分支处理传入真正 ref 时 → 返回 T 本身防止嵌套传入 any 时 → 返回 Ref保留 ref 信息总结传入值T 的类型[T] extends [Ref]IfAny 结果最终类型ref(0)Refnumbertrue不是 any → 返回 TRefnumberany值anytrue是 any → 返回RefanyRefany123numberfalse-Refnumber关键点[T] extends [Ref]为 true 时T 可能是真正的 ref也可能是 anyIfAny用来区分这两种情况真正 ref 要返回本身防止嵌套any 要包装成 Ref保留信息2.3 条件分支二RefUnwrapRefT, UnwrapRefT | T详解[T] extends [Ref] 为 falseT 不是 Ref: RefUnwrapRefT, UnwrapRefT | T // 创建一个 Ref值的类型要经过 UnwrapRef 处理RefUnwrapRefT, UnwrapRefT | T的含义RefUnwrapRefT, UnwrapRefT | T // 第一个参数读取类型UnwrapRefT // 第二个参数写入类型UnwrapRefT | TUnwrapRef 是什么定义export type UnwrapRefT T extends Refinfer V ? UnwrapRefSimpleV : UnwrapRefSimpleTUnwrapRef 的作用递归地解包嵌套的 ref// 基本类型 type A UnwrapRefnumber // number type B UnwrapRefstring // string // 一层 ref type C UnwrapRefRefnumber // number解包了 // 嵌套 ref type D UnwrapRefRefRefnumber // number递归解包 // 对象中的 ref type E UnwrapRef{ count: Refnumber } // { count: number }对象属性也被解包UnwrapRef 定义详解先看整体结构这是 TypeScript 的递归类型解包export type UnwrapRefT T extends Refinfer V ? UnwrapRefSimpleV : UnwrapRefSimpleT这是一个条件类型意思是如果 T 是一个 Ref 类型就解包出它里面的值 V然后递归处理 V如果 T 不是 Ref 类型就直接用 UnwrapRefSimple 处理 T拆解关键语法T extends Refinfer V这是 TypeScript 的模式匹配语法// 假设有一个 Ref 类型 type RefT { value: T } // infer V 的意思是把 Ref 里面的类型提取出来命名为 V type GetRefValueT T extends Refinfer V ? V : never // 使用 type A GetRefValueRefnumber // number提取出来了 type B GetRefValuestring // never不是 RefUnwrapRefSimpleV这是另一个类型工具用来处理非 Ref 类型的解包比如对象、数组等执行流程示例例子1基本类型type T1 UnwrapRefnumber // number 不是 Ref → 走第二支UnwrapRefSimplenumber // 结果number例子2一层 Reftype T2 UnwrapRefRefnumber // Refnumber 是 Ref → 走第一支UnwrapRefSimplenumber // 结果number例子3嵌套 Reftype T3 UnwrapRefRefRefnumber // 第一次RefRefnumber 是 Ref → 提取 V Refnumber // 调用 UnwrapRefSimpleRefnumber // UnwrapRefSimple 内部又会调用 UnwrapRef递归 // 第二次Refnumber 是 Ref → 提取 V number // 调用 UnwrapRefSimplenumber // 结果number例子4对象包含 Reftype T4 UnwrapRef{ count: Refnumber } // { count: Refnumber } 不是 Ref → 走第二支 // UnwrapRefSimple{ count: Refnumber } // UnwrapRefSimple 会遍历对象属性对每个属性递归调用 UnwrapRef // 最终{ count: number }配合 UnwrapRefSimple 看export type UnwrapRefSimpleT T extends Builtin ? T : // 基本类型直接返回 T extends Mapinfer K, infer V ? MapK, UnwrapRefSimpleV : // Map 特殊处理 T extends Setinfer V ? SetUnwrapRefSimpleV : // Set 特殊处理 T extends object ? { [P in keyof T]: UnwrapRefT[P] } : // 对象递归解包 T完整流程示例type Test UnwrapRef{ count: Refnumber, user: { name: Refstring, age: number }, tags: RefSetRefstring } // 执行过程 // 1. { count: Ref... } 不是 Ref → UnwrapRefSimple // 2. 遍历对象属性 // - count: UnwrapRefRefnumber → number // - user: UnwrapRef{ name: Refstring, age: number } // → 递归处理 user 对象 // * name: UnwrapRefRefstring → string // * age: number → number // - tags: UnwrapRefRefSetRefstring // → 提取 SetRefstring // → UnwrapRefSimpleSetRefstring // → 处理 SetSetUnwrapRefSimpleRefstring // → UnwrapRefSimpleRefstring → string // → 最终Setstring // 结果 { count: number, user: { name: string, age: number }, tags: Setstring }为什么需要递归解包没有递归解包导致的问题// 假设只有一层解包 type ShallowUnwrapT T extends Refinfer V ? V : T const obj ref({ user: ref({ name: ref(vue) }) }) // 使用时 obj.value.user // 类型还是 Ref{ name: Refstring } ❌ obj.value.user.value.name.value // 要写一堆 .value有递归解包const obj ref({ user: ref({ name: ref(vue) }) }) // 使用时 obj.value.user.name // 直接是 string✅ // 所有层级的 ref 都被自动解开了类比理解把UnwrapRef想象成一个剥洋葱的过程// 洋葱RefRefRefnumber UnwrapRefRefRefRefnumber // 第一层发现是 Ref → 剥开得到 RefRefnumber // 第二层发现还是 Ref → 再剥开得到 Refnumber // 第三层发现还是 Ref → 再剥开得到 number // 结果number把UnwrapRefSimple想象成处理各种食材的工具基本类型Builtin→ 直接吃Map/Set → 特殊处理对象 → 每个属性都剥一遍其他 → 保持原样回到RefUnwrapRefT, UnwrapRefT | TRefUnwrapRefT, UnwrapRefT | T // 第一个参数读取类型UnwrapRefT // 第二个参数写入类型UnwrapRefT | T为什么写入类型要允许两种看例子理解例子传入普通值const count ref(0) // T number // RefUnwrapRefnumber, UnwrapRefnumber | number // Refnumber, number | number // Refnumber, number count.value 10 // ✅ 写入 number count.value 20 // ❌ 类型错误只能写 number例子赋值带 ref 的对象const state ref({ name: ref(vue), age: ref(3) }) // 类型Ref{ name: string, age: number }, // { name: string, age: number } | { name: Refstring, age: Refnumber } // 读取时自动解包 console.log(state.value.name) // string // 写入时两种都支持 state.value { name: react, age: 10 } // ✅ 普通对象 state.value { name: ref(angular), age: ref(5) } // ✅ 带 ref 的对象如果不这样设计会怎样方案A只允许 UnwrapRefRefUnwrapRefT, UnwrapRefT // 写入只能写解包后的类型 const obj ref({ count: ref(0) }) obj.value { count: 10 } // ✅ 可以 obj.value { count: ref(20) } // ❌ 类型错误不能写 ref // 但有时我们需要写入 ref比如从另一个 ref 赋值方案B只允许 TRefUnwrapRefT, T // 写入只能写原始类型 const obj ref({ count: ref(0) }) obj.value { count: ref(20) } // ✅ 可以 obj.value { count: 10 } // ❌ 类型错误不能写普通值 // 但大多数时候我们从 API 拿到的是普通对象Vue 的方案两者都允许RefUnwrapRefT, UnwrapRefT | T // 两种都支持 // 既可以从 API 赋值普通对象 // 也可以从其他 ref 赋值总结参数作用为什么这样设计UnwrapRefT读取类型让使用者直接拿到解包后的值方便使用UnwrapRefT或T写入类型既支持普通对象也支持带 ref 的对象更灵活通俗理解读取时Vue 帮你把里面的 ref 都解开了你直接拿值用写入时Vue 很宽容你想传普通对象也行想传带 ref 的对象也行这就是 Vue 响应式系统读取方便写入灵活的设计哲学3. shallowRef - 浅层响应式 ref 的实现持续更新中未完待续~