读取哪个字段,就得到哪种类型:泛型关联
让可复用逻辑保留输入之间及输入与输出之间的类型关系。
本章目录CONTENTS ↓
配置对象的 theme 是字符串,offline 是布尔值。我们想用同一个属性读取函数处理它们:读 theme 就得到 string,读 offline 就得到 boolean,拼错字段则报错。若结果总写成所有属性值的联合,调用者还得重复检查自己刚刚选定的字段。
因此,函数不仅要接受不同对象,还要记录“本次选了哪个键”,再用这个键决定结果。类型参数保存本次选择,keyof 提供合法键范围,索引访问读取对应的值类型。
一个属性读取 API 的完整契约
先把要求拆开:用 T 表示整个对象;从 keyof T 取允许的键;用第二个参数 K 记录本次键;结果读取 T[K]。如果没有 K,只保留整个键集合,结果也只能覆盖全部字段。下面用精确与宽泛的两个签名比较差别。
function readProperty<T, K extends keyof T>(obj: T, key: K): T[K] { return obj[key];}
const settings = { theme: "dark", retries: 3, offline: false };const theme = readProperty(settings, "theme"); // stringconst offline = readProperty(settings, "offline"); // boolean// @ts-expect-error 键必须来自这个对象readProperty(settings, "missing");这里有两条关系:T 连接对象与合法键集合,K 连接本次键与返回值。若只有合法键检查,没有记录本次选择,就只能返回全部属性值的联合。
function readLoose<T>(obj: T, key: keyof T): T[keyof T] { return obj[key];}const loose = readLoose(settings, "theme"); // string | number | boolean两个函数的运行时代码相同,调用者获得的静态信息却不同。类型设计会影响后续是否还需要检查和断言。
分开理解约束、推导和结果
| 角色 | 本例中的含义 |
|---|---|
类型参数 T、K |
为本次调用记录对象类型和键类型。 |
约束 K extends keyof T |
限定 K 必须属于该对象的合法键范围。 |
| 推导 | 利用实参确定 T,并在读取 theme 时确定 K 为 "theme"。 |
结果 T[K] |
根据本次键读取属性值类型,得到 string。 |
约束是许可范围,不代表每次都取完整范围;推导也不一定保留最窄的字面量类型。这里可变对象属性 settings.theme 推导为 string,因此返回结果是 string,不是 "dark"。
类型参数在编译时工作。函数运行时仍然只是 obj[key],不会根据实际值重新执行一遍泛型推导。
信息不确定时,结果也要保留可能性
const key: "theme" | "offline" = Math.random() > 0.5 ? "theme" : "offline";const value = readProperty(settings, key); // string | boolean调用处只知道键属于两个候选,K 就可能是联合,T[K] 也得到对应值的联合。泛型并不保证每个类型参数永远是单个成员。
这一点直接影响 API 设计:一个类型参数把名字与数据联系起来,不一定已经禁止联合实参下的交叉配对。需要严格表达整组合法参数时,参见事件 API 的参数联合。
什么时候值得引入泛型
如果调用者需要“输入越具体,输出或其他参数也越具体”,泛型通常有价值。如果多个输入都只得到同一个固定结果类型,普通联合参数可能更清楚。不要因为函数可以复用就给每个位置单独加类型参数;互不关联的参数不能凭命名建立关系。
泛型函数体还必须对所有满足约束的输入成立。例如 T extends { length: number } 只保证能读取 length,不保证 T 一定是字符串,更不保证新造的 { length: 0 } 能作为任意 T 返回。
联合、重载与条件返回怎样选择
这一节是跨章对照:先理解本章的属性读取与泛型关联即可;尚未学习条件类型时,可以先继续映射与分配两章,再回读这里的条件返回。重载部分会就地说明新规则,不要求预先掌握。
设计签名时,需要分开考虑两件事:允许传入什么,以及输入怎样决定输出。以去掉首尾空格的函数为例,字符串输入应返回字符串,字符串数组输入应返回字符串数组。普通联合可以表达总体范围:
function cleanUnion(input: string | string[]): string | string[] { return typeof input === "string" ? input.trim() : input.map(s => s.trim());}
const cleaned = cleanUnion(" hi "); // string | string[]// @ts-expect-error 返回类型仍然可能是数组cleaned.toUpperCase();函数体处理了两种输入,但签名没有承诺每一种输入对应哪一种输出。调用者即使传入明确的字符串,也只能得到联合结果;编译器不会在每次调用时分析函数体,自动补上这个关系。如果不同输入本来就返回同一种结果,则无需保留这层区别:
function countInput(input: string | string[]): number { return input.length;}重载:逐项描述调用形式
重载可以分别表达字符串和数组的返回类型:
function cleanOverload(input: string): string;function cleanOverload(input: string[]): string[];function cleanOverload(input: string | string[]): string | string[] { return typeof input === "string" ? input.trim() : input.map(s => s.trim());}
const one = cleanOverload(" hi "); // stringconst many = cleanOverload([" hi "]); // string[]const uncertain = Math.random() > 0.5 ? " hi " : [" hi "];// @ts-expect-error 两个可见重载都不能接住整个联合cleanOverload(uncertain);前两行是对外可调用的重载签名,带函数体的一行是实现签名。实现签名用于检查实现,不能直接用于外部调用。联合实参无法整体赋给 string,也无法整体赋给 string[],所以这次调用失败;重载解析不会把这个实参拆成两次调用再合并结果。
如果 API 必须接受联合变量,就需要在实现之前增加一个可见的联合签名。下面是一份包含该签名的声明;declare 只描述契约,不提供实现:
declare function cleanCombined(input: string): string;declare function cleanCombined(input: string[]): string[];declare function cleanCombined(input: string | string[]): string | string[];
const combinedOne = cleanCombined(" hi "); // stringconst combinedMany = cleanCombined([" hi "]); // string[]const combinedUncertain = cleanCombined(uncertain); // string | string[]少量调用形式用重载逐项写出通常容易阅读;增加一种形式时,也要维护对应的签名和实现分支。编译器检查重载与实现签名兼容,但仍需要核对各分支是否兑现相应的返回承诺。
泛型:用一条规则计算对应结果
当结果能按输入类型用统一规则计算时,可以用泛型配合条件类型。假设一个同步商品查询 API 接受单个 ID 或 ID 数组,并约定所有 ID 都能查到:
type Product = { id: string; price: number };type ProductResult<T extends string | string[]> = T extends string ? Product : Product[];
declare function getProduct<T extends string | string[]>( id: T): ProductResult<T>;
const product = getProduct("p1"); // Productconst products = getProduct(["p1", "p2"]); // Product[]const ids = Math.random() > 0.5 ? "p1" : ["p1", "p2"];const possibleProducts = getProduct(ids); // Product | Product[]// @ts-expect-error number 不满足输入约束getProduct(42);约束限定输入范围,T 记录本次实参类型,ProductResult 根据 T 计算结果。对于 string|string[],条件左侧是裸类型参数 T,因此分别计算两个成员:string 对应 Product,string[] 对应 Product[],最后合并为 Product|Product[]。详见条件分配。
这个设计的收益不只是少写几行:明确的输入能得到精确输出,联合输入也能直接传入。如果把返回类型写成 T,就会错误地承诺返回 ID 本身的类型,而不是商品类型。类似地,clean 返回一个新字符串时,也不能承诺保留输入的字面量类型:输入 " hi ",清理后的 "hi" 已经不符合原字面量类型。
条件返回声明的简洁也有实现成本。在 TypeScript 6.0.3 中,直接在泛型 clean 实现中返回 string|string[],编译器不能自动证明它满足尚未确定的条件返回类型。声明精确不等于函数体已经证明了输入输出关联;实现时需要核对分支,不能把添加断言当作验证。
完整实现与验证见精确 API 契约:从声明到实现:用泛型重载连接精确接口和普通联合实现,再检查编译器尚未证明的分支对应关系。
本例只描述同步、全部命中、普通可变数组的查询契约。不存在的商品、异步查询和只读数组需要另行明确需求,再调整类型。
按需要保留的信息选择
同一种输入许可可以有不同的结果精度。调用形式相同、结果类型固定时,先考虑普通联合;少量不同调用形式各有明确结果时,可以用重载;结果能按输入类型统一计算时,可以用泛型配合索引或条件类型。把调用者得到的信息和实现、维护成本一起考虑,不把签名更短当作唯一标准。
这些方式可以组合。DOM 事件声明就用泛型连接事件名与事件对象,再用后备重载接受一般 string。设计比较用于说明当前契约的收益与成本,不是对语言或库历史动机的叙述。
本节代码与关键返回类型以 TypeScript 6.0.3 strict 检查;声明示例不代表商品查询的运行测试。官方查阅入口:Function Overloads 与 Conditional Types。
下一步可在表单字段变更和函数包装中观察同一类型参数怎样连接多个位置。需要查语法与推导边界时,使用官方 Generics 与 Indexed Access Types。回到全景。
这一页,先记到这里。