我所理解的 TypeScript 最佳实践(12):用泛型保留类型关系,用 extends 写约束和条件
- 为什么选择 TypeScript
- 严格模式
- 使用常量枚举来管理状态
- 按运行环境处理 TypeScript 代码
- 类型检查、Lint 与测试
- TypeScript 7 升级与工具链兼容
- 用 satisfies 检查类型并保留推断
- 用 import type 区分类型依赖和运行时依赖
- 用对象类型表达字段约束
- 用联合类型表达备选,用交集类型叠加约束
- 用元组描述位置固定的数据
- 用泛型保留类型关系,用 extends 写约束和条件(当前)
- 按目标类型判断赋值是否成立
- 按输入和输出设计泛型的协变与逆变
- 先校验外部数据,再使用收窄后的类型
- 让局部实现保留推断,用注解约束公开接口
- 从一份定义派生配置、命令和事件的类型
- 用判别联合排除互斥的状态组合
- 用 never 表示没有值的类型
- 用逆向映射推断还原字段类型
设置页的选项可以保存字符串,也可以保存数字。读取一个选项时,传进去的值如果是字符串,返回值也应该保留字符串类型。泛型可以把这两处连起来,让一次调用的输入决定这次调用的返回类型。对象字段、keyof 和索引访问的写法可以先读《用对象类型表达字段约束》。
如果已经拿到了两个具体类型,需要判断它们能否在回调或存储接口里互相替换,见《按输入和输出设计泛型的协变与逆变》。
泛型类型通过类型实参生成具体类型
Option<Value> 声明的是一份可以重复使用的对象类型,Value 只在这个类型别名里有效。写 Option<number> 就是在类型位置给它一个实参,value 的类型随之确定。整个过程发生在类型检查期间。
type Option<Value> = { label: string; value: Value };
const frame: Option<string> = { label: '原生标题栏', value: 'native' };
const zoom: Option<number> = { label: '100%', value: 100 };
这里变量的类型已经写出来了,检查器用它检查右侧对象。普通类型别名要求写出类型实参,或者使用声明时提供的默认类型。
泛型函数可以从每次调用的实参推断类型
type Option<Value> = { label: string; value: Value };
function getOptionValue<T>(option: Option<T>) {
return option.value;
}
const frame = getOptionValue({ label: '原生标题栏', value: 'native' }); // string
const zoom = getOptionValue({ label: '100%', value: 100 }); // number
const exactFrame = getOptionValue<'native'>({ label: '原生标题栏', value: 'native' }); // 'native'
getOptionValue<T> 自己声明了 T,再把它传给 Option<Value>,让参数的 value 和返回类型共用一份类型信息。前两次调用由 TypeScript 根据实参推断 T,最后一次显式指定字面量类型 'native'。函数体用 T 检查实现是否对每次调用成立,实际运行时只读取 option.value。
函数声明也可以显式写上返回类型 : T。这里直接返回 option.value,检查器已经能推断出相同的结果。
extends 在泛型声明里限制可传入的类型
给同一个 getOptionValue() 加上 <T extends string | number>,读取字段的逻辑照旧,调用方只能传值类型能赋给 string | number 的选项。
type Option<T> = { label: string; value: T };
function getOptionValue<T extends string | number>(option: Option<T>) {
return option.value;
}
const frame = getOptionValue<'native'>({ label: '原生标题栏', value: 'native' }); // 'native'
const zoom = getOptionValue<number>({ label: '100%', value: 100 }); // number
const mixed = getOptionValue<string | number>({ label: '缩放', value: 100 }); // string | number
// @ts-expect-error boolean 无法赋给 string | number。
getOptionValue<boolean>({ label: '启用', value: true });
// @ts-expect-error 联合中仍有 boolean。
getOptionValue<string | boolean>({ label: '启用', value: 'native' });
把类型看作它允许的值的集合。A | B 允许 A 或 B 中的值,T extends A | B 要求 T 能赋给这个联合。A、B、A | B 以及更窄的成员类型都可能符合。假如 C 里有联合之外的值,C 和 A | C 都不符合。示例里即使实际传入的值是 'native',显式指定的类型 string | boolean 仍有 boolean 成员,所以那次调用报错。any 有特殊的可赋值规则,也能被显式传进约束。
JavaScript 子类可以比父类多出属性。按 TypeScript 的对象结构来想,两件事能同时成立。子类实例的成员更多,满足父类要求的值也包含这些子类实例,因此子类实例类型所描述的值可以是更窄的集合。把一个已有的 { label: string; value: number } 对象交给只要求 { label: string } 的函数也是同样的道理。它已经具备 label,value 仍留在原对象上。具体例子见对象赋值怎样匹配字段。
对象约束要求必备字段,保留额外字段
T extends { x: number; y: number } 让函数体能读取两个数字坐标。额外字段可以保留在 T 里,调用者仍然能用它。下面用两个能通过的实参和两个会报错的实参对照。
function retainPoint<T extends { x: number; y: number }>(point: T) {
return point;
}
const point = retainPoint({ x: 0, y: 1, z: 2 });
point.z; // number
// @ts-expect-error 缺少必填字段 y。
retainPoint({ x: 0 });
// @ts-expect-error y 必须是数字。
retainPoint({ x: 0, y: '1' });
给 T 的类型 |
是否符合约束 | 原因 |
|---|---|---|
{ x: number; y: number } |
是 | 两个必填字段都存在。 |
{ x: number; y: number; z: number } |
是 | z 会留在推断结果里。 |
{ x: number } |
否 | 缺少 y。 |
{ x: number; y?: number } |
否 | y 仍可能缺席。 |
{ x: number; y: string } |
否 | y 的类型不同。 |
unknown |
否 | 还没有证据表明它是带两个数字字段的对象。 |
any |
是 | any 可以越过这层静态检查。 |
never |
是 | never 能赋给任意类型,但正常运行时没有可传入的 never 值。 |
如果给函数的是 unknown,要先检查对象及字段。这里的约束还允许直接传带 z 的对象字面量,因为函数会把整份对象推断为 T。显式把 T 写成只有 x 和 y 的具体类型后,直接传对象字面量会按这个具体目标做多余属性检查。
条件类型用 extends 在两个结果之间选择
在类型别名右侧,A extends B ? X : Y 会检查 A 能否赋给 B,成立就得到类型 X,否则得到 Y。例如 100 extends number ? 'numeric' : 'other' 的结果是字面量类型 'numeric'。把 100 换成类型参数,就能让同一个别名根据传入的类型选择结果。
type BooleanValueKey<T> = T extends boolean ? 'value' : never;
type FrameKey = BooleanValueKey<'native'>; // never
type EnabledKey = BooleanValueKey<true>; // 'value'
计算 BooleanValueKey<'native'> 时,把 T 换成 'native'。'native' 不能赋给 boolean,于是选 never。换成 true,条件成立,得到 'value'。never 表示没有可用的值,和其他类型做联合时不会增加成员。
泛型约束已经可用,条件类型仍可能待求值
假设一个文档读取 API 支持两种模式。'text' 返回字符串,'bytes' 返回字节数组。调用方知道自己传的是哪一种时,返回类型也应该跟着确定。
type ReadMode = 'text' | 'bytes';
type ReadResult<Mode extends ReadMode> = Mode extends 'text' ? string : Uint8Array;
declare function readDocument<Mode extends ReadMode>(path: string, mode: Mode): ReadResult<Mode>;
const text = readDocument('notes.md', 'text'); // string
const bytes = readDocument('notes.md', 'bytes'); // Uint8Array
function readPreview<Mode extends ReadMode>(mode: Mode) {
const result = readDocument('notes.md', mode);
const content: string | Uint8Array = result;
// @ts-expect-error 调用者也可能传入 'bytes'。
const textOnly: string = result;
return result;
}
const preview = readPreview('text'); // string
检查 readPreview() 的函数体时,Mode extends ReadMode 只约束调用者可以传什么。函数体把读取结果保留为 ReadResult<Mode>,等调用者传入具体模式再选择返回类型。这就是条件类型的延迟求值。虽然此时还没选中分支,赋给 string | Uint8Array 仍然安全,因为这个目标能接住两种结果。调用 readPreview('text') 时,Mode 推断为 'text',同一份返回类型这时算成了 string。这里的 declare 只用于演示 API 的类型签名。
把这个 API 包进另一个函数时,可以像 readPreview() 一样继续传递泛型参数。给包装函数标注 string | Uint8Array 会抹掉这层对应关系,传入 'text' 时也只能得到联合类型。模式和结果已经由一份固定的类型表描述时,可以用 ResultByMode[Mode] 直接查表。条件类型适合按输入的结构选择结果,例如从数组取元素类型。
有时约束看起来已经足够窄,条件却还留在类型里。可以用布尔键的赋值对照弹窗观察这个差异。TypeScript 的条件类型说明也给出了条件何时可以先保留。
直接检查类型参数会逐个处理联合成员
条件左边直接写类型参数 T 时,TypeScript 会给联合中的每个成员算一次条件,再把各次结果用 | 合并。这叫分布式条件类型。所有普通类型都能赋给 unknown,写 T extends unknown 就可以让各成员各走一遍真分支。
type ArrayOfEach<T> = T extends unknown ? T[] : never;
type ArrayOfWhole<T> = [T] extends [unknown] ? T[] : never;
type Separate = ArrayOfEach<string | number>; // string[] | number[]
type Together = ArrayOfWhole<string | number>; // (string | number)[]
ArrayOfEach<string | number>分两次代入。第一次用string,所以真分支的T[]是string[]。第二次用number,得到number[]。合并后,数组要么全是字符串,要么全是数字。ArrayOfWhole<string | number>的左侧是元组[T],编译器按普通条件检查整个[string | number]。条件仍然成立,但此时真分支里的T还是string | number。同一个数组可以同时装字符串和数字。
官方示例用 any,把这两行的 unknown 换成 any,结果一样。写 T[K] extends U 时,左边是索引访问类型,编译器会先取出 T[K] 的结果,再做一次整体检查。想按每个键分别查值,就先写 K extends unknown,再在真分支里查当前的 T[K]。
这里的 [T] 是只有一个位置的元组类型。它保留整个 T 作为第一个元素的类型。数组和元组的位置、长度与只读约束见《用元组描述位置固定的数据》。
infer 从匹配成功的类型里取出一部分
如果有 readonly string[],想得到元素类型 string,可以写一个数组形状,把想取出的部分标成 infer Item。infer 声明的是条件类型里的局部类型变量,写在 extends 右边用于匹配的类型中。匹配成功后,? 右边的真分支可以使用它。
type ElementOf<T> = T extends readonly (infer Item)[] ? Item : never;
type MutableElementOf<T> = T extends (infer Item)[] ? Item : never;
type Word = ElementOf<readonly string[]>; // string
type Score = ElementOf<number[]>; // number
type Missing = ElementOf<boolean>; // never
type ReadonlyIsNotMutable = MutableElementOf<readonly number[]>; // never
对 readonly string[],TypeScript 找到一个 Item,让 readonly Item[] 和输入匹配,于是 Item 是 string。boolean 匹配不到数组形状,走 never 分支。要提取函数返回类型,可以把匹配形状换成 () => infer Result。
number[] 可以交给只读数组的使用方,所以也匹配 readonly (infer Item)[]。反过来,用 T extends (infer Item)[] 匹配时,readonly number[] 会落到假分支,因为目标数组允许 push() 等写操作。元组也有这个方向的区别。对象字段的 readonly、可选字段 ? 有各自的兼容规则,见《用对象类型表达字段约束》。
type GetterResult<T> = T extends () => infer Result ? Result : never;
type Message = GetterResult<() => string>; // string
type CountList = GetterResult<() => readonly number[]>; // readonly number[]
type Missing = GetterResult<string>; // never
把 GetterResult 的输入换成 () => readonly number[],Result 得到完整的数组类型。遇到带参数的函数,可以照手册的返回类型示例把匹配形状写宽。下面的例子只提取返回值,保留 Promise 那一层。
type FunctionResult<F> = F extends (...args: never[]) => infer Result ? Result : never;
type RenderPreview = (documentPath: string, zoom: number) => Promise<boolean>;
type PreviewResult = FunctionResult<RenderPreview>; // Promise<boolean>
这里的 ...args: never[] 只出现在条件类型的匹配形状里,用来匹配参数各异的函数签名。它没有调用 RenderPreview,也没有改变该函数要求的两个参数。需要把函数的参数和返回类型都提取出来时,可以用内置的 Parameters<F> 和 ReturnType<F>。
重载根据这一次传入的实参匹配签名
同一个函数名可以有多条重载签名。下面的声明让一个实参的调用返回值本身,让两个实参的调用返回一个带 value 字段的对象。declare 只声明类型,供编译器检查调用。
declare function readSetting<T>(value: T): T;
declare function readSetting<P, K extends keyof P>(object: P, key: K): { value: P[K] };
const settings = { frame: 'native', zoom: 100 };
const byValue = readSetting(settings.zoom); // number
const byKey = readSetting(settings, 'zoom'); // { value: number }
byValue 调用只传了数字,T 推断成 number,套用第一条的返回类型。byKey 调用传了对象和键名,P 是设置对象,K 是 'zoom',返回类型按第二条的 { value: P[K] } 计算。匹配重载后,调用表达式按这条签名来检查。至于函数怎样运行,则由 JavaScript 函数体决定。
any 和 unknown 会让同一个条件得到不同结果
any 可以参与绝大多数赋值,unknown 表示具体类型未知,读取它的属性前需要先做检查。一个交集可以用来观察两者的区别。
type DetectAny<T> = 0 extends 1 & T ? true : false;
type DetectedAny = DetectAny<any>; // true
type DetectedUnknown = DetectAny<unknown>; // false
type DetectedNumber = DetectAny<number>; // false
1 & any 的结果仍是 any,所以 0 能赋给它。1 & unknown 和 1 & number 都只允许 1,这时 0 无法赋值。这种条件适合工具类型在处理 any 时切换到专门的分支。
| 和 & 的常见组合,以及它们遇到 never、unknown、any 时的区别,见《用联合类型表达备选,用交集类型叠加约束》。
读一段带 extends 的声明时,先找出这一次代入的类型,再看 extends 在类型参数列表里还是在 ? 的左边。前者决定调用能不能通过,后者决定产出什么类型。拿不准条件是否已经化简时,可以分别把结果赋给某一分支的类型和覆盖两个分支的类型,观察编译器能保证哪一步。
示例按 TypeScript 6.0.3 的严格模式检查。可以把任意一个代码块单独复制到 example.ts,执行 npx --package=typescript@6.0.3 tsc --ignoreConfig --strict --noEmit --target es2023 example.ts。
泛型布尔键与具体布尔键的赋值对照
这里把 T 限制在 string | number,再观察一个筛选布尔键的条件。具体传入字符串时能直接得到 never,在泛型函数体里,同一条条件还能留在参数类型上。
type BooleanValueKey<T> = T extends boolean ? 'value' : never;
type PendingKey<T extends string | number> = BooleanValueKey<T>;
type ConcreteKey = PendingKey<'native'>; // never
type UncheckedKey = PendingKey<any>; // 'value'
function checkBooleanKey<T extends string | number>(value: T, key: PendingKey<T>) {
const allowed: string | number = value;
const possibleKey: 'value' = key;
// @ts-expect-error 编译器还不能把 key 当成 never。
const noKey: never = key;
}
按约束检查时,value 可以赋给 string | number。key 则可以赋给覆盖两条分支的 'value',却还不能赋给 never。通常的字符串、数字及其字面量会走到 never。显式传入 any 也能通过泛型约束,但 PendingKey<any> 会保留 'value'。
这个条件进入 Vue 的属性映射后,连没有用到泛型的相邻字段也可能受到影响。Vue 专题中的纯 TypeScript 例子对照了直接读取与类型索引,并给出对应的检查器实现。