跳到正文

Vue 泛型 props 传给 toRefs 时可能丢失类型推断(6):补充内容:LooseRequired 让 props 键必有并保留 undefined

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

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

第 5 篇 的 PR 签名把布尔判断移到各个字段,仍然用 LooseRequired 表达组件拿到的 props。以一个可选的 label 为例,可以从 Vue 初始化 props 的那一刻,看出这个类型为什么要把键和值分别处理。

Vue 初始化 props 时补齐已声明的键

父组件渲染 <LabelCard />,省略了可选的字符串 prop label。进入子组件的 setup() 后,可以分别观察对象里有没有这个键,以及它的值是什么。

import { defineComponent } from 'vue';

export const LabelCard = defineComponent({
  props: { label: String },
  setup(props) {
    console.log(Object.hasOwn(props, 'label')); // true
    console.log(props.label); // undefined
    return () => null;
  },
});

父组件如果改成 <LabelCard label="Home" />,两行结果是 true 和 'Home'。两次渲染都有这个键,区别只在字段值。

Vue 的 initProps() 先让 setFullProps() 处理传入的 props 以及适用的默认值和布尔转换,再遍历已声明的 prop。省略 label 且没有默认值时,前一步结束后 props 里还没有这个键,补键循环才为它写入 undefined。

setFullProps(instance, rawProps, props, attrs)
// ensure all declared prop keys are present
for (const key in instance.propsOptions[0]) {
  if (!(key in props)) {
    props[key] = undefined
  }
}

因此父组件的输入可以写作 { label?: string },而子组件的读取类型需要表达 { label: string | undefined }。在后一种类型里,空对象与 { label: undefined } 是两种不同的形状。

LooseRequired 补齐键,同时保留原来的读值类型

Vue 的类型声明把这两项要求放在同一个映射里。T 是组件声明的原始 props 类型,在这个例子中就是 { label?: string }。

export type LooseRequired<T> = { [P in keyof (T & Required<T>)]: T[P] }

可以把计算拆成三步。

  1. Required<T> 在这个例子里得到 { label: string },把 label 的可选标记去掉。
  2. T & Required<T> 要满足 Required<T> 对 label 的必填要求。映射从交集取出键 label,沿用它的必填标记。
  3. 冒号右边的 T[P] 从原来的 T 取值。T['label'] 读的是可选字段,结果仍是 string | undefined。
// 复用 Vue 的映射定义,观察同一个 label 在三个位置的类型。
type LooseRequired<T> = { [P in keyof (T & Required<T>)]: T[P] };
type LabelProps = { label?: string };

type ParentValue = LabelProps['label']; // string | undefined
type RequiredValue = Required<LabelProps>['label']; // string
type SetupValue = LooseRequired<LabelProps>['label']; // string | undefined

const fromParent: LabelProps = {};
const insideSetup: LooseRequired<LabelProps> = { label: undefined };

// @ts-expect-error 组件内部的类型要求 label 键存在。
const missingKey: LooseRequired<LabelProps> = {};

// @ts-expect-error Required<LabelProps> 中的 label 要是字符串。
const requiredLabel: Required<LabelProps> = { label: undefined };

把左侧取键的来源换成 Required<T>,这个例子仍然算出同一个结果。Required<LabelProps> 和 LabelProps & Required<LabelProps> 都要求 label 存在,两种映射都取出同一个键和必填标记,右边读到的也都是 LabelProps['label']。Vue 当时把这个映射用进了组件的 setup 签名,差异在给整个组件做赋值检查时才显现。

mixin 检查会拿组件的 setup 签名一起比较

Vue 当时的通用 mixin 类型 ComponentOptionsMixin 允许传入各类组件,props 实参写成 any。它的组件类型也带着 setup 字段。ComponentOptionsBase.setup 用 LooseRequired 计算组件自身及其 mixins、extends 的 props。因此,检查 mixins: [LabelCard] 对应的类型赋值时,TypeScript 会碰到这个参数类型。

先只看函数,让实现承担一个简单的保证。只要 Vue 传来的对象有 label 键,哪怕它的值是 undefined,这个实现也能正常接收。现在试着把它赋给一个声明可以接收任意字符串键字典的函数。

