TypeScript 元组（tuple）：语法、具名、可选与剩余元素

TypeScript 元组是一个元素个数固定、每个位置都有自己类型的数组。[string, number] 表示恰好两个元素：先是一个字符串，再是一个数字。按照值出现的顺序，把各个类型写在方括号里即可。

// A tuple type: position 0 is a string, position 1 is a number
let user: [string, number] = ["Ada", 36];

const userName = user[0]; // string
const age = user[1];      // number
console.log(userName.toUpperCase(), age + 1); // ADA 37

// Destructuring gives each element its own type
const [n, a] = user;
console.log(`${n} is ${a}`); // Ada is 36

user = ["Grace", 85];     // fine: same shape
console.log(user, user.length); // [ 'Grace', 85 ] 2

在运行时，元组就是普通的 JavaScript 数组。元组额外带来的一切（固定的长度和每个位置的类型）都由编译器检查，然后被擦除。

元组语法

下面逐一讲解每种形式。值得留意的是 length 的类型：对于固定长度的元组，它是一个字面量类型，所以编译器知道 pair.length 恰好是 2。

编译器检查什么

元组类型固定了元素的个数、顺序以及每个位置的类型。其中任何一项写错都是编译错误：

// This does not compile: wrong length, wrong order, index out of range.
const tooShort: [string, number] = ["Ada"];
const swapped: [string, number] = [36, "Ada"];
const ok: [string, number] = ["Ada", 36];
console.log(ok[2]);

index.ts(2,7): error TS2322: Type '[string]' is not assignable to type '[string, number]'.
  Source has 1 element(s) but target requires 2.
index.ts(3,36): error TS2322: Type 'number' is not assignable to type 'string'.
index.ts(3,40): error TS2322: Type 'string' is not assignable to type 'number'.
index.ts(5,16): error TS2493: Tuple type '[string, number]' of length '2' has no element at index '2'.

普通数组永远发现不了最后一个错误：对于 string[]，arr[2] 就是一个 string，只是在运行时恰好是 undefined。

具名元组元素

标签用来说明每个位置的含义。它们完全不影响类型和索引方式，但编辑器会在悬停提示和函数签名提示中显示它们，这让 [number, number] 不再那么难懂。

type Point = [x: number, y: number];
type Span = [start: number, end: number];
type HttpResult = [status: number, body: string];

function distance([x1, y1]: Point, [x2, y2]: Point): number {
    return Math.hypot(x2 - x1, y2 - y1);
}

const start: Point = [0, 0];
console.log(distance(start, [3, 4])); // 5

const result: HttpResult = [404, "Not Found"];
const [code, text] = result;
console.log(code, text); // 404 Not Found

从 TypeScript 5.2 开始，可以只给部分位置加标签，其余位置不加，例如 [first: string, number]。标签只是写给人看的：[x: number, y: number] 和 [number, number] 是同一个类型，可以互相赋值。

可选元素

在元素类型后面加 ?，这个位置就变成可选的。可选元素必须放在必需元素之后，而且每多一个可选元素，length 的类型就会多一种可能。

type Rgb = [red: number, green: number, blue: number, alpha?: number];

const solid: Rgb = [255, 128, 0];
const faded: Rgb = [255, 128, 0, 0.5];

function toCss([r, g, b, a = 1]: Rgb): string {
    return `rgba(${r}, ${g}, ${b}, ${a})`;
}

console.log(toCss(solid)); // rgba(255, 128, 0, 1)
console.log(toCss(faded)); // rgba(255, 128, 0, 0.5)

const alpha = faded[3];   // number | undefined
const len = solid.length; // 3 | 4
console.log(alpha, len);  // 0.5 3

读取可选元素得到的是 T | undefined，所以在做算术运算之前，需要在解构模式里给默认值（a = 1）或者先做检查。

剩余元素

剩余元素 ...T[] 表示任意个 T 类型的元素。它可以放在末尾、开头或中间，但每个元组最多只能有一个。

// A label, then any number of scores
type Row = [name: string, ...scores: number[]];
const rows: Row[] = [["Ada", 90, 85], ["Grace", 77], ["Alan"]];

for (const [name, ...scores] of rows) {
    const avg = scores.length ? scores.reduce((a, b) => a + b, 0) / scores.length : 0;
    console.log(name, scores, avg);
}

// Any number of strings, then a number at the end
type PathAndSize = [...segments: string[], bytes: number];
const file: PathAndSize = ["home", "ada", "notes.txt", 2048];
console.log(file.at(-1)); // 2048

带剩余元素的元组，length 的类型是 number，因为长度不再固定。保持固定的是那些带类型的位置在哪里。

只读元组与 as const

readonly [T, U] 去掉了 push、pop、splice 和按索引赋值，这正是固定长度的值应有的样子。在数组字面量后面写 as const，会推断出一个由字面量类型组成的只读元组。

const pair: readonly [string, number] = ["x", 1];
// @ts-expect-error: Cannot assign to '0' because it is a read-only property.
pair[0] = "y";
console.log(pair); // [ 'y', 1 ]: not frozen at runtime

