我所理解的 TypeScript 最佳实践(11):用元组描述位置固定的数据
- 为什么选择 TypeScript
- 严格模式
- 使用常量枚举来管理状态
- 按运行环境处理 TypeScript 代码
- 类型检查、Lint 与测试
- TypeScript 7 升级与工具链兼容
- 用 satisfies 检查类型并保留推断
- 用 import type 区分类型依赖和运行时依赖
- 用对象类型表达字段约束
- 用联合类型表达备选,用交集类型叠加约束
- 用元组描述位置固定的数据(当前)
- 用泛型保留类型关系,用 extends 写约束和条件
- 按目标类型判断赋值是否成立
- 按输入和输出设计泛型的协变与逆变
- 先校验外部数据,再使用收窄后的类型
- 让局部实现保留推断,用注解约束公开接口
- 从一份定义派生配置、命令和事件的类型
- 用判别联合排除互斥的状态组合
- 用 never 表示没有值的类型
- 用逆向映射推断还原字段类型
一页搜索结果可以有任意多条记录,用数组表示就够了。一个选区则由起点和终点组成,两个位置都有各自的意义。TypeScript 的元组能让编译器检查这两个位置是否存在,以及每个位置允许什么类型。
数组约束元素类型,元组还约束位置
number[] 表示元素都是数字,长度随运行时数据变化。[start: number, end: number] 是二元组,要求前两个位置各有一个数字。start 和 end 是给读者与编辑器看的标签,运行时仍然用索引或解构取值。
type SelectionRange = [start: number, end: number];
const range: SelectionRange = [12, 24];
const [start, end] = range;
// @ts-expect-error 缺少结束位置。
const incomplete: SelectionRange = [12];
// @ts-expect-error 普通数组没有保证一定存在两个元素。
const fromArray: SelectionRange = [12, 24] as number[];
不同位置也可以用不同的类型。例如 [name: string, zoom: number] 约束第一个元素是名字,第二个是缩放值。(string | number)[] 则允许两个位置各自出现任意一种类型,无法保证解构后拿到的是名字还是数字。TypeScript 手册的元组类型也用这些位置约束区分了元组和数组。
只读数组和只读元组适合只读取的参数
调用方可以把可变数组交给接收 readonly number[] 的函数。函数承诺只读,所以不需要调用者提供 push() 等写入能力。反过来就会报错,因为需要可变数组的一方有权写入。元组也遵循这个方向。
function getLength(range: readonly [start: number, end: number]) {
return range[1] - range[0];
}
const mutable: [number, number] = [12, 24];
const fixed = [12, 24] as const; // readonly [12, 24]
getLength(mutable);
getLength(fixed);
// @ts-expect-error fixed 不能交给允许写入的元组变量。
const writable: [number, number] = fixed;
数组字面量通常会推断为数组。as const 让上面的字面量保留两个数字的字面量类型,同时产生只读元组。需要可变的二元组时,可以给变量显式标注元组类型,也可以用 satisfies [number, number] 提供元组形状并检查它。
const ordinary = [12, 24]; // number[]
const fixed = [12, 24] as const; // readonly [12, 24]
const pair = [12, 24] satisfies [number, number]; // [number, number]
可变元组仍然有数组方法,push() 可以改变运行时长度。TypeScript 不会跟踪这些操作来重写元组声明中的位置。函数契约确实要守住位置和长度时,使用只读元组,外部输入再在运行时检查。
可选位置和剩余位置能表达一段参数
命令的第一个参数固定是命令名,后面可以附带任意数量的路径。可以用剩余位置表达这部分,也可以给固定位置标上 ?。
type FileCommand = [name: 'open', ...paths: string[]];
type SetZoom = [name: 'zoom', level?: number];
const openCommand: FileCommand = ['open', 'intro.md', 'appendix.md'];
const zoomCommand: SetZoom = ['zoom'];
可选位置适合尾部可以省略的参数。剩余位置适合重复的同类参数。用泛型展开一个元组还能保留每个位置的类型,这在转发一组参数时很有用。TypeScript 4.0 的可变参数元组用函数组合和参数转发演示了这种能力。
在条件类型里用单元素元组保留整个联合
在类型位置,T[] 表示一个元素类型为 T 的数组,[T] 则表示只有第一个位置的元组。把 T 换成 string | number,[T] 就是 [string | number]。它只有一个位置,该位置可以是字符串或数字。
type IsEveryMemberString<T> = [T] extends [string] ? true : false;
type OnlyText = IsEveryMemberString<'open' | 'close'>; // true
type Mixed = IsEveryMemberString<'open' | 1>; // false
这个判断要比较整个单元素元组,'open' | 1 无法整体放进 [string]。用这种写法时,代码没有创建运行时数组。逐成员判断和整体判断的推导见《用泛型保留类型关系,用 extends 写约束和条件》。
短小的位置协议适合元组,例如坐标、区间和函数参数列表。字段多、顺序容易弄混,或经常只传其中一项时,用具名对象让调用点直接显示字段含义。
示例用 TypeScript 6.0.3 的严格模式验证,每个代码块都可以独立检查。