Vue 泛型 props 传给 toRefs 时可能丢失类型推断(7):补充内容:条件求值、赋值和索引访问走不同的检查路径
第 6 篇 展示了 LooseRequired 的取键写法怎样改变泛型赋值检查。回到 toRefs() 的问题,还需要区分一个类型在三种检查里各能提供什么信息。TypeScript 可以用泛型约束检查赋值,同时把条件类型保留到更具体的实参出现。第 1 篇用简单元组说明了这个区别。下面的 TypeScript 6.0.3 例子还会改动元组的层数、读取字段的写法和包装类型,以便分别观察哪一步使条件保留下来。
检查器会看条件两侧和元组的直接元素
在 TypeScript 6.0.3 里,条件类型进入分支比较前,会检查两侧的类型是否仍待定。本文的例子会触发两种检查。
- 某一侧直接是待定的类型时,检查器会保留条件式。
T extends unknown左侧是待定的T,unknown extends T则是右侧。尚未算出的泛型索引访问也可能触发这项检查。 - 两侧直接写成等长的简单元组时,检查器额外看两侧的直接元素。两边都要有至少一个元素,且没有可选项或剩余项。只要有一个直接元素仍待定,例如
[T]、[0, T]里的T,或[P['options']]里的泛型索引,这个条件就会保留下来。
以 T extends ['a'] 为约束,在泛型函数体内给下表各行的条件加上 ? true : false,悬停结果如下。判断两侧是不是简单元组时,检查器看的是条件的语法,所以 type One<X> = [X] 这样的别名只在类型上是元组。
| 条件 | 悬停结果 | 当前检查 |
|---|---|---|
T extends unknown |
保留条件式 | 左侧直接是待定的 T |
unknown extends T |
保留条件式 | 右侧直接是待定的 T |
[T] extends unknown |
true |
右侧是整个 unknown,元组整体能赋给它 |
[T] extends [unknown] |
保留条件式 | 两侧是等长简单元组,左侧的直接元素是 T |
[unknown] extends [T] |
保留条件式 | 两侧是等长简单元组,右侧的直接元素是 T |
[0, T] extends [0, unknown] |
保留条件式 | 第二个直接元素也是检查对象 |
[T] extends [unknown, unknown] |
false |
长度不同,直接比较即可排除 |
One<T> extends [unknown] |
true |
左侧写的是类型别名,普通比较能通过 |
[[T]] extends [[unknown]] |
true |
直接元素是整个固定长度元组 [T],随后结构比较能通过 |
[{ a: T }] extends [{ a: unknown }] |
true |
直接元素是普通对象,随后可以比较属性 a |
检查到 [[T]] 的直接元素 [T] 时,元组特判就结束了。接下来的结构比较仍然可以比较嵌套属性,例如确认对象的属性 a: T 能赋给 a: unknown。两项检查都在 TypeScript 6.0.3 的 getConditionalType() 中实现。检查器源码与元组规则的演进弹窗
给 T 一个具体类型后,条件可以按那次输入继续计算。例如把 ['a'] 代入 [T] extends [unknown] 就会得到 true。这里的「延迟求值」发生在类型检查期间,具体类型实参和泛型函数的运行时调用各有自己的用途。
赋值能通过,条件类型仍可能待定
继续用 T extends ['a'] 作约束,把比较目标换成 string[]。普通赋值能使用 T 的约束,条件类型则按元组的规则决定是否继续求值。
// 判断整个 X 能否赋给 string[]。
type IsStringArray<X> = [X] extends [string[]] ? true : false;
// 检查类型实参是否能赋给 true。
type ExpectTrue<X extends true> = X;
// 检查类型实参是否能赋给 boolean。
type ExpectBoolean<X extends boolean> = X;
function inspect<T extends ['a']>(value: T) {
const array: string[] = value; // string[];value 仍是 T。
const tuple: [T] = [value]; // [T]
const arrayTuple: [string[]] = tuple; // [string[]];赋值通过。
type Pending = IsStringArray<T>; // [T] extends [string[]] ? true : false,条件仍保留。
type FitsBoolean = ExpectBoolean<Pending>; // 通过。结果仍是 Pending。
// @ts-expect-error TS2344,编译器不能保证 IsStringArray<T> 可以赋给 true。
type FromParameter = ExpectTrue<IsStringArray<T>>;
type FromArray = ExpectTrue<IsStringArray<typeof array>>; // true
}
type FromTuple = ExpectTrue<IsStringArray<['a']>>; // true
在 WebStorm 中悬停
Pending,可能会看到「已展开」显示为(true & [string[]]) | false。这个显示是怎么来的,见WebStorm 的悬停说明弹窗。
tuple 那两行说明,即使给泛型套了一层,TypeScript 也能比较 [T] 和 [string[]],并让赋值通过。条件类型走的是另一项检查。TypeScript 6.0.3 在计算 IsStringArray<T> 时,保留了 [T] extends [string[]] ? true : false。给这个结果起名叫 Pending,条件依然在。用已经标注为 string[] 的 typeof array 或具体的 ['a'] 代入,才会在这个例子里得到 true。
把 @ts-expect-error 那行注释删掉,FromParameter 会显示下面的诊断。
error TS2344: Type 'IsStringArray<T>' does not satisfy the constraint 'true'.
Type 'boolean' is not assignable to type 'true'.
第一行说明 ExpectTrue 要求它的类型实参能赋给 true。第二行里的 boolean 是编译器用来比较的约束。检查器仍保留条件,用两条分支的结果 true | false 得到一个可用于比较的范围。因此 FitsBoolean 通过了,FromParameter 却还缺少一个保证,也就是结果一定为 true。诊断里保留的 false 来自条件表达式的假分支。它没有给出一个满足 T extends ['a'] 且使条件算成 false 的类型实参。
这里给 X 套上 [X],是为了让条件比较整个输入类型。例如传入 string[] | number[] 时,检查的是整个联合能否赋给 string[]。这个写法不会让内部尚未确定的 T 提前求值。
通过 ExpectTrue 的类型仍可以保留条件式
三个条件都待求值,用上一节的 ExpectTrue 检查时却有不同的结果。
// 对照双侧元组判断与裸类型参数判断。
type TupleCheck<T> = [T] extends [unknown] ? true : false;
type BareCheck<T> = T extends unknown ? true : false;
type BareToTuple<T> = T extends [unknown] ? true : false;
function inspectConstraints<T extends ['a']>() {
type B = TupleCheck<T>; // [T] extends [unknown] ? true : false
type C = BareCheck<T>; // T extends unknown ? true : false
type D = BareToTuple<T>; // T extends [unknown] ? true : false
// @ts-expect-error TS2344,B 用于比较的约束是 boolean。
type CheckB = ExpectTrue<B>;
type CheckC = ExpectTrue<C>; // 通过,悬停仍显示 C 的条件式。
type CheckD = ExpectTrue<D>; // 通过,悬停仍显示 D 的条件式。
}
type Empty = BareCheck<never>; // never
type FitsTrue = ExpectTrue<Empty>; // 通过,结果仍是 never。
ExpectTrue 只检查实参能否赋给 true。B、C、D 都可以先用两个分支的并集 boolean 比较,但这个并集无法赋给 true。C 和 D 左侧直接写 T,属于分配条件类型,检查器还能用 T 的约束 ['a'] 再算一次,得到用于这次比较的 true。B 左侧是 [T],只得到默认的 boolean 约束。通过检查后 ExpectTrue<X> 返回原来的 X,所以 CheckC 和 CheckD 悬停时仍然显示条件式。进一步计算分配条件类型约束的逻辑见 TypeScript 6.0.3 的检查器。
BareCheck<never> 把 never 当成没有成员的联合来分配,结果是 never。因为 never 可以赋给 true,FitsTrue 也能通过。直接写 never extends true ? true : false 则只比较一次,得到 true。这三种写法的完整对照见 TypeScript 最佳实践第 19 篇。
先读取字段和先写类型索引会得到不同结果
在数组旁边加一组布尔字段。交集的左边声明 options: string[],右边根据 T 生成布尔字段。右边可能生成 value,也可能不生成任何字段。
// 从布尔类型中选出 value 键。
type BooleanValueKey<T> = T extends boolean ? 'value' : never;
type WithFlags<T> = { options: string[] } & {
// 只有布尔键会进入右侧的映射。
[K in BooleanValueKey<T>]: boolean;
};
// 判断整个 X 能否赋给 string[]。
type IsStringArray<X> = [X] extends [string[]] ? true : false;
// 检查类型实参是否能赋给 true。
type ExpectTrue<X extends true> = X;
function inspectOptions<T extends string | number>(input: WithFlags<T>) {
type ArrayType = WithFlags<T>['options']; // WithFlags<T>['options'],索引待定。
type FromObject = (typeof input)['options']; // WithFlags<T>['options'],索引待定。
const array = input.options; // string[]
const bracket = input['options']; // string[]
type FromValue = ExpectTrue<IsStringArray<typeof array>>; // true
type FromBracket = ExpectTrue<IsStringArray<typeof bracket>>; // true
// @ts-expect-error ArrayType 仍是泛型索引,条件待定。
type CheckAlias = ExpectTrue<IsStringArray<ArrayType>>;
// @ts-expect-error FromObject 仍是同一个泛型索引,条件待定。
type CheckObject = ExpectTrue<IsStringArray<FromObject>>;
}
type Concrete = ExpectTrue<IsStringArray<WithFlags<string>['options']>>; // true
读 input.options 时,TypeScript 可以直接查找表达式上这个名字的属性。从左边找到 options: string[],右边没有同名声明可叠上来,所以读到的值是 string[]。input['options'] 是另一种写法,做的也是表达式取值。
写 type ArrayType = WithFlags<T>['options'] 时,TypeScript 处理的是类型索引。类型索引可以表达「以后传入不同的对象类型,按同一个键取得各自的字段类型」。所以对象类型还含有待定的泛型映射时,TypeScript 在这里先把整个索引留着。它没有逐个分析右边的映射可能贡献哪些键,再决定能否提前取出 options。加上别名只给这项操作起了名字,CheckAlias 仍然报错。
(typeof input)['options'] 也会保留索引:input 虽然已经声明,但 typeof input 取得的仍是整个 WithFlags<T>。如果先写 const array = input.options,再用 typeof array,拿到的就是已经读过的那个字段的类型。这里的 input 只是一个函数参数,TypeScript 在没有创建对象的情况下也能完成这次属性查询。
最后一行把 T 换成了 string。右边的映射算出来是空的,这时索引也能得到 string[],所以 Concrete 通过。
还能单独检查这个待定的索引能不能赋给 string[]。把下面几行接到刚才的例子里:
function inspectAssignment<T extends string | number>(indexed: WithFlags<T>['options']) {
const array: string[] = indexed; // string[];赋值通过。
// @ts-expect-error indexed 仍是泛型索引,条件待定。
type FromIndex = ExpectTrue<IsStringArray<typeof indexed>>;
type FromArray = ExpectTrue<IsStringArray<typeof array>>; // true
}
和上一节的元组一样,赋值检查可以借用约束,条件求值仍然保留原来的输入。array 已知是 string[],indexed 的类型仍然是那个泛型索引。TypeScript 6.0.3 的检查器源码弹窗
逐字段包装把待定的条件带到数组上
在刚才的对象上加回 value: T,让它对应 Vue 选择器的 props。options 仍是 string[]。
Box<T> 用 { value: T } 模拟 Vue 的 Ref。wrap() 无条件包装每个字段,box() 会先判断字段是不是已经有一层 Box。两者都用 P[K] 取得每个字段的类型。
// 从布尔类型中选出 value 键。
type BooleanValueKey<T> = T extends boolean ? 'value' : never;
// 用 T 表示选中值的类型,options 始终声明为 string[]。
type Props<T> = { options: string[]; value: T };
// 把布尔字段的映射叠到原对象上。
type WithFlags<T> = Props<T> & { [K in BooleanValueKey<T>]: boolean };
// 用 value 包装输入类型。
type Box<T> = { value: T };
// 判断整个 T 能否赋给 Box<any>。
type IsBox<T> = [T] extends [Box<any>] ? true : false;
// 保留已有的 Box,其他类型包装一层。
type AsBox<T> = [T] extends [Box<any>] ? T : Box<T>;
// 直接包装对象的每个字段。
declare function wrap<P>(input: P): { [K in keyof P]: Box<P[K]> };
// 逐字段判断是否需要包装。
declare function box<P>(input: P): { [K in keyof P]: AsBox<P[K]> };
function compare<T extends string | number>(input: WithFlags<T>) {
const array = input.options; // string[]
type FromValue = IsBox<typeof array>; // false
type FromKey = IsBox<WithFlags<T>['options']>; // 条件仍待定
const wrapped = wrap(input).options.value; // WithFlags<T>['options']
const normalized = box({ options: array }).options.value; // string[]
const broken = box(input).options.value; // any
wrapped.find(item => item.length > 0); // item 是 string
normalized.find(item => item.length > 0); // item 是 string
broken.find(item => item.length > 0); // TS7006,item 是隐式 any
}
function compareConcrete(input: WithFlags<string>) {
const restored = box(input).options.value; // string[]
restored.find(item => item.length > 0); // item 是 string
}
把前面用的 IsStringArray 换成 IsBox,能看到同样的区别。IsBox<typeof array> 已经可以算出 false。逐字段转换用的是仍带交集的 WithFlags<T>['options'],所以 FromKey 仍是待定的条件类型。
延迟求值到这一步仍然只是条件没选定。any 出现在读取 AsBox<…>['value'] 时。保留原输入的真分支按 Box<any> 读取 .value,带来了 any。新建 Box 的假分支则保存原来的字段类型。待定结果的属性查询合并这两种可能,any 覆盖了数组类型,.find() 就没有数组签名给回调推断 item。
三处对照各改变一个条件。
wrap(input)还接收同一个带条件的对象,但无条件包装,.find()能推断出string。box({ options: array })保留了是否已有 Box 的判断。这次传入的字段已经是明确的string[],条件直接选中包装分支。compareConcrete()仍对整个对象调用box(),但T已经是string。布尔键先算出never,数组签名也能保留下来。
例子在 TypeScript 6.0.3 的 --strict 下复现。数组、props 对象和布尔键映射的三处只读修饰都可以省去,报错位置相同。在 Vue 中,defineProps() 生成带布尔键映射的交集,toRefs() 再按键取字段,并判断字段是不是已经是 Ref。《布尔键映射让 toRefs 的数组字段读成 any》沿着这条路径找到实际报错的位置。
这些对照把待定条件和可赋值检查分开了。检查器如果在条件求值时也使用上界,需要判断哪些分支确实可以提前确定。第 8 篇 用可选字段、函数参数和多态 this 验证这个边界。
TypeScript 检查赋值、索引访问和条件类型的源码
TypeScript 6.0.3 的 checker.ts 和 7.0.2 的 checker.go 保留了同一套元组延迟规则。下面用 6.0.3 的源码跟踪赋值、索引访问和条件类型,再和 Go 版的判断对照。
泛型对象上的类型索引可以保留为待处理的类型
WithFlags<T>['options'] 中,objectType 是带泛型映射的交集,indexType 是字符串字面量类型 'options'。在类型别名里,accessNode 是索引访问类型节点。下面节选了 getIndexedAccessTypeOrUndefined() 的判断条件和创建索引访问类型的分支。源码注释交代了表达式的兼容性需求:this['foo'] 这类取值原本就会用对象的约束来尽早解析属性,因此表达式和类型节点走不同的分支。input.options 按名查询属性,能直接读到交集左边的 options: string[]。
if (
isGenericIndexType(indexType) || (accessNode && accessNode.kind !== SyntaxKind.IndexedAccessType ?
isGenericTupleType(objectType) && !indexTypeLessThan(indexType, getTotalFixedElementCount(objectType.target)) :
isGenericObjectType(objectType) && !(isTupleType(objectType) && indexTypeLessThan(indexType, getTotalFixedElementCount(objectType.target))) || isGenericReducibleType(objectType))
) {
// 省略缓存查询与写入,只保留创建类型的语句。
type = createIndexedAccessType(objectType, indexType, persistentAccessFlags, aliasSymbol, aliasTypeArguments);
return type;
}
检查赋值时可以使用约束
TypeScript 6.0.3 的 src/compiler/checker.ts 中,isRelatedTo() 通过 structuredTypeRelatedToWorker() 检查类型之间的关系。源类型为类型变量时,可以取它的约束,再比较约束和目标类型。下面节选自处理源类型变量的分支。对于元组示例里的 const array: string[] = value,source 是 T,constraint 是 ['a'],target 是 string[]。
const constraint = getConstraintOfType(source as TypeVariable) || unknownType;
if (result = isRelatedTo(constraint, target, RecursionFlags.Source, /*reportErrors*/ false, /*headMessage*/ undefined, intersectionState)) {
return result;
}
正文的 const array: string[] = indexed 也用到了约束,但入口略有不同。getNarrowableTypeForReference() 看到初始化表达式 indexed 有具体的上下文类型 string[],又发现索引访问有带联合成分的基础约束,因此在检查这次读值时用基础约束替代索引访问。此处跟踪到的约束是 string[] & boolean,这个交集带有数组约束,能赋给 string[]。这个替换只用于当前表达式,类型位置的 WithFlags<T>['options'] 仍然保留。
const substituteConstraints = !(checkMode && checkMode & CheckMode.Inferential) &&
someType(type, isGenericTypeWithUnionConstraint) &&
(isConstraintPosition(type, reference) || hasContextualTypeWithNoGenericTypes(reference, checkMode));
return substituteConstraints ? mapType(type, getBaseConstraintOrType) : type;
条件类型先判断是否需要等待
计算 IsStringArray<T> 则从 getConditionalType() 开始。它在尝试选分支前先调用 isDeferredType()。checkTuples 要求两侧都是直接写出的等长简单元组。满足这项条件时,辅助函数检查两侧元组的直接元素。[WithFlags<T>['options']] 也一样,里面的元素仍是泛型索引访问。
function isDeferredType(type: Type, checkTuples: boolean) {
return isGenericType(type) || checkTuples && isTupleType(type) && some(getElementTypes(type), isGenericType);
}
// getConditionalType() 的节选,先检查两侧的语法节点。
const checkTypeNode = skipTypeParentheses(root.node.checkType);
const extendsTypeNode = skipTypeParentheses(root.node.extendsType);
const checkTuples = isSimpleTupleType(checkTypeNode) && isSimpleTupleType(extendsTypeNode) &&
length((checkTypeNode as TupleTypeNode).elements) === length((extendsTypeNode as TupleTypeNode).elements);
const checkTypeDeferred = isDeferredType(checkType, checkTuples);
// 省略 infer 的处理。
const inferredExtendsType = combinedMapper ? instantiateType(root.extendsType, combinedMapper) : extendsType;
if (!checkTypeDeferred && !isDeferredType(inferredExtendsType, checkTuples)) {
// 在这里尝试选真或假分支,分支细节省略。
}
result = createType(TypeFlags.Conditional) as ConditionalType;
这两个输入的 checkTypeDeferred 都是 true,所以不会进入选分支的代码。检查器保留整个条件,供以后代入具体类型时继续计算。选真分支的实现还包含一次 getRestrictiveInstantiation() 比较,它会去掉类型参数的约束再检查可赋值性。这里的两个例子停在更早的延迟判断处。
TS2344 里的 boolean 则来自另一步比较。TypeScript 6.0.3 的 getDefaultConstraintOfConditionalType() 会取两条分支的类型,在两边都没有 any 的这个例子里,使用它们的联合。真、假分支分别为 true 和 false,所以检查器 API 读到的基础约束是 boolean,而别名自身仍是条件类型。TypeScript 2.8 的条件类型说明把选真分支所需的关系称为 definitely assignable。
元组检查从单元素扩展到等长的多元素
PR #42248 为修复递归条件类型的求值问题引入了单元素元组检查。TypeScript 5.0 的 PR #52091 把检查扩展到等长的多元素元组,因为 [A, B] extends [false, false] 也可能在类型尚未确定时选错分支。PR #56271 又让 ([A, B]) 也能走同一条路径。
#52144 的复现使用了 [T] extends [PrimitiveDataType]。作者希望在已经知道 T extends PrimitiveDataType 时,把条件类型本身化简到真分支,让后续调用得到正确的函数签名。这与 B 同属双侧元组的待定问题。C 和 D 在 ExpectTrue 中通过的是可赋值检查。TypeScript 5.4 的 PR #56004 改进了这一步对分配条件类型的约束计算。
#52144 的后续回复补了一组对照。令 T extends 1,分配条件 T extends 1 ? true : false 在泛型下能通过 ExpectTrue,具体代入 any 却得到 boolean。双侧元组 [T] extends [1] ? true : false 在同样的泛型约束下无法通过 ExpectTrue,具体代入 any 则得到 true。
同一份断言在 TypeScript 6.0.3 和 7.0.2 上有相同的结果。双侧元组中的 [T] 和 [0, T] 仍待定,放进 ExpectTrue 会报 TS2344。裸类型参数和嵌套元组的对应断言都通过。TypeScript 7 的 Go 版检查器也保留了元组的直接元素检查。
TypeScript 7 保留了元组的直接元素检查
TypeScript 7.0.2 用 Go 实现相同的延迟条件。这里的 checkTuples 仍来自对两侧元组语法和长度的检查,core.Some 逐个检查直接元素。
// microsoft/typescript-go/internal/checker/checker.go:24383-24385
func (c *Checker) isDeferredType(t *Type, checkTuples bool) bool {
return c.isGenericType(t) || checkTuples && isTupleType(t) && core.Some(c.getElementTypes(t), c.isGenericType)
}
6.0.3 的 src/compiler/checker.ts 有 54,434 行。元组延迟规则的几次 PR 都直接改这个文件,再补测试。检查器的官方说明 解释了为什么大量函数位于 createTypeChecker() 内部。它们频繁互调,共享同一批检查器状态,放在一起可以减少跨模块传递或访问这份状态的成本。6.0.3 的构建入口从 TypeScript 源码构建发布用的 JavaScript。7.0.2 也保留了约 3.2 万行的 Go 检查器源码。
WebStorm 的悬停展开与 TypeScript Playground
在 WebStorm 2026.3 里悬停同一个待定的 Pending,这组对照中「初始类型」仍是条件式,「已展开」显示为 (true & [string[]]) | false。测试时保留 TypeScript 语言服务,切换「启用服务驱动的类型引擎」前后,这一处展开文本相同。JetBrains 的 TypeScript 设置说明 把类型计算与语言服务的部分高亮和补全分开。前者受服务驱动引擎开关影响,后者只要开启语言服务就仍可使用。这里记录的是两个界面的显示差异,具体是哪条内部计算路径生成了展开文本,单看悬停和设置无法确定。
在 TypeScript Playground 选择 6.0.3,悬停 Pending 会看到 [T] extends [string[]] ? true : false。直接调用同版本语言服务也得到这条条件表达式。编译器则在 TS2344 里用 boolean 解释为什么检查没通过。判断这个别名的行为时,可以用具体类型代入验证。例如 IsStringArray<['a']> 接受 true,把 true 直接赋给 (true & [string[]]) | false 却会报错。这两种写法不能互换。