跳到正文

Vue 泛型 props 传给 toRefs 时可能丢失类型推断(5):逆向映射推断让 toRefs 保留字段类型

Vue 泛型 props 传给 toRefs 时可能丢失类型推断

  1. 双侧元组中的泛型可能让条件类型延迟求值
  2. 待定的泛型键会让交集上的索引访问延迟求值
  3. 布尔键映射让 toRefs 的数组字段读成 any
  4. 组件可用类型标注或 getter 暂时绕过推断错误
  5. 逆向映射推断让 toRefs 保留字段类型(当前)
  6. 补充内容:LooseRequired 让 props 键必有并保留 undefined
  7. 补充内容:条件求值、赋值和索引访问走不同的检查路径
  8. 补充内容:用泛型上界提前选分支需要额外条件
  9. 补充内容:只改 TypeScript 时需要识别待定索引的数组形状

2026 年 11 月 19 日的补充验证找到了另一条路径:在 toRefs() 调用时逐字段推断输入。候选实现给 toRefs() 增加一个逆向映射重载,原来的直接接收 T 的签名作为回退。DefineProps<T, BKeys>、defineProps() 和 withDefaults() 可以沿用原来的定义。

这条路径在 TypeScript 6.0.3 和 7.0.2 上通过了无约束 T、T extends string | boolean 和原始 T extends string | number 的复现,也通过了泛型结构双向赋值与 Verter 检查。Vue Core PR #16300 已增加后续提交 9490b16be,把修复移到 toRefs() 的输入推断处,并恢复原来的宏类型。原提交保留,PR 仍待上游合并。本文先解释当前候选,再保留此前逐字段修改宏的推导和兼容性探索。

在 toRefs 的参数处推断每个字段

参数类型会影响检查器怎样推断 T。直接接收整个对象和按字段反推,可能给后续的 ToRefs<T> 提供不同的输入。

直接接收 T 会保留原来的交集索引

这里继续用同一份选择器类型。数组里的元素含有泛型,但 options 的外层已经是数组。

// 声明选择器的一个选项。
type Option<T> = { value: T };

// 把候选项和当前值关联到同一个泛型。
type Props<T> = {
  options: readonly Option<T>[];
  value: T;
};

原来的签名把参数直接写成 T,检查器可以把整份 props 类型原样推给它。

declare function toRefs<T extends object>(object: T): ToRefs<T>;

假设 P 是 typeof props,接下来计算的仍然是 ToRefs<P>,其中 options 的类型通过 P['options'] 取得。这个交集索引可能还待定,所以最终会遇到前文讨论的 ToRef 条件。

新的参数类型为推断提供了另一种形状。

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

{ [K in keyof T]: T[K] } 是一个保留字段修饰符的同态映射类型。检查器可以根据传入对象的字段,反向推断映射前的 T。这就是逆向映射推断。options 这一次通过按字段推断得到数组,T 中的这一格可以写成 readonly Option<Value>[],再交给 ToRefs<T>。

这个机制来自 TypeScript 的同态映射推断设计 #12528。检查器在这种推断中把模板内的 T[K] 当作等待推断的字段位置,再拿源对象的字段类型为它提供候选。这里的 T 尚未确定,参数里的索引参与寻找它;等此次推断结束,返回类型才使用得到的 T。

因此,参数里的 T[K] 和返回类型里的 T[K] 虽然写法相同,承担的任务却不同。直接把原来的 props 类型固定为 T,再对返回类型套映射,也不等于重新进行这次参数推断。关于拆箱例子、设计背景和一般 API 的用法,可以看《用逆向映射推断还原字段类型》。

对于这个复现,传入对象原有的 P['options'] 可以继续待定。恢复的是 toRefs() 此次调用所推断出的输入字段,随后 ToRef 得到明确的数组,选择 Ref<数组> 的假分支。value 自己的泛型和布尔条件仍然保留在自己的字段里。

用同一个函数检查无约束泛型与默认值

下面的函数使用无约束 T。在新重载下,两个 item 都能获得 Option<T> 的上下文类型。把函数头改成 T extends string | boolean 或 T extends string | number,两条路径也都通过。

import { defineProps, toRefs, withDefaults } from 'vue';

function inspect<T>() {
  const props = defineProps<Props<T>>();
  const linked = toRefs(props);
  const selected = linked.options.value.find(item => item.value === props.value); // Option<T> | undefined

  const defaulted = withDefaults(defineProps<Props<T> & { label?: string }>(), {
    label: 'Choose',
  });
  const defaultedRefs = toRefs(defaulted);
  const selectedWithDefault = defaultedRefs.options.value.find(item => item.value === defaulted.value); // Option<T> | undefined
}

withDefaults() 的原签名仍可从 DefineProps 推断原始字段和布尔键,默认值工厂也继续取得原始 prop 类型。原来需要额外处理的是它返回的整体交集。逆向映射重载在 toRefs(defaulted) 调用处重新推断各字段,因此这条路径也能恢复数组推断。

DefineProps 本身仍然采用原来的结构。

