跳到正文

我所理解的 TypeScript 最佳实践(11):用元组描述位置固定的数据

我所理解的 TypeScript 最佳实践

  1. 为什么选择 TypeScript
  2. 严格模式
  3. 使用常量枚举来管理状态
  4. 按运行环境处理 TypeScript 代码
  5. 类型检查、Lint 与测试
  6. TypeScript 7 升级与工具链兼容
  7. 用 satisfies 检查类型并保留推断
  8. 用 import type 区分类型依赖和运行时依赖
  9. 用对象类型表达字段约束
  10. 用联合类型表达备选,用交集类型叠加约束
  11. 用元组描述位置固定的数据(当前)
  12. 用泛型保留类型关系,用 extends 写约束和条件
  13. 按目标类型判断赋值是否成立
  14. 按输入和输出设计泛型的协变与逆变
  15. 先校验外部数据,再使用收窄后的类型
  16. 让局部实现保留推断,用注解约束公开接口
  17. 从一份定义派生配置、命令和事件的类型
  18. 用判别联合排除互斥的状态组合
  19. 用 never 表示没有值的类型
  20. 用逆向映射推断还原字段类型

一页搜索结果可以有任意多条记录,用数组表示就够了。一个选区则由起点和终点组成,两个位置都有各自的意义。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 的严格模式验证,每个代码块都可以独立检查。