type SetupProps = Readonly<{ label: string | undefined }>;
type PropsDictionary = { readonly [key: string]: any };

function hasLabel(props: SetupProps) {
  return 'label' in props;
}

const empty: PropsDictionary = {}; // 字典允许一个键都没有。

// @ts-expect-error 字典可能没有实现所需的 label 键。
const acceptsDictionary: (props: PropsDictionary) => unknown = hasLabel;

如果赋值成立,调用方就可以按目标签名调用 acceptsDictionary(empty)。实现 hasLabel 要求 label 键存在,所以 TypeScript 拒绝赋值。

两种取键方式让编译器选择不同的比较路径

继续使用 LabelProps 和同一个 hasLabel。Short 对应 Vue 第一个提交的 keyof Required<T>,Intersection 对应后续的交集写法。把它们各自放进带 setup 的组件类型,再做三次赋值。

type LabelProps = { label?: string };
type PropsDictionary = { readonly [key: string]: any };
type Short<T> = { [P in keyof Required<T>]: T[P] };
type Intersection<T> = { [P in keyof (T & Required<T>)]: T[P] };

interface ShortComponent<T> {
  setup?: (props: Readonly<Short<T>>) => unknown;
}

interface IntersectionComponent<T> {
  setup?: (props: Readonly<Intersection<T>>) => unknown;
}

function hasLabel(props: Readonly<{ label: string | undefined }>) {
  return 'label' in props;
}

const shortBase: ShortComponent<LabelProps> = { setup: hasLabel };
const intersectionBase: IntersectionComponent<LabelProps> = { setup: hasLabel };

// @ts-expect-error 展开 setup 参数后,字典缺少必有的 label。
const a: ShortComponent<any> = shortBase;
const b: IntersectionComponent<any> = intersectionBase;

// @ts-expect-error 保留同一份实现,把目标写成具体结构后,又会报缺少 label。
const expanded: { setup?: (props: PropsDictionary) => unknown } = intersectionBase;

b.setup?.({}); // 类型检查通过。直接调用得到 false。

TypeScript 4.7.4 和 6.0.3 在 --strict 下的结果相同。两种映射代入 LabelProps 都要求 label 存在。代入 any 后,它们的参数都能展开为允许空对象的字典。三个结果的区别在于检查器实际比较了什么。

赋值 检查器先比较什么 结果
a Required<T> 的去可选标记使实参比较无法直接放行。检查器再展开 setup 的参数,发现字典缺少 label。 报错
b 两边都是同一个 IntersectionComponent<T> 的实例。检查器比较调用方的实参 any 和实现的实参 LabelProps,这一步已经通过。 通过
expanded 右边仍是刚才的实现,左边换成显式的 setup 参数结构。展开后,字典仍然缺少 label。 报错

为什么左侧的一个交集就能造成差异?比较泛型时,检查器会额外读取映射的可选标记。取键的来源直接是 Required<T> 时,能读到它去掉问号的 -?,所以会进一步比较映射出来的结构。来源是 T & Required<T> 时,泛型 T 本身没有提供一致的去可选信息,检查器允许先按泛型实参比较。这和具体字段怎样生成是两次不同的检查。把 LabelProps 展开后,Required<LabelProps> 仍会要求 label 存在。各版本怎样记录这些信息,见可选修饰符怎样改变检查路径弹窗。

b.setup?.({}) 的直接调用说明了这种检查的边界。它绕过了 Vue 的 props 初始化,所以只用来检验 TypeScript 接受了什么形状。正常走 Vue 的 initProps() 时,已声明的 label 仍会补齐。这里借 setup 签名观察的是组件选项之间的类型赋值。运行时合并规则见选项合并文档。

Vue 的提交与类型测试

Vue #6244 处理的是宽索引签名覆盖具名字段的问题。原实现用 string & keyof T。第一个提交把它改成 keyof Required<T>,第二个提交才换成 keyof (T & Required<T>)。审阅建议保留了交集,只调整冒号后的空格。提交和审阅都没有写明为什么加入交集。当时的类型测试可以验证交集写法带来的一项兼容差异。后来 #6421 才把这个工具接进 defineProps。