type DefineProps<T, BKeys extends keyof T> = Readonly<T> & {
  readonly [K in BKeys]-?: boolean;
};

declare function defineProps<TypeProps>(): DefineProps<LooseRequired<TypeProps>, BooleanKey<TypeProps>>;

泛型工具可以继续在 DefineProps<T, K> 和上面那份结构之间双向赋值。Verter 也继续从第二个参数提取布尔键。

三种调用决定 ToRefs 使用哪一份对象类型

逆向映射能够改善这次调用对输入的推断,但调用方显式选择类型参数时,返回类型就沿用那份类型。继续使用前面的 Props<Value>,对照自动推断、指定原类型和指定普通字段形状。

function inspectExplicitType<Value>() {
  const props = defineProps<Props<Value>>(); // 原来的 DefineProps 交集。
  const inferred = toRefs(props); // 对此次调用逐字段推断新的输入类型。
  const fixedOriginal = toRefs<typeof props>(props); // 显式把输入固定为原来的交集。
  const fixedShape = toRefs<{
    readonly options: readonly Option<Value>[];
    readonly value: Value;
  }>(props); // 显式把输入指定为这份普通对象类型。

  const inferredOptions = inferred.options.value; // readonly Option<Value>[]
  const originalOptions = fixedOriginal.options.value; // any
  const shapeOptions = fixedShape.options.value; // readonly Option<Value>[]
}

三种调用传入的是同一个 props,返回类型使用的类型参数却不同。自动调用时,检查器按实参字段推断出 { readonly options: readonly Option<Value>[]; readonly value: Value },再把这份新对象类型交给 ToRefs。Value 仍是泛型,但 options 的外层已经确定是数组。

显式写 <typeof props> 时,调用方已经把类型参数固定为原来的交集。返回类型仍是 ToRefs<typeof props>,其中的待定索引没有消失。参数中的映射用于检查这次调用的输入,不会把返回类型中的参数替换成一份展开后的对象。于是,后续 ToRef 仍可能暴露 Ref 分支中的 any。

第三种调用则直接指定了普通对象形状,它同样能得到数组。这说明差别在于这次调用使用哪一份类型参数。原来的 typeof props 没有被展开,也没有因第一次调用而改变。

调用 交给 ToRefs 的对象类型 options.value
toRefs(props) 根据实参逐字段推断出的新对象类型 readonly Option<Value>[]
toRefs<typeof props>(props) 原来的 props 交集类型 any
toRefs<明确字段形状>(props) 显式指定的普通对象类型 readonly Option<Value>[]

这组三种调用的结果在 TypeScript 6.0.3 和 7.0.2 上一致。候选重载改善的是自动推断路径;它没有改变 ToRefs、ToRef 或编译器对全部交集索引的求值规则。关于参数中的字段如何参与反向推断,可以对照 TypeScript 逆向映射推断篇。

为数字索引保留入口,并接住私有品牌类型

只把参数改成映射类型,还会碰到另一个兼容性问题。Vue 的现有类型测试包含 ShallowReactive 对象,它携带私有品牌属性 __shallowReactiveBrand。映射推断得到的同名普通属性无法替代这份私有身份,单重载版本会在传参时报告 TS2345。

现有用例的核心形状如下。

import { type Ref, ref, shallowReactive, toRefs } from 'vue';

const input = shallowReactive({
  a: { b: ref(42) },
});

const linked = toRefs(input);
const nested = linked.a.value.b; // Ref<number>

完整源码检查还发现了带响应式品牌的数组用例。只保留映射和通用回退时,映射重载可能先匹配成功,却把数组推成只有方法和具名属性的对象,原来的数字索引丢失,访问 linked[0] 会报告 TS7053。Record<number, string> 也需要保留数字索引。

直接在最前面增加数组重载,可以保护数组,却使仓库现有的一个上下文推断用例失败。这个用例把 toRefs(reactive({ state: 'state1' })) 赋给 ToRefs<AppData>。单独增加数组重载后,内层 state 被拓宽为 string,无法再满足目标类型里的字面量联合。

候选改为用条件元组限制数字索引重载。number extends keyof T 成立时,剩余参数是空元组,调用仍然只传一个对象。否则剩余参数是 [never],这条重载无法用普通的单参数调用匹配,具名字段对象继续参与后面的逆向映射推断。

候选声明最终使用三个重载。

// 为数字索引输入保留原类型,条件元组只控制重载匹配。
declare function toRefs<T extends object>(object: T, ..._numericIndex: number extends keyof T ? [] : [never]): ToRefs<T>;

// 对可逐键推断的输入,先恢复各字段的类型。
declare function toRefs<T extends object>(object: {
  [K in keyof T]: T[K];
}): ToRefs<T>;

// 接住带有私有品牌等无法按普通字段重建的对象。
declare function toRefs<T extends object>(object: T): ToRefs<T>;

带数字索引的数组、元组和记录优先沿用自己的输入类型。普通对象匹配第二条时,检查器使用逐键推断得到的 T。第二条因私有品牌等原因无法匹配时,第三条沿用原来的泛型输入。三个重载共用 toRefs() 原来的单参数运行时实现,仍然为同一个响应式对象创建字段 Ref。

