跳到正文

Vue 泛型 props 传给 toRefs 时可能丢失类型推断(8):补充内容:用泛型上界提前选分支需要额外条件

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

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

T extends string 足以让 { a: T } 赋给 { a: string }。碰到以 T 为参数的函数,TypeScript 要按反方向检查,所以不能把同一条保证直接拿去选条件分支。以下示例用 TypeScript 6.0.3 的 --strict 检查。赋值通过后悬停仍显示条件式的例子见第 7 篇。

对象结构比较也可能保留条件式

用同一个 T extends ['a'] 对照三次比较。把 T 放在普通对象的 a 字段里,这三条条件都会进入分支比较。第一条的目标字段是 string,第二条换成 unknown,第三条则换成一个左侧对象没有的字段。

// 用同一个元组约束比较对象的 a 字段。
type IsStringField<T extends ['a']> = { a: T } extends { a: string } ? true : false;
type IsUnknownField<T extends ['a']> = { a: T } extends { a: unknown } ? true : false;
type HasOtherField<T extends ['a']> = { a: T } extends { b: string } ? true : false;

function inspectStructure<T extends ['a']>(source: { a: T }) {
  const tupleField: { a: ['a'] } = source; // 通过,普通赋值使用 T 的约束。
  const unknownField: { a: unknown } = source; // 通过。

  // @ts-expect-error TS2322,T 的约束无法保证 a 可以赋给 string。
  const stringField: { a: string } = source;

  type ToString = IsStringField<T>; // { a: T } extends { a: string } ? true : false
  type ToUnknown = IsUnknownField<T>; // true
  type ToOtherField = HasOtherField<T>; // false
}

type FromTuple = IsStringField<['a']>; // false
type FromNever = IsStringField<never>; // true

普通赋值可以借用 T extends ['a'] 的约束,所以 tupleField 能通过。stringField 报错只说明检查器无法保证每次拿到的 a 都能赋给 string。提前把条件算成 false 则需要排除所有可能让条件成立的实参。

对于这里的对象条件,检查器先做一次宽松比较,把字段里的 T 换成内部的通配类型,在调试输出中显示为 any。连这样都无法满足目标结构时,就选假分支。否则再做一次严格比较,把 T 当成没有约束的类型参数。仍能满足目标结构时,就选真分支。两次比较都没有确定分支时,条件式会保留下来。TypeScript 6.0.3 的分支选择实现和 TypeScript 2.8 的条件类型说明都按这个顺序判断。

目标 宽松比较 严格比较 求值结果
{ a: string } a: any 可以赋给 a: string 无约束的 T 无法赋给 string 保留条件式
{ a: unknown } a: any 可以赋给 a: unknown 无约束的 T 也可以赋给 unknown true
{ b: string } 左侧依旧缺少 b 已选出假分支 false

最后两行说明为什么代入约束 ['a'] 只算一次会丢掉信息。IsStringField<['a']> 得到 false。never 同样满足 T extends ['a'],但代入后比较的是 { a: never } 和 { a: string }。never 可以赋给 string,所以这一次得到 true。这里比较的是整个对象,never 只出现在属性中。关于它的可赋值性和分配条件里的行为,可以对照 TypeScript 最佳实践第 19 篇。

用约束直接选真假分支都可能出错

T extends string 给出的是上界。T 可以取 string,也可以取更窄的 'a'。把上界代入条件只会算出其中一次结果。下面把 T 放在对象的字段和函数的参数里。使用 --strict,其中的 strictFunctionTypes 会检查函数参数的赋值方向。

// 约束是 string,条件检查 a 是否只能是 'a'。
type IsLiteralA<T extends string> = { a: T } extends { a: 'a' } ? true : false;

// 检查 a 的类型能否赋给 string。
type HasStringField<T extends string> = { a: T } extends { a: string } ? true : false;

// 检查函数能否接收任意字符串。
type CanHandleString<T extends string> = ((value: T) => void) extends (value: string) => void ? true : false;

function inspectBounds<T extends string>(field: { a: T }, handler: (value: T) => void) {
  const stringField: { a: string } = field; // 通过,T 能赋给 string。

  // @ts-expect-error TS2322,任意 string 未必能传给参数 T。
  const stringHandler: (value: string) => void = handler;

  type LiteralField = IsLiteralA<T>; // 保留条件式。
  type StringField = HasStringField<T>; // 保留条件式。
  type Handler = CanHandleString<T>; // 保留条件式。
}

type FieldAtBound = IsLiteralA<string>; // false
type FieldAtLiteral = IsLiteralA<'a'>; // true

type StringFieldAtBound = HasStringField<string>; // true
type StringFieldAtLiteral = HasStringField<'a'>; // true

type HandlerAtBound = CanHandleString<string>; // true
type HandlerAtLiteral = CanHandleString<'a'>; // false

在字段比较里,直接代入约束会过早选 false。例如 { a: string } 不能赋给 { a: 'a' },因为 a 还可能是 'b'。传入同样满足约束的 'a' 后,字段类型正好匹配,条件得到 true。宽松比较把 T 临时换成类似 any 的通配类型,{ a: any } 能通过这次比较,所以检查器保留了真分支的可能。上一节缺少 b 字段的例子即使换上通配类型也过不了,这一步就能选出 false。