在 Vue 当时的源码上也能看到同样的差异。用锁定的 TypeScript 4.7.4 检查该提交的 defineComponent 类型测试,保留交集时通过。只换回 keyof Required<T> 后,mixins: [MixinA] 报 TS2769,接着读取 props.aP1 又报字段不存在。extends 用例也出现同类错误。

具体键和索引签名的对照,见键集合、索引签名与大型联合的编译对照弹窗。第 7 篇 继续用小例子区分普通赋值、类型索引和条件求值。

可选修饰符怎样改变检查路径

下面用 title 和 id 分别观察两个字段的约束,再看 TypeScript 何时只比较泛型实参。

字段是否必填和型变怎样检查分别计算

同一个交集可以让某个键必填,又让另一个键继续可选。TypeScript 在构造字段时逐个看键,在比较泛型实参时则查看映射对可选标记做过什么操作。

一边去掉问号,只约束它自己的字段

一边要求 title 必填,就足以让交集里的 title 必填。看两个不同的键,就能看到这条规则的范围。

type NeedsTitle = Required<{ title?: string }>;
type MayHaveHint = { hint?: string };
type Input = NeedsTitle & MayHaveHint;

const valid: Input = { title: '文档' };
// @ts-expect-error 缺少必填的 title。
const invalid: Input = { hint: '提示' };

title 的约束来自 NeedsTitle,hint 的约束来自 MayHaveHint。输入可以省略 hint,但必须有 title。如果把其中一边的 -? 概括成「整个交集统一去掉可选标记」,就会把对 title 成立的结论套到 hint 上。

具体到 TypeScript 6.0.3,src/compiler/checker.ts 的 createUnionOrIntersectionProperty() 每次处理一个字段名。对交集,遇到一个必填的同名字段,就会清掉当前字段的 Optional 标记。以下是循环里的交集分支。

optionalFlag &= prop.flags;

型变推断使用的是另一个函数。检查器用一个数概括映射声明对可选标记做了什么。-1 表示去掉 ?,1 表示加上 ?,0 表示没有可统一采用的增减操作。它与某个字段最终是否必填各自计算。上面的交集没有统一的操作,但 title 仍然必填。

在 { [P in keyof X]: T[P] } 中,检查器从 keyof 右侧取出 X,作为修饰符的来源。下面这行来自 TypeScript 6.0.3 的 src/compiler/checker.ts,位于 getModifiersTypeFromMappedType() 的 keyof 分支。4.7.4 也从这里取得来源。

type.modifiersType = instantiateType(getTypeFromTypeNode((getConstraintDeclarationForMappedType(type) as TypeOperatorNode).type), type.mapper);

TypeScript 4.7.4 的 getCombinedMappedTypeOptionality() 先检查外层映射自身的修饰符。如果外层没有,再看 X 本身是否是泛型映射。这里省去了原文件外层的缩进。

function getCombinedMappedTypeOptionality(type: MappedType): number {
    const optionality = getMappedTypeOptionality(type);
    const modifiersType = getModifiersTypeFromMappedType(type);
    return optionality || (isGenericMappedType(modifiersType) ? getMappedTypeOptionality(modifiersType) : 0);
}

来源 Required<T> 本身是泛型映射,检查器读到声明里的 -?,返回 -1。T & Required<T> 的来源是交集,isGenericMappedType(modifiersType) 返回 false,因此得到 0。

TypeScript 6.0.3 中,同一个函数会递归读取映射来源和交集成员。下面是 src/compiler/checker.ts 中的实现。

function getCombinedMappedTypeOptionality(type: Type): number {
    if (getObjectFlags(type) & ObjectFlags.Mapped) {
        return getMappedTypeOptionality(type as MappedType) || getCombinedMappedTypeOptionality(getModifiersTypeFromMappedType(type as MappedType));
    }
    if (type.flags & TypeFlags.Intersection) {
        const optionality = getCombinedMappedTypeOptionality((type as IntersectionType).types[0]);
        return every((type as IntersectionType).types, (t, i) => i === 0 || getCombinedMappedTypeOptionality(t) === optionality) ? optionality : 0;
    }
    return 0;
}