这也给出了当前候选的范围:上面的三类普通泛型 props 已经通过。带私有品牌的输入可以继续走原签名;如果它同时含有待定的交集索引,是否仍能恢复字段,需要另取对应输入验证,不能把回退重载理解成任何输入都会被规范化。

四种方案的类型检查结果

以下对照于 2026 年 11 月 19 日在 TypeScript 6.0.3、7.0.2 的 strict 模式下执行。每个推断用例都同时包含普通 defineProps() 和经过 withDefaults() 的路径。表中的泛型结构赋值指两个类型参数都未实例化时的双向赋值。

检查项 原声明 已提交的逐字段宏方案 布尔交集提前排除方案 toRefs 逆向映射重载
T extends string | number 的数组推断 TS7006 通过 通过 通过
无约束 T 的数组推断 TS7006 通过 TS7006 通过
T extends string | boolean 的数组推断 TS7006 通过 TS7006 通过
泛型结构双向赋值 通过 TS2322 通过 通过
Verter 布尔键提取 通过 通过 通过 通过

表格中的联合类型按同一个泛型约束理解。具体用例、声明方案和 40 组检查结果保存在方案验证记录弹窗中。Verter 的宏类型重新生成和消费检查也在两个 TypeScript 版本上通过。

Vue 原有的 pnpm test-dts 使用 TypeScript 6.0.3,完整检查通过,pnpm check 的源码类型检查也通过。新增回归覆盖无约束泛型、可能为布尔值的泛型、泛型双向赋值、默认值、只读字段、可选字段、Symbol 键、普通及响应式数组、只读及响应式元组、索引签名、联合对象和泛型对象透传。已有浅响应式用例验证了回退重载,响应式 ref.spec.ts 的 38 个运行时测试也通过。

把整个源码仓库的类型测试改用 TypeScript 7.0.2 时,原基线和候选都会在 defineComponent、FunctionalComponent 和 defineModel 的用例中报告相同的 9 条诊断。因此,这里的 TypeScript 7 结论限定为上述定向用例和下游验证。

逐字段宏方案的推导与兼容性探索

下面保留首个提交 5bf0ab0d2 中的宏方案。它展示了从源头逐字段计算为何能恢复推断,也记录了内部标记、下游类型提取和泛型结构赋值之间的取舍。后续提交已经恢复原宏定义;这一段用于解释方案取舍。最后再对照布尔交集提前排除方案,以及单独套一层映射为什么不足以覆盖全部用例。

原写法让 options 带上了 value 的条件

先定义一个只有两个字段的选择器。选中的 value 是 T,每一项也含有一个 T,但 options 的外层结构已经明确是数组。下面用 TypeScript 6.0.3 的 --strict 检查。旧写法用 Vue 3.6.0-rc.15 的发布声明,修复写法用逐字段宏方案。普通 .ts 里的函数只用于观察泛型类型,实际组件把宏写在 <script setup> 顶层。

import { type DefineProps, defineProps, type Ref, toRefs, withDefaults } from 'vue';

// 声明选择器的原始字段。
type Option<T> = { value: T };
type Props<T> = {
  options: readonly Option<T>[];
  value: T;
};

// 单独观察 ToRef 的内层条件:输入是否已经是 Ref。
type IsExistingRef<X> = [X] extends [Ref] ? true : false;

旧声明先筛出一份布尔键

旧签名把完整的只读 props 和布尔字段映射取交集。选择器的数组字段 options 可以先排除,待定的只剩 value 的布尔条件。此时键集合的上界已知是 'value',但 Expanded['options'] 仍要对整个交集取索引,所以连数组的类型也留到了后面再算。把布尔键改成确定的空集合 never 后,这一索引可以读到数组。布尔键上界和空键集合的类型对照弹窗

toRefs 拿到的是交集的索引类型

同一个 props 可以用点号或方括号在表达式里读属性,也可以先取出宏的返回类型 P,再用 P['options'] 做类型索引。三个写法访问的都是 options。

function inspectReleasedMacro<T extends string | number>() {
  const props = defineProps<Props<T>>(); // DefineProps<LooseRequired<Props<T>>, BooleanKey<Props<T>>>
  const direct = props.options; // readonly Option<T>[]
  const viaBrackets = props['options']; // readonly Option<T>[]
  type FromValue = typeof direct; // readonly Option<T>[]
  type P = typeof props; // 原始只读字段与布尔字段映射的交集。
  type Value = P['value']; // 仍是交集的索引。
  type Options = P['options']; // 仍是同一个交集的索引。
  type DirectRefCheck = IsExistingRef<FromValue>; // false
  type IndexedRefCheck = IsExistingRef<Options>; // [Options] extends [Ref] ? true : false,待定。
  const { options } = toRefs(props); // ToRef<Options>,内层条件待定。
  const items = options.value; // any

  // @ts-expect-error TS7006,item 没有从数组方法获得上下文类型。
  const selected = items.find(item => item.value === props.value); // any
}