// as const: a readonly tuple with the exact literal values
const corner = [10, 20] as const; // readonly [10, 20]
const [cx, cy] = corner;          // cx: 10, cy: 20
console.log(cx + cy);             // 30

// Useful for fixed lists of allowed values
const SIZES = ["small", "medium", "large"] as const;
type Size = (typeof SIZES)[number]; // "small" | "medium" | "large"
const pick: Size = "medium";
console.log(SIZES.length, pick);   // 3 medium

(typeof SIZES)[number] 把元组变成其元素类型的联合类型，这个模式在 索引访问类型 中有讲解。只读元组不能传给类型为可变元组的参数，所以只读取数据的函数应该接受 readonly [number, number]。

readonly 检查只发生在编译期。在运行时数组并没有被冻结（从输出可以看到，上面的赋值确实执行了），所以如果需要运行时保证，请使用 Object.freeze。

从函数返回元组

把多个值作为元组返回，正是 React 的 useState 的做法（const [value, setValue] = useState(0)）。但有个坑：return 中的数组字面量会被推断为数组，而不是元组。

// This does not compile: the return type was inferred as an array.
function useCounter(start: number) {
    let count = start;
    const increment = () => ++count;
    return [count, increment];
}

const [count, increment] = useCounter(10);
console.log(count + 1);
increment();

index.ts(9,13): error TS2365: Operator '+' cannot be applied to types 'number | (() => number)' and 'number'.
index.ts(10,1): error TS2349: This expression is not callable.
  Not all constituents of type 'number | (() => number)' are callable.
    Type 'number' has no call signatures.

这个函数返回的是 (number | (() => number))[]，所以解构出来的两个名字都是联合类型。有两种修复方法：标注返回类型，或者加上 as const。

// Fix 1: annotate the return type as a tuple
function useCounter(start: number): [number, () => number] {
    let count = start;
    return [count, () => ++count];
}

// Fix 2: as const infers readonly [boolean, () => boolean]
function useToggle(initial: boolean) {
    let on = initial;
    return [on, () => (on = !on)] as const;
}

const [count, increment] = useCounter(10);
console.log(count + 1, increment()); // 11 11

const [on, toggle] = useToggle(false);
console.log(on, toggle(), toggle()); // false true false

返回元组可以让调用方随意给各部分命名。如果值超过两三个，或者顺序不直观，就改为返回对象：{ count, increment } 本身就说明了含义。

元组作为函数参数

类型为元组的剩余参数可以描述整个参数列表，包括可选参数。内置的工具类型 Parameters<T> 就是用这种方式表示函数参数的。

function greet(...args: [name: string, times?: number]) {
    const [name, times = 1] = args;
    console.log(Array(times).fill(`Hi ${name}`).join(", "));
}

greet("Ada");     // Hi Ada
greet("Ada", 2);  // Hi Ada, Hi Ada

type GreetArgs = Parameters<typeof greet>; // [name: string, times?: number | undefined]
const saved: GreetArgs = ["Grace", 3];
greet(...saved); // Hi Grace, Hi Grace, Hi Grace

把元组展开传入函数调用时，每个实参都会按位置做类型检查，而展开一个 (string | number)[] 做不到这一点。

元组与数组的区别

内置类型中也会出现元组。Object.entries(obj) 返回 [string, T][]，而 Map 是用 [key, value] 元组构造的：

const stock = { apples: 3, pears: 0 };

for (const [fruit, qty] of Object.entries(stock)) { // [string, number]
    console.log(fruit, qty > 0 ? "in stock" : "sold out");
}

const prices = new Map<string, number>([["tea", 2.5], ["coffee", 3.2]]);
const entries: [string, number][] = [...prices];
console.log(entries); // [ [ 'tea', 2.5 ], [ 'coffee', 3.2 ] ]

有一个陷阱：可变元组仍然拥有所有数组方法，所以 pair.push(3) 在 [string, number] 上也能通过编译，悄悄地生成一个三元素数组，而它的类型却说只有两个。把元组声明为 readonly 就能堵住这个漏洞。另外，由于类型会被擦除，来自程序外部的数据（JSON、API）在运行时不会按元组类型检查：在信任它之前，先验证它的长度和元素类型。

可变参数元组类型

元组类型可以展开其他元组类型，写作 [...T, ...U]。结合泛型，就能为拼接或前置元素的函数标注类型，同时保留每个位置的类型：

function concat<T extends unknown[], U extends unknown[]>(a: [...T], b: [...U]): [...T, ...U] {
    return [...a, ...b];
}

const joined = concat([1, "a"], [true]); // [number, string, boolean]
const [num, str, flag] = joined;
console.log(num.toFixed(1), str.toUpperCase(), !flag); // 1.0 A false

type WithId<T extends unknown[]> = [id: number, ...rest: T];
const row: WithId<[string, boolean]> = [7, "Ada", true];
console.log(row);

库的类型也大量依赖元组推断：Promise.all([fetchUser(), fetchPosts()]) 会解析为一个元组，每个输入的 Promise 对应一个类型。