every(...) 检查每个成员的结果是否和第一个相同。对泛型的 T & Required<T>,尚未确定的 T 走最后的 return 0,Required<T> 在映射分支得到 -1。两者不同,整个交集的摘要返回 0。这一步得到 0 之后,具体字段仍可以由其中一个成员要求必填。

直接比较泛型实参会漏掉映射新增的必填约束

Base 只有 id。OptionalTitle 也要求 id,同时允许省略 title,所以 Base 可以赋给 OptionalTitle。两个映射都会把声明过的 title 变成必有的键。映射后的 Base 仍然只有 id,因此同一个赋值方向到了映射结果上就不成立。

type Base = { id: string };
type OptionalTitle = { id: string; title?: string };
type Short<T> = { [K in keyof Required<T>]: T[K] };
type WithIntersection<T> = { [K in keyof (T & Required<T>)]: T[K] };
type ShortHandler<T> = (props: Short<T>) => void;
type IntersectionHandler<T> = (props: WithIntersection<T>) => void;

const input: Base = { id: 'doc' };
const original: OptionalTitle = input;

declare const short: ShortHandler<OptionalTitle>;
// @ts-expect-error 展开后的参数缺少必填的 title。
const shortHandler: ShortHandler<Base> = short;

declare const intersection: IntersectionHandler<OptionalTitle>;
const intersectionHandler: IntersectionHandler<Base> = intersection;
// @ts-expect-error 直接比较函数参数时,Base 缺少 title。
const byStructure: (props: Base) => void = intersection;

intersectionHandler(input); // 调用处只要求 id。

先看 shortHandler。左侧的调用者可以只传 { id: 'doc' },右侧的实现要求 title 键也存在。title 的值可以是 undefined,但调用者仍要传这个键。如果跳过映射,直接按逆变检查 Base 能否赋给 OptionalTitle,就会放过这次赋值。

这就是 -? 需要特殊处理的原因。它能让原本可以省略的字段变成必有,原始实参的可赋值关系就不足以预测映射结果。反过来也有可能。如果两个实参都声明了 title,只是一个必填、一个可选,直接应用 Required 后,两边都要求必填。编译器遇到 Unmeasurable 时,先检查实参是否相同。不同就去比较展开后的结构,让具体字段决定结果。

intersectionHandler 展示了只比较泛型实参会放过什么。它通过了检查,下面的调用也可以只传 id。把目标类型改写成普通函数签名 (props: Base) => void 后,右侧还是同一个函数,检查器直接比较参数结构,于是指出 title 缺失。

Unmeasurable 和 Unreliable 决定先做哪一步检查

在 6.0.3 的 mappedTypeRelatedTo() 里,下面这段代码根据 getCombinedMappedTypeOptionality(source) < 0 选择如何记录型变推断中的标记。只保留了这一行,按表达式换行。后面两段取自同文件的 typeArgumentsRelatedTo() 和 relateVariances(),省略了无关分支。

// mappedTypeRelatedTo()
const sourceConstraint = instantiateType(
  getConstraintTypeFromMappedType(source),
  getCombinedMappedTypeOptionality(source) < 0 ? reportUnmeasurableMapper : reportUnreliableMapper,
);

// typeArgumentsRelatedTo()
if (varianceFlags & VarianceFlags.Unmeasurable) {
  related = relation === identityRelation
    ? isRelatedTo(s, t, RecursionFlags.Both, /*reportErrors*/ false)
    : compareTypesIdentical(s, t);
}
// 中间分支省略。
else if (variance === VarianceFlags.Contravariant) {
  related = isRelatedTo(t, s, RecursionFlags.Both, reportErrors, /*headMessage*/ undefined, intersectionState);
}

// relateVariances()
if (result = typeArgumentsRelatedTo(sourceTypeArguments, targetTypeArguments, variances, reportErrors, intersectionState)) {
  return result;
}
if (some(variances, v => !!(v & VarianceFlags.AllowsStructuralFallback))) {
  originalErrorInfo = undefined;
  resetErrorInfo(saveErrorInfo);
  return undefined;
}

ShortHandler 的映射摘要是 -1。比较键约束时,检查器给参与型变推断的类型参数记录 Unmeasurable。这使 typeArgumentsRelatedTo() 先走 compareTypesIdentical()。Base 和 OptionalTitle 不相同,relateVariances() 随后让检查器回到函数结构,得到缺少 title 的报错。