检查 props.options 时,TypeScript 按名字去交集的两侧找已经能解析出的 options 属性。左侧的 Readonly<LooseRequired<Props<T>>> 有这个字段,类型是 readonly Option<T>[]。右侧的映射键还待定,当前解析不出任何可供查找的成员。检查器因此用左侧找到的属性给这次读取定类型。用字面量写成 props['options'] 时,也是求这次读取的结果。两处入口可对照点号的属性查找和交集成员的查找。

P['options'] 走的是类型索引的入口。检查器先按对象分类,交集右侧的键还待定,整份交集因此被当作泛型对象。即使索引已经是字面量 'options',这条分支也会先保存一个待求值的索引类型。它在这一处没有用键集合的上界排除 'options'。TypeScript 的源码注释还说明了方括号表达式的例外来自已有代码的兼容性:固定键的取值表达式会尽早解析属性。可对照索引访问的延迟分支。

typeof direct 取得的是已经查到的数组类型,typeof props 取得的仍是整份交集类型。Vue 的 ToRefs<P> 声明用 P[K] 取字段,所以它把第二条路径上待定的 Options 交给 ToRef。

ToRef<X> 的内层条件选真分支时沿用 X,选假分支时返回 Ref<X>。实际声明还包着一层 IfAny,作用见第 3 篇的 ToRef 分析。此时条件未能选出分支,检查器读取 .value 时要考虑两条路径。其中真分支可以按 Ref<any> 读取 .value,这个 any 覆盖了另一条路径上的类型。

已提交的宏方案让两个返回值按字段计算

让 ToRef 直接拿到数组,就能选中包装成 Ref 的分支。Vue 可以先把 defineProps() 的布尔处理拆到每个字段,再让 withDefaults() 接住这个结果。下面用 SetupProps 表示这份逐字段映射。

defineProps 只根据当前字段处理布尔类型

旧写法先扫整份对象,收集所有布尔键,再把生成的布尔对象用 & 叠到原对象上。这样,哪怕只是取 options 的类型,也要经过那整份映射。逐字段宏方案 先遍历原有字段的 keyof P。每次取一个键 K,只用当前的 P[K] 计算这一格,结果再写回同一个键。布尔判断从对象层移到了字段值里面。

下面的 SetupProps 是这一步的简化模型。它用原字段的键逐个计算,宏的实际签名会在下一节展开。

// 根据一个字段自己的类型决定是否与 boolean 取交集。
type SetupProp<X> = X & ([X] extends [boolean | undefined] ? ([X] extends [never | undefined] ? unknown : boolean) : unknown);

// 保留原字段的键,每个键独立计算字段类型。
type SetupProps<P> = {
  readonly [K in keyof P]: SetupProp<P[K]>;
};

SetupProp<X> 的形状是 X & 修正类型。右边只会给出 boolean 或 unknown,两层条件负责决定该用哪一个。

  1. 先看整个 X 能否赋给 boolean | undefined。string、boolean | string 和数组在这一关就走假分支,右边得到 unknown。X & unknown 仍是 X,原类型直接通过。
  2. 再排除只有 undefined 或 never 的字段。它们也能通过第一关,但本身没有布尔值,第二关命中后还是给 unknown。这个检查对应旧 BooleanKey 的第二关。
  3. 剩下的字段才与 boolean 取交集。boolean | undefined 收窄成 boolean,true | undefined 则收窄成 true,原来声明的布尔字面量得以保留。
type Label = SetupProp<string | undefined>; // string | undefined
type Empty = SetupProp<undefined>; // undefined
type Toggle = SetupProp<boolean | undefined>; // boolean
type Locked = SetupProp<true | undefined>; // true

同一份 Props<T> 经逐字段映射后,value 可以继续保留待定条件,options 仍能展开成数组。

function inspectPatched<T extends string | number>() {
  type P = Props<T>;
  type ValueCheck = [P['value']] extends [boolean | undefined] ? true : false; // 条件仍待定。
  type OptionsCheck = [P['options']] extends [boolean | undefined] ? true : false; // false

  const props = defineProps<Props<T>>(); // 逐字段计算的 DefineProps<…>。
  type Value = (typeof props)['value']; // SetupProp<T>,即 T & 一个待定条件。
  type Options = (typeof props)['options']; // readonly Option<T>[] & unknown,化简成 readonly Option<T>[]。
  type ExistingRef = IsExistingRef<Options>; // false
  const { options } = toRefs(props); // Ref<readonly Option<T>[]>
  const items = options.value; // readonly Option<T>[]
  const selected = items.find(item => item.value === props.value); // item 是 Option<T>,selected 是 Option<T> | undefined。
}

算 Value 时,布尔条件的左边是 [T],检查器仍把条件留在 T & … 里面。算 Options 时,布尔条件左边已经换成 [readonly Option<T>[]]。即使数组元素里含有 T,外层也已经足以判断它不是布尔值;这一字段得到 数组 & unknown,没有引用 Value 里的条件。于是 ToRef 看到的也是明确的数组类型。数组不符合 Ref 的结构,条件选择假分支,结果就是 Ref<readonly Option<T>[]>。