在函数比较里,直接代入约束会过早选 true,因为代入 string 会得到两个相同的函数签名。换成 'a' 后,左侧函数只接收 'a',右侧函数的调用者却可以传入 'b'。这次比较得到 false。严格比较暂时去掉 T 的约束。按照 strictFunctionTypes 的检查方向,检查器要证明任意 string 都能传给左侧函数的参数 T。这个保证推不出来,真分支就仍然待定。

字段和函数参数的赋值方向相反

StringField 和 Handler 使用同一个 T extends string。字段要求把 T 赋给 string,约束已经提供了这个保证,所以 stringField 的赋值可以通过。函数参数要求把任意 string 传给 T,方向正好反过来。这就是函数参数的逆变。假如 T 是 'a',调用方传来的 'b' 就无法传给 handler。

比较 赋值所需的关系 普通赋值 泛型条件的结果
{ a: T } 赋给 { a: string } T 能赋给 string 通过 StringField 保留条件式
(value: T) => void 赋给 (value: string) => void string 能赋给 T 报 TS2322 Handler 保留条件式

这两个条件的宽松比较都能通过,所以要进一步判断能否选真分支。字段的约束足以让普通赋值通过。TypeScript 6.0.3 在为条件类型提前选择真分支时,仍会用去掉约束的 T 再比较一次。这一步无法证明无约束的 T 能赋给 string,所以 StringField 也会延迟。比较目标如果换成 { a: unknown },无约束的 T 仍能赋给 unknown,可以直接选中真分支。TypeScript 的条件类型说明把这一步称为确定可赋值检查,并明确说明它不考虑类型参数约束。

上界能证明一部分条件的真分支

HasStringField<T> 的真分支可以用约束证明。左边的字段随 T 一起变窄,右边始终要求 { a: string }。既然 T 能赋给 string,{ a: T } 就能赋给 { a: string }。上一节的逆变反例说明函数参数的比较方向不同,字段的这条推导仍然成立。

不过,只知道两边各自是协变的,还不足以决定结果。下面的左侧字段是 T | 'a',右侧字段是 T。把 T 从 string 换成 'b',两边都变窄了,左边却仍保留着 'a'。

// 检查 T 加上 'a' 后,字段类型是否仍能赋给 T。
type FitsBoth<T extends string> = { a: T | 'a' } extends { a: T } ? true : false;

type BothAtBound = FitsBoth<string>; // true,string | 'a' 仍是 string。
type BothAtLiteral = FitsBoth<'b'>; // false,'b' | 'a' 不能赋给 'b'。

即使只有左侧含 T,也要看约束具体保证了什么。TypeScript 6.0.3 的 getConditionalType() 源码注释用 { x: any } 解释为什么确定真分支时要忽略约束。把它放回对象字段的例子,T extends { x: any } 允许 x 是 number。直接把约束代入,{ x: any } 却能赋给 { x: string },会提前选错真分支。

// 检查 a 里的 x 能否赋给 string。
type HasNestedString<T extends { x: any }> = { a: T } extends { a: { x: string } } ? true : false;

type NestedAtBound = HasNestedString<{ x: any }>; // true
type NestedAtNumber = HasNestedString<{ x: number }>; // false

TypeScript 已经会在比较同一个泛型的不同实例时用型变简化比较,例如比较 Producer<Cat> 和 Producer<Animal> 时只比较实参。要让 HasStringField<T> 直接得到 true,还需要让条件类型的分支选择识别这次结构比较中的保证。上面两个反例分别说明,这个判断要看 T 出现在比较的哪一侧,以及约束是否真的限制了字段类型。

可选字段会打断可赋值关系的传递

即使 T 只出现在左侧的协变位置、右侧固定、约束里也没有 any,把上界代入后得到的 true 仍可能推不下去。下面把 T 放在单元素元组里,排除联合类型分配的影响。

// 泛型约束只要求 id。
type Bound = { id: string };
// 目标把 tag 声明为可选的字符串字段。
type Target = { id: string; tag?: string };
// 这个输入满足 Bound,但 tag 是数字。
type Input = { id: string; tag: number };

// 检查整个 T 是否能赋给 Target。
type Check<T extends Bound> = [T] extends [Target] ? true : false;

type IsInputWithinBound = [Input] extends [Bound] ? true : false; // true
type CheckBound = Check<Bound>; // true
type CheckInput = Check<Input>; // false

比较 Input 和 Bound 时只检查 id。比较 Bound 和 Target 时允许缺少 tag。直接比较 Input 和 Target 时,两边都声明了 tag,number 就无法赋给 string。用 TypeScript 6.0.3 开启 --strict 验证,exactOptionalPropertyTypes 设为 true 或 false 都得到同样的结果。

#52144 的比较目标就是泛型约束