IntersectionHandler 的映射摘要是 0。这次键约束比较只记录了 Unreliable,于是检查器仍先走逆变分支。isRelatedTo(t, s, ...) 里的 t 是赋值左侧的 Base,s 是右侧的 OptionalTitle。这两个实参能赋值,检查就结束了。Unreliable 允许在实参比较失败时再检查结构。它允许先接受实参比较的成功结果,本例恰好展示了这样做会漏掉一个必填键。

TypeScript 5.5 开始递归读取交集成员

从 4.7.4 到 6.0.3,逐个次版本抽样检查发布标签里的 src/compiler/checker.ts,再用同版本的 npm 发布包在 --strict 下编译上面两个例子。5.4.5 仍用单层判断,5.5.2 已经使用递归实现。本文的 TypeScript 源码节选来自 Microsoft TypeScript 项目,采用 Apache 2.0 许可证。

实测版本 怎样读取映射来源 Required<T> / T & Required<T> 三个函数赋值
4.7.4 检查外层及直接来源。标记函数在比较时包装成 mapper。 -1 / 0 短写法和直接比较结构报错,交集写法通过。
4.8.2、4.8.4、4.9.5、5.0.4、5.1.6、5.2.2、5.3.3、5.4.5 仍检查外层及直接来源,使用预先创建的 mapper。 -1 / 0 短写法和直接比较结构报错,交集写法通过。
5.5.2、5.5.4、5.6.3、5.7.3、5.8.3、5.9.3、6.0.2、6.0.3 递归检查映射来源。交集成员的结果一致时才采用。 -1 / 0 短写法和直接比较结构报错,交集写法通过。

两组版本在 T & Required<T> 上得到相同的 0。旧版在看到交集时停止,新版看到了 Required<T> 的 -?,但交集成员没有给出一致的结果。

两个相同的 Required 相交会化简成一个

Required<T> & Required<T> 对同一个类型重复施加了同一份约束。两版检查器在构造交集时都按类型标识去重,剩一个成员就直接返回那个类型。因此,读修饰符时看到的还是 Required<T>,它的 -? 仍然生效。这个化简发生在读取修饰符之前。下面是 TypeScript 6.0.3 的 src/compiler/checker.ts 中两处非连续的节选,4.7.4 也用相同的方式去重。

// addTypeToIntersection() 记录尚未收录的成员。
typeSet.set(type.id.toString(), type);

// getIntersectionType() 直接返回唯一的成员。
if (typeSet.length === 1) {
  return typeSet[0];
}

用重复的交集再做一次上面的组件赋值,会复现短写法的错误。

type Repeated<T> = { [P in keyof (Required<T> & Required<T>)]: T[P] };

interface RepeatedComponent<T> {
  setup?: (props: Readonly<Repeated<T>>) => unknown;
}

type Props = { title: string };
declare const repeatedBase: RepeatedComponent<Props>;

// @ts-expect-error 通用组件的 setup 参数仍缺少 title。
const repeated: RepeatedComponent<any> = repeatedBase;

TypeScript 4.7.4 和 6.0.3 都得到这项错误。代入普通的 { label?: string } 时,三个写法又都接受 { label: undefined }。如果要改库里的泛型映射,具体对象的键和值可以先单独测,再把映射放回 setup 之类的调用签名,重跑实际的赋值用例。

TypeScript 保留了映射键的型变快速路径

Unreliable 的设计是先接受实参比较成功的结果,失败时再检查结构。TypeScript 6.0.3 的 src/compiler/types.ts 把它描述为型变检查可能错拒绝,但预期不会错放行。前面的 IntersectionHandler 例子表明,这个预期在部分映射上会落空。

2019 年的修复尝试过统一检查结构

TypeScript #29698 记录了一次同类的漏报。编译器接受 Record<string, number> 到 Record<'title', number> 的赋值,但宽字典的实际对象可以缺少 title。同一个 Record 的两个实例可以直接比较类型实参,普通索引签名与具名字段则走结构比较。见 TypeScript #29698。