SetupProps 分别计算 value 和 options。value 仍保留待定条件,options 保留数组形状,使 ToRef 选择包装分支

TypePropsSource 在两个参数内标记逐字段计算

公开的 DefineProps<T, BKeys> 有两种用法。defineProps<P>() 可以根据每个字段的类型自动判断布尔转换。外部代码也可以直接写 DefineProps<P, 'enabled'>,只指定 enabled 参与收窄。第二个参数还要保留布尔键名单,供 Verter 等下游提取。逐字段宏方案把区分入口的信息放进了第一个参数。

declare const TypePropsSource: unique symbol;

declare function defineProps<P>(): DefineProps<LooseRequired<P> & { readonly [TypePropsSource]: LooseRequired<P> }, BooleanKey<P>>;

type DefineProps<T, BKeys extends keyof T> = Readonly<{
  [K in keyof T as K extends typeof TypePropsSource ? never : K]: T[K];
}> &
  (T extends { readonly [TypePropsSource]: infer P } ? { readonly [K in keyof P]: SetupProp<P[K]> } : { readonly [K in BKeys]-?: boolean });

[TypePropsSource] 把一个专用的 Symbol 用作类型里的属性键。unique symbol 让 TypeScript 能精确匹配这个键,避开业务 props 的字符串键。declare const 只提供类型声明,编译后的 JavaScript 不会创建这个 Symbol。typeof TypePropsSource 取得这个键的类型,键重映射里的 never 把它从公开结果中滤掉。unique symbol 的语法和引入时间弹窗

有了这个键,DefineProps 就能从标记里推断出 P,接着逐字段计算。没有标记的具体类型仍按显式的 BKeys 生成布尔字段。标记保存的内容是 LooseRequired<P>,其中字段已经有键,但可选布尔字段的值仍允许 undefined。这份信息接下来要交给 withDefaults() 的默认值工厂。

发布版的 withDefaults 怎样接收 props 并加上默认值

给同一个选择器补一个可选的 label,用它观察默认值和数组字段各自走哪条路。

type PropsWithLabel<T> = Props<T> & { label?: string };

调用 withDefaults(defineProps<PropsWithLabel<T>>(), { label: 'open' }) 时,第一个实参是宏返回的 props,第二个实参才是默认值。发布版的参数签名要从第一个实参拿到两项信息,原始字段 T 和布尔键 BKeys。InferDefaults<T> 再用原始字段检查默认值,最后才计算返回类型。下面是 Vue 3.6.0-rc.15 的发布签名。

export function withDefaults<
  T,
  BKeys extends keyof T,
  Defaults extends InferDefaults<T>,
>(
  props: DefineProps<T, BKeys>,
  defaults: Defaults,
): PropsWithDefaults<T, Defaults, BKeys>

返回类型 PropsWithDefaults<T, Defaults, BKeys> 也沿用整体取交集的结构。去掉源码中的类型分配和边界检查,可以把它读成三块。

  • 未设默认值的字段。从原始 props 保留这些字段。这里包括 options 和 value。
  • 设了默认值的字段。label 有字符串默认值,组件读到的是 string。
  • 整份布尔字段映射。根据 BKeys 统一补布尔读取类型,也会检查这些键各自是否设置了 undefined 默认值。

发布版的两个宏能一起调用,label 也能读成 string。把两参数逐字段宏方案的 DefineProps 搭配旧的 withDefaults() 重载,调用也能通过,但返回对象还叠着那整份布尔字段映射,options.value 依旧读成 any。早期实验直接返回独立的逐字段别名,旧签名还可能从全部字段推断布尔键,在实参校验时就报 TS2345。两参数逐字段宏方案保留 DefineProps<…> 后,下面要处理的是原始字段推断和返回形状。

withDefaults 从标记里推断收窄前的字段

新重载把第一个实参写成带标记的 DefineProps。检查器可以匹配同一泛型别名的实参,从第一个类型参数中推回原始 T,再由 InferDefaults<T> 检查第二个实参。只保留一个布尔标记就能选中逐字段分支,但工厂仍需要 enabled 收窄前的类型,所以标记携带的是整份原始字段。

declare function withDefaults<T, Defaults extends InferDefaults<T>>(
  props: DefineProps<T & { readonly [TypePropsSource]: T }, BooleanKey<T>>,
  defaults: Defaults,
): PropsWithDefaults<T, Defaults>;

在同一个选择器里加一个可选的 enabled,就能看到组件和默认值工厂读到的类型。

function inspectFactory<T extends string | number>() {
  const props = defineProps<PropsWithLabel<T> & { enabled?: boolean }>();
  const enabled = props.enabled; // boolean

  const resolved = withDefaults(props, {
    label: raw => {
      const rawEnabled = raw.enabled; // boolean | undefined
      return rawEnabled ? 'open' : 'closed';
    },
  });

  const label = resolved.label; // string
  const items = toRefs(resolved).options.value; // readonly Option<T>[]
}