#52144 讨论的是一个可以提前选真分支的具体场景。左侧是 [T],右侧是固定的 [PrimitiveDataType],而 T 已经满足 T extends PrimitiveDataType。TypeScript 维护者 Ryan Cavanaugh 的回复确认该例可以安全求出真分支,同时指出更窄的泛型实参可能扭转用上界算出的假分支。他提到编译器还没有「部分延迟」(partial deferral)的机制,尝试实现会比较棘手。截至 2026-11-16,该建议仍在 Backlog,讨论里没有给出具体的性能数据或兼容性阻碍。

在 #52144 里,T 的约束和右侧元组的元素都是 PrimitiveDataType。把单元素元组的元素拿出来,条件问的是 T 能否赋给 PrimitiveDataType,调用检查也用这个约束。上面的可选字段反例里,约束是 Bound,比较目标是 Target。#52144 省掉的正是从 Bound 到 Target 的第二次比较。

// 用两种原始类型保留 issue 中的联合约束。
type Primitive = string | number;

// 根据整个 T 选择回调签名。
type SelectCallback<T> = [T] extends [Primitive] ? (value: T) => void : (value: T, index: number) => void;

function invoke<T extends Primitive>(run: SelectCallback<T>, value: T) {
  // @ts-expect-error TS2554,条件待定时,调用还需满足两个形参的签名。
  run(value);
}

在 TypeScript 6.0.3 的检查器里试加这条规则,命中时用原来的 T 实例化真分支,所以回调参数仍是 T。去掉示例中的 @ts-expect-error 后,最小例子和 #52144 的原始复现都通过了,可选字段反例仍为 false。作为对照,如果只要求上界能赋给右侧,实验检查器会把 Check<Input> 错算成 true。实验限定在双侧单元素元组。裸类型参数写成 T extends U 会形成分配条件,代入 never 和 any 时还有额外的分支规则。

对象、数组和函数也能使用同一个约束

U 是原始类型或原始类型的联合,足以覆盖 #52144。把比较目标换成普通对象、只读数组或函数签名,也可以验证同一条关系。两边都是只有一个必填元素的元组,比较会落到元素类型 T 和 U 上。

// 同时用作泛型约束和元组右侧元素的三种类型。
type Obj = { id: string };
type Arr = readonly string[];
type Fn = (value: string) => number;

// 判断整个 T 能否赋给 U。
type Fits<T, U> = [T] extends [U] ? true : false;

function inspect<O extends Obj, A extends Arr, F extends Fn>() {
  // 原版 6.0.3 保留下列条件式。
  type ObjectGeneric = Fits<O, Obj>; // [O] extends [Obj] ? true : false
  type ArrayGeneric = Fits<A, Arr>; // [A] extends [Arr] ? true : false
  type FunctionGeneric = Fits<F, Fn>; // [F] extends [Fn] ? true : false
}

type ObjectConcrete = Fits<{ id: 'x'; extra: number }, Obj>; // true
type ArrayConcrete = Fits<readonly ['a', 'b'], Arr>; // true
type FunctionConcrete = Fits<(value: string | number) => 1, Fn>; // true

去掉实验检查器里对原始类型的限制,只比较 T 的约束与右侧元素是不是同一个类型。三个泛型条件都提前得到 true,三个具体实参也仍然得到 true。函数例子里,Fn 的调用方可以传任意字符串。实参的函数能接收字符串或数字,而且返回的 1 也满足 number。

多态 this 会改变函数调用时的约束

两处写着同一个接口名时,函数调用实际检查的约束仍可能不同。在 SelfConsumer 里,value: this 中的 this 是随实例类型变化的类型。TypeScript 检查函数调用中显式指定的类型实参时,会先用该实参实例化约束中的 this。

// consume 接收和当前实例同类型的参数。
interface SelfConsumer {
  consume: (value: this) => void;
}

// consume 只能接收带 tag 的 TaggedConsumer。
type TaggedConsumer = { consume: (value: TaggedConsumer) => void; tag: string };

// 用同一个接口名作约束和比较目标。
declare function checkConsumer<T extends SelfConsumer>(): [T] extends [SelfConsumer] ? true : false;

const fromCall = checkConsumer<TaggedConsumer>(); // 调用通过,类型是 false。
type Direct = [TaggedConsumer] extends [SelfConsumer] ? true : false; // false

checkConsumer<TaggedConsumer>() 能通过约束,因为 checkTypeArguments() 先用 TaggedConsumer 替换 SelfConsumer 里的 this。这时目标的 consume 也只要求接收 TaggedConsumer。求值 [TaggedConsumer] extends [SelfConsumer] 时,右侧 consume 要能接收普通的 SelfConsumer。后者可能没有 tag,所以在 --strict 下条件得到 false。

如果仅凭约束和右侧元素是同一个内部类型就提前选真分支,实验检查器会把 fromCall 错算成 true,而 Direct 仍是 false。提前求值需要核对实参检查实际使用的约束,尤其是函数调用会不会实例化其中的 this。

回到 Vue 的选择器,组件标注和逐字段 PR 中的声明让 ToRef 直接比较数组形状。这样可以恢复 .find() 的元素类型。组件侧改法见第 4 篇,PR 中的声明见第 5 篇。