2019 年的 PR #30416 最初尝试把用作映射键的类型参数都标为 Unmeasurable。测试中,更多结构比较导致 DefinitelyTyped 上的类型检查结果变化,还触发了循环检查问题。合入前的提交 4e96d98d10 将两个标记分开。移除可选标记的映射继续用 Unmeasurable,其余这类键约束比较记作 Unreliable,实参比较通过时可以提前返回。取舍记录在 PR #30416 和拆分两个标记的提交中。

Anders Hejlsberg 在 2022 年的 #49852 里给出了 Record 的双向对照。Unreliable 让实参比较失败的方向有机会通过结构检查,也保留了另一个方向由型变直接放行的结果。他说明,把这类映射键一律改成 Unmeasurable 会增加检查开销,也会改变既有代码的通过结果。双向对照和后续讨论见 TypeScript #49852。

LooseRequired 的交集写法也能放过缺失的键

把前面的 intersection 换成真正的函数,就能看到这个差异怎样传到运行时。实现要求对象有 title 键,键对应的值可以是 undefined,所以这里用 Object.hasOwn() 检查键是否存在。

type Base = { id: string };
type OptionalTitle = { id: string; title?: string };
type WithIntersection<T> = { [K in keyof (T & Required<T>)]: T[K] };
type IntersectionHandler<T> = (props: WithIntersection<T>) => void;

const inspect: IntersectionHandler<OptionalTitle> = props => {
  if (!Object.hasOwn(props, 'title')) {
    throw new Error('缺少 title 键');
  }
};

const handle: IntersectionHandler<Base> = inspect;
handle({ id: 'doc' });

TypeScript 6.0.3 和 7.0.2 都在 --strict 下接受这段代码,执行时会抛出「缺少 title 键」。这是 TypeScript 的类型检查漏报,与上游已知的映射键型变问题属于同类。#29698 的复现用的是 Record,这里的复现用的是取交集键的映射。Unreliable 的提前返回是已有的性能和兼容性取舍,它无法证明这次函数赋值符合展开后的参数约束。

键集合、索引签名与大型联合的编译对照

两个写法可以取出相同的 props 键

对 T = { label?: string },keyof T 和 keyof Required<T> 都包含 label。TypeScript 的交集取键规则通常把 keyof (A & B) 化为 keyof A | keyof B,所以这里加交集仍然取出同一个键。实测还覆盖了索引签名、符号键、只读字段和带判别字段的对象联合。关于 Required<T> 对普通对象和可调用对象的影响,见对象类型篇。

泛型映射还依赖 keyof 后面的类型

映射类型里的 [P in keyof X] 会用 X 取得要映射的属性及修饰符。正文的 getModifiersTypeFromMappedType() 源码展示了怎样取得 keyof 后的类型。只比较键名,看不到这一层差异。下面用尚未确定的 T 分别做两组赋值检查。

type OriginalKeys<T> = keyof (T & Required<T>);
type ShortKeys<T> = keyof Required<T>;
type Current<T> = { [P in keyof (T & Required<T>)]: T[P] };
type Short<T> = { [P in keyof Required<T>]: T[P] };

function compareKeys<T>(a: OriginalKeys<T>, b: ShortKeys<T>) {
  const fromOriginal: ShortKeys<T> = a;
  const fromShort: OriginalKeys<T> = b;
}

function compareMappings<T>(a: Current<T>, b: Short<T>) {
  // @ts-expect-error 检查器无法证明任意 T 的 Current<T> 都可赋给 Short<T>。
  const fromOriginal: Short<T> = a;
  const fromShort: Current<T> = b;
}

TypeScript 4.8.2 和 6.0.3 都接受两组键类型之间的双向赋值。检查整个映射时,Short<T> 能赋给 Current<T>,反过来会报 TS2322。具体 props 的键和值可以相同,泛型声明仍会被检查器区分。

大型联合可以触发实际的编译差异

Vue #10514 记录了图标 prop 触发 TS2590 的情况。下面用模板字面量生成 320 个名字,再加一个对象成员。用相同的 IconProps 比较两种映射。

type Row = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f';
type Column = Row | 'g' | 'h' | 'i' | 'j';
type IconName = `${Row}${Column}`;
type IconProps = { icon?: IconName | { path: string } };