把宏返回的值接到一个只写了可见字段的对象类型上,类型实参中的信息也会随之丢失。检查器只能按对象字段做反向映射推断,看到的 enabled 已经是 boolean。这里可以对照 TypeScript 6.0.3 的 同名泛型别名推断 和反向映射推断。

逐字段宏方案让返回值也逐字段处理默认值

新重载的返回类型 PropsWithDefaults 遍历 keyof T。每个字段只取自己的原始类型,由它是否有默认值决定下一步。

type DefaultedProp<T, D> = [D] extends [undefined] ? IfAny<D, NotUndefined<T>, T> : NotUndefined<T>;

type PropsWithDefaults<T, Defaults extends InferDefaults<T>> = {
  readonly [K in keyof T]: K extends keyof Defaults ? DefaultedProp<T[K], Defaults[K]> : SetupProp<T[K]>;
};
  • 有具体默认值。label: 'open' 会去掉该字段的 undefined,数组工厂 options: () => [] 同理。
  • 显式把默认值设为 undefined。DefaultedProp 直接沿用原始字段类型,布尔 prop 也可以保留 undefined。这对应 Vue 的布尔转换规则。其中 IfAny 保留了发布版对 any 默认值的特殊处理。
  • 省略默认值。这格继续走 SetupProp。可选布尔字段仍按 Vue 的读值规则处理,其他字段保留自己的类型。

这个选择器只有 label 出现在 Defaults 里,所以只有它走 DefaultedProp。options 和 value 继续单独计算,label 的默认值和 value 的待定条件都不会进入 options 的类型。

function inspectDefaults<T extends string | number>() {
  const props = withDefaults(defineProps<PropsWithLabel<T>>(), { label: 'open' }); // PropsWithDefaults<…>
  const label = props.label; // string
  type Value = (typeof props)['value']; // SetupProp<T>,布尔判断仍待定。
  type Options = (typeof props)['options']; // readonly Option<T>[]
  type ExistingRef = IsExistingRef<Options>; // false
  const { options } = toRefs(props); // Ref<readonly Option<T>[]>
  const items = options.value; // readonly Option<T>[]
  const selected = items.find(item => item.value === props.value); // item 是 Option<T>,selected 是 Option<T> | undefined。
}

显式名单继续走原来的布尔键计算

第二个重载保留 T, BKeys, Defaults 三个类型参数,返回内部类型 LegacyPropsWithDefaults<T, Defaults, BKeys>。这份公式按调用者指定的键补布尔字段。如果两个字段原本都是 boolean | undefined,而名单只有 'enabled',那么 visible 仍能为 undefined。逐字段的自动公式会同时收窄两个字段。旧重载因此需要自己的返回类型。

type Switches = {
  enabled: boolean | undefined;
  visible: boolean | undefined;
};

declare const input: DefineProps<Switches, 'enabled'>;

const result = withDefaults<Switches, 'enabled', {}>(input, {});
const enabled = result.enabled; // boolean
const visible = result.visible; // boolean | undefined
declare function withDefaults<T, BKeys extends keyof T, Defaults extends InferDefaults<T>>(
  props: DefineProps<T, BKeys>,
  defaults: Defaults,
): LegacyPropsWithDefaults<T, Defaults, BKeys>;

普通宏调用优先匹配逐字段重载。显式传三个泛型的调用沿用上面这条签名,默认值设为 undefined 时也继续按旧规则计算。

保留 DefineProps 让下游还能提取布尔键

下游既可以传入布尔键,也可以从宏返回的类型里把键推出来。以下三种写法都出现在 npm 发布包的声明文件里。

  • @mrzlanx532/nuxt-3-backoffice-ui@0.1.7 从 Vue 导入 DefineProps,在表单 composable 里显式传入 never,用这个类型标注保存和渲染函数的 props 参数。这里的 never 表示布尔键集合为空。可对照表单 composable 的源码。
  • vue-function-component@1.0.7 用库自己定义的 BooleanKey<PropsType> 作为第二个参数,把解析后的 props 类型交给渲染函数。可对照函数式组件的类型声明。
  • @verter/types@0.0.1-beta.7 用 DefineProps<T, infer BKeys> 匹配宏的返回类型。它的 ExtractBooleanKeys 会返回推到的键,MakeBooleanOptional 则用这些键把布尔字段改成调用方可省略的字段。实现见 Verter 的两个类型工具。

前两个包要求双参数的 DefineProps 保持可用,Verter 则会从宏的实际返回类型里推断第二个参数。给选择器加一个 active 后,可以用同一个组件检查布尔键提取和 options 的数组推断。

import { type DefineProps, defineProps, toRefs } from 'vue';

// 用 Verter 的匹配方式读出 Vue 类型里的布尔键。
type ExtractBooleanKeys<T> = T extends DefineProps<T, infer BKeys extends keyof T> ? BKeys : never;

function inspectDownstream<T extends string | number>() {
  const props = defineProps<Props<T> & { active?: boolean }>();
  const { options } = toRefs(props); // Ref<readonly Option<T>[]>
  const selected = options.value.find(item => item.value === props.value); // item 是 Option<T>。
  return props;
}