type Current<T> = { [P in keyof (T & Required<T>)]: T[P] };
type Short<T> = { [P in keyof Required<T>]: T[P] };

declare const current: Current<IconProps>;
declare const short: Short<IconProps>;

const currentIcon = current.icon; // TS2590
const shortIcon = short.icon; // IconName | { path: string } | undefined

在 4.8.2 和 6.0.3 的严格模式里,开启或关闭 exactOptionalPropertyTypes 都得到这个结果。原映射读取 icon 时,检查器要计算交集两边的字段类型。6.0.3 的 --generateTrace 记录了 103,362 个候选组合,超过了编译器的交集展开上限。短写法从 Required<T> 取得字段信息,这个例子能完成检查。TypeScript 6.0.3 的 src/compiler/checker.ts 在 checkCrossProductUnion() 中用下面这段判断限制候选数量,节选省略了跟踪记录。

if (size >= 100000) {
  error(currentNode, Diagnostics.Expression_produces_a_union_type_that_is_too_complex_to_represent);
  return false;
}

两个新写法都能保留索引签名旁的具名字段

下面用两类索引签名复测 PR 的问题。Previous 对应修改前的写法,Current 对应合入版,Short 对应首个提交。

type Previous<T> = { [P in string & keyof T]: T[P] };
type Current<T> = { [P in keyof (T & Required<T>)]: T[P] };
type Short<T> = { [P in keyof Required<T>]: T[P] };

type Fields = { [key: string]: any; a?: 1; b: false };
type Events = {
  [key: `on${string}`]: (...args: never[]) => unknown;
  onHandle: () => number;
};

合入提交的锁文件记录的是 TypeScript 4.8.2。用它和 6.0.3 检查,得到相同结果。

读取的具名字段 Previous Current Short
Fields['a'] 对应的字段 any 1 | undefined 1 | undefined
Fields['b'] 对应的字段 any false false
Events['onHandle'] 对应的字段 (...args: never[]) => unknown () => number () => number

旧映射先计算 string & keyof T。宽索引签名让它只剩 string,a 和 b 失去各自的声明。首个提交和合入版都保住了这两个例子的具名字段。

布尔 prop 的读取类型

可选的布尔 prop 和可选的字符串 prop 都会补齐键,读取类型还有一层差异。BooleanKey 筛出适用布尔转换的字段,DefineProps 再把这些字段的读值限定为布尔。第 3 篇在泛型组件里用到了这一步。

逐键筛选与普通 props 的完整展开弹窗
普通布尔 prop 怎样得到组件内的读取类型

BooleanKey 只返回可以按布尔 prop 处理的键名

BooleanKey 的输出是键名。例如输入 { enabled?: boolean; label?: string },输出是 'enabled'。

// vuejs/core/packages/runtime-core/src/apiSetupHelpers.ts:103-109
type BooleanKey<T, K extends keyof T = keyof T> = K extends any
  ? T[K] extends boolean | undefined
    ? T[K] extends never | undefined
      ? never
      : K
    : never
  : never

阅读面板有两个可选字段 enabled 和 label。把这份声明交给 BooleanKey<T>,第二个参数 K 默认等于 keyof T,这里就是 'enabled' | 'label'。给类型索引传入两个键的联合,相当于分别取出两个字段的读取类型,再把结果合成联合。由于两个字段都可省略,各自的读取类型都包含 undefined。这条取值规则见 TypeScript 手册的索引访问类型。

type PanelProps = { enabled?: boolean; label?: string };
type Keys = keyof PanelProps; // 'enabled' | 'label'

type EnabledValue = PanelProps['enabled']; // boolean | undefined
type LabelValue = PanelProps['label']; // string | undefined
type AllValues = PanelProps[Keys]; // boolean | string | undefined

// 模拟直接用整组键取值,再跑 BooleanKey 的第一关。
type CheckTogether = PanelProps[Keys] extends boolean | undefined ? Keys : never; // never

这次条件问的是「boolean | string | undefined 里的值都能赋给 boolean | undefined 吗?」只要其中的 string 无法赋过去,整个条件就选假分支。它只做了一次判断,结果是 never。如果真分支能通过,返回的也会是两个键组成的 Keys,没有逐个键的结果可供筛选。

源码在取值前先写了一层 K extends any。条件左边直接是类型参数 K,TypeScript 会把联合里的两个键分别代入。'enabled' 和 'label' 都能通过外层条件,每次进入内层时只有一个键,于是 T[K] 就能分别读出两个字段的类型。这个拆分过程也可对照分布式条件类型的数组示例。

type EnabledKey = BooleanKey<PanelProps, 'enabled'>; // 'enabled'
type LabelKey = BooleanKey<PanelProps, 'label'>; // never
type SelectedKeys = BooleanKey<PanelProps>; // 'enabled' | never,化简为 'enabled'。

上面的第一个调用只检查 boolean | undefined,两关通过后留下 'enabled'。第二个调用检查的是 string | undefined,第一关就返回 never。默认传入整个键联合时,外层条件自动做这两次计算,最后把各自返回的键合起来。

BooleanKey 按键判断字段类型,第二关排除只有 undefined 或 never 的字段

原始字段 T[K] 的读取类型 判断过程与结果
enabled?: boolean boolean | undefined 第一关允许布尔值和 undefined。还包含布尔值,第二关保留 'enabled'。
locked: true true true 可以赋给 boolean,第二关保留 'locked'。
collapsed?: false false | undefined 第一关通过,还包含 false,第二关保留 'collapsed'。
label?: string string | undefined string 过不了第一关,得到 never。
mode: boolean | string boolean | string 第一关检查整个字段,含有 string 就得到 never。
placeholder?: undefined undefined 第一关允许 undefined,第二关排除它,得到 never。
unavailable: never never never 可赋给 boolean | undefined,也可赋给 never | undefined,所以第二关得到 never。

表里的 boolean、boolean | undefined,以及更窄的 true、false | undefined 都符合筛选标准。这些类型允许出现布尔值,取值范围又限定在 boolean | undefined 内。单独的 undefined 和 never 过得了第一关,第二关会排除它们。各键的结果合成联合,只剩 'enabled' | 'locked' | 'collapsed'。

DefineProps 把筛出的布尔键叠到完整对象上

DefineProps 左边是完整的只读对象。右边只遍历 BKeys,用 -? 去掉这些字段的可选标记,并要求它们的值符合 boolean。

// vuejs/core/packages/runtime-core/src/apiSetupHelpers.ts:99-101
export type DefineProps<T, BKeys extends keyof T> = Readonly<T> & {
  readonly [K in BKeys]-?: boolean
}

这里的 T 来自 LooseRequired<TypeProps>,已经包含所有声明过的 prop 键。BKeys 则来自 BooleanKey<TypeProps>。

用 { enabled?: boolean; label?: string } 代入。Original 对应左边的完整对象,BooleanFields 对应右边只含 enabled 的映射。Result 是两者的交集。

type Original = { readonly enabled: boolean | undefined; readonly label: string | undefined };
type BooleanFields = { readonly enabled: boolean };
type Result = Original & BooleanFields;

type Enabled = Result['enabled']; // boolean
type Label = Result['label']; // string | undefined

label 筛到 never,右边的 BooleanFields 就没有 label 这一行。Result 仍要满足左边的 Original,所以必须有 label,读出来还是 string | undefined。enabled 两边都有,字段值需要同时符合 boolean | undefined 和 boolean,读出来就只剩 boolean。

父组件可省略 prop,子组件按 Vue 解析后的类型读取

假设阅读面板声明了一个可选布尔开关 enabled 和一个可选标题 label,两者都没有显式默认值。父组件写 <ReadingPanel /> 时可以省略这两项。Vue 解析后,setup 接收到的对象里两个已声明的键都存在。按 Vue 的布尔 prop 规则,省略 enabled 会得到 false,省略 label 会得到 undefined。

父组件同时省略两个字段后,Vue 把 enabled 解析为 false,setup 读取类型为 boolean,label 的值为 undefined,读取类型仍是 string 或 undefined

defineProps 的类型声明要描述的是图中右侧的读取类型。LooseRequired 对应两个键都存在,BooleanKey 选出需要按布尔 prop 处理的 enabled,DefineProps 再把它的读取类型收窄到 boolean。这样,子组件可以直接使用开关值,读取标题时则还要考虑 undefined。