type Keys = ExtractBooleanKeys<ReturnType<typeof inspectDownstream<string>>>; // 'active'

用 TypeScript 6.0.3 对照三份声明。数组推断在 T 仍是泛型时检查,读取布尔键时再把 T 代成 string。

宏的返回类型 下游提取的布尔键 泛型组件中的 options.value
Vue 3.6.0-rc.15 的 DefineProps<T, BKeys> 'active' any,.find() 报 TS7006
直接返回逐字段的 SetupProps<T> never readonly Option<T>[]
逐字段宏方案的 DefineProps<T, BKeys>,第一个参数带标记 'active' readonly Option<T>[]

发布包的 MakeBooleanOptional 也能根据 'active' 放宽调用方的类型。调用方可以省略 active,仍须传入 options 和 value。前面两个项目的表单调用和泛型渲染函数用例,换成逐字段宏方案声明后也都能通过类型检查。

Verter 还有一条独立的检查路径。它的宏生成脚本会读入 Vue 的 .d.ts,重新生成 vue.macros.ts。如果把标记提成一个内部类型别名,脚本会复制别名,却漏掉它引用的 unique symbol 声明,生成文件会报 TS2304。逐字段宏方案把标记直接写在两个宏签名中。用固定版本的生成脚本重新生成后,宏文件和调用用例在 TypeScript 6.0.3 和 7.0.2 上都能编译。生成过程见 Verter 的宏类型生成脚本。

泛型参数未确定时,旧交集的双向赋值会报错

具体的 DefineProps<Props, 'enabled'> 仍能按名单计算。泛型工具如果一边用 DefineProps<T, K>,另一边手写旧结构 Readonly<T> & { readonly [P in K]-?: boolean },则可能遇到类型兼容性变化。T 仍是泛型时,TypeScript 无法先排除它带有内部标记的可能性。在 TypeScript 6.0.3 和 7.0.2 的最小对照里,旧声明的两个赋值方向都通过,逐字段宏方案的两个方向都报 TS2322。已检查的公开调用没有复现这组报错。双向赋值的最小复现弹窗

pnpm test-dts 覆盖了有无 withDefaults() 的数组推断、原始默认值工厂输入和显式布尔键等路径。再用 vue-tsc 3.3.14 与 TypeScript 6.0.3 检查两份真实泛型 SFC。基线在两条路径上都报 TS7006,逐字段宏方案的声明产物通过两条检查。

两个宏都按字段计算后,options 的数组类型可以保留下来。第 6 篇继续解释 LooseRequired 怎样表达运行时补齐的键。如果固定 Vue 的发布声明,第 9 篇用本地编译器实验说明 TypeScript 侧还需要解决哪一步。

提前排除布尔交集只能解决约束明确的情况

兼容性审查给出了一条更小的候选:沿用旧版 DefineProps,在筛选布尔键前增加 [T[K] & boolean] extends [never]。

type BooleanKey<T, K extends keyof T = keyof T> = K extends any
  ? [T[K] & boolean] extends [never]
    ? never
    : T[K] extends boolean | undefined
      ? T[K] extends never | undefined
        ? never
        : K
      : never
  : never;

T extends string | number 已经排除了布尔值,T & boolean 可以化简为 never。value 提前退出筛选,旧版宏签名和结构赋值也都能保留。这个小补丁通过了完整类型测试及 Verter 检查。

但约束允许布尔值时,同一步就无法继续。T extends string | boolean 允许调用方把 T 取成 string,也允许取成 boolean。前者的 value 应被排除,后者的 value 应被保留。约束里的联合不能直接当成已经代入的具体联合类型处理。

无约束 T 的可能性更多,T & boolean 同样不能一律化简为 never。在两个 TypeScript 版本中,这两种函数里的布尔键仍待定,直接调用旧版 toRefs() 继续报告 TS7006。它可以作为原始选择器的局部修复,但覆盖范围小于逐字段宏方案。

再套一层映射仍可能保留原来的索引

另一个尝试是在原结构上加一层字段展开。下面是用于隔离推断行为的简化模型。

// 表示原来的公开类型结构。
type PreviousProps<T, K extends keyof T> = Readonly<T> & {
  readonly [P in K]-?: boolean;
};

// 按原字段重新写出一份类型。
type Expanded<P> = {
  [K in keyof P]: P[K];
};

// 让原结构和展开后的结构同时出现在结果里。
type ReexpandedProps<T, K extends keyof T> = PreviousProps<T, K> & Expanded<PreviousProps<T, K>>;

这个变体在 TypeScript 6.0.3 的隔离用例里保住了双向结构赋值,但宽泛泛型的数组回调仍然报告 TS7006。映射右边继续读取 P[K],原有的待定索引还会传下去。

把宏改成返回 DefineProps<SetupProps<P>, never>,则能让这个隔离用例的数组字段恢复推断,但 Verter 提取到的布尔键也变成了 never。第二个参数承载的下游契约仍然需要验证。

展开结果的映射继续读取 P[K],逆向映射重载则在参数位置推断各字段,随后才生成 ToRefs<T>。这个推断顺序使候选实现能够沿用原有宏返回类型和 BKeys 信息。

旧声明的布尔键上界和空映射

发布版的纯类型重载把 LooseRequired<Props<T>> 和 BooleanKey<Props<T>> 传给 DefineProps。这两个字段原本就必填,所以 LooseRequired 在这个例子里不改变它们的类型。布尔判断先遍历各个键,符合条件就留下键名,否则返回 never。把每个键的结果合起来,never 会从联合里消去。下面把发布声明右侧的对象映射单独起名为 BooleanFields,以便观察它的键从哪里来。

// 看每个键对应的字段是否是一个需要布尔转换的 prop。
type BooleanKey<P, K extends keyof P = keyof P> = K extends any ? (P[K] extends boolean | undefined ? (P[K] extends never | undefined ? never : K) : never) : never;

// 把筛出的键映射成必有且只读的 boolean 字段。
type BooleanFields<K extends PropertyKey> = { readonly [P in K]-?: boolean };

function inspectOriginal<T extends string | number>(key: BooleanKey<Props<T>>) {
  type P = Props<T>;
  type RawValue = P['value']; // T
  type RawOptions = P['options']; // readonly Option<T>[]

  type ValueKey = BooleanKey<P, 'value'>; // 仍是依赖 T 的条件,分支结果为 'value' 或 never。
  type OptionsKey = BooleanKey<P, 'options'>; // never
  type Keys = BooleanKey<P>; // ValueKey | never,化简后就是仍待定的 ValueKey。
  const possibleKey: 'value' = key; // 通过,Keys 的上界是 'value'。
  type SharedFields = BooleanFields<Keys>; // 键仍待定的布尔字段对象。

  type Expanded = Readonly<P> & SharedFields; // 原对象和整份布尔字段对象的交集。
  type ExpandedOptions = Expanded['options']; // 仍保留对这个交集的索引。
  type ExpandedRefCheck = IsExistingRef<ExpandedOptions>; // 待定。

  // 对照:显式给出空的键集合,保留同样的对象交集。
  type KnownOptions = (Readonly<P> & BooleanFields<never>)['options']; // readonly Option<T>[]
  type KnownRefCheck = IsExistingRef<KnownOptions>; // false
}

possibleKey 的赋值能通过,说明检查器已经知道 Keys 的上界是 'value'。只要这个类型有成员,成员就只能是 'value'。映射里是否一定有这个键,则需要等条件求值。比如把 T 换成具体的 string 后,Keys 会是 never,布尔字段映射就是空的。

unique symbol 表示一个具体的 Symbol 键

unique 是 TypeScript 的上下文关键字。const unique = 1 仍然合法。unique symbol 随 2018 年 1 月 31 日发布的 TypeScript 2.7 引入,让编译器能区分具体的 Symbol 身份。版本见 TypeScript 2.7 发布公告。

symbol 可以接收任意 Symbol。const 直接接住 Symbol() 的结果时,TypeScript 可以推断出一个具体的 unique symbol 类型。两次创建的键可以有相同的描述。

const first = Symbol('source'); // unique symbol
const second = Symbol('source'); // 另一个 unique symbol

const metadata = { [first]: 123 };
const value = metadata[first]; // number

// @ts-expect-error second 对应另一个键。
const other = metadata[second];

declare const Key: unique symbol 适合只在类型层使用的键。{ [Key]: T } 用它作属性名,typeof Key 取得它的类型。let key: unique symbol 和 type KeyType = unique symbol 会报错。已经声明的键可以通过 type KeyType = typeof Key 引用。TypeScript 6.0.3 也允许在类的 static readonly 属性,以及接口或对象类型的 readonly 属性上直接写这个类型。用法见 TypeScript 手册。

双向赋值的最小复现

同一份代码通过 strict 模式检查。发布声明允许两次赋值,草案声明在两行赋值处都报告 TS2322。

import type { DefineProps } from 'vue';

type PreviousProps<T, K extends keyof T> = Readonly<T> & {
  readonly [P in K]-?: boolean;
};

function compare<T, K extends keyof T>(previous: PreviousProps<T, K>, current: DefineProps<T, K>) {
  const fromPrevious: DefineProps<T, K> = previous;
  const fromCurrent: PreviousProps<T, K> = current;
  return [fromPrevious, fromCurrent];
}
四种类型声明方案的定向验证

打开原文件 props-compatibility-matrix-2026-11-19.json

记录按原声明、已提交的逐字段宏方案、布尔交集提前排除方案、逆向映射重载分组。每组都在 TypeScript 6.0.3 和 7.0.2 上检查三个泛型约束、双向赋值和 Verter 布尔键提取。每个数组推断用例包含普通宏和 withDefaults() 两条路径。

errors 为空表示该次定向检查通过。7006 对应回调参数丢失类型,2322 对应泛型结构赋值失败。记录包含完整用例和两份 Git 提交编号,候选重载的源码则展示在本文第一节。源码仓库全量测试、运行时测试和下游生成器检查的范围在 checks 中单独记录。