TypeScript 联合类型：| 运算符用法与示例

联合类型用 | 列出几个候选类型：类型为 string | number 的值要么是字符串，要么是数字。TypeScript 用联合类型描述那些本来就可能有多种形态的值，并且在你使用某种形态特有的功能之前，编译器会要求你先检查手上是哪一种。

function formatId(id: string | number): string {
  if (typeof id === "number") {
    return id.toString().padStart(6, "0"); // id is number here
  }
  return id.toUpperCase();                 // id is string here
}

console.log(formatId(42));     // 000042
console.log(formatId("ab-7")); // AB-7

在 typeof 检查的每个分支里，id 都只有一种类型。这一步叫作收窄（narrowing），正是它让联合类型变得实用。

只能使用共有成员

收窄之前，你只能使用联合类型中每个成员都支持的操作。toString() 在字符串和数字上都存在，所以没问题；toUpperCase() 只有字符串才有：

// This does not compile: numbers have no toUpperCase()
function shout(value: string | number) {
  return value.toUpperCase();
}

console.log(shout("hi"));

index.ts(3,16): error TS2339: Property 'toUpperCase' does not exist on type 'string | number'.
  Property 'toUpperCase' does not exist on type 'number'.

第二行指出了缺少该属性的是哪个成员。反过来也是同样的规则：string | number 类型的值不能传给类型为 string 的参数（TS2345），因为它可能是数字。联合类型能接受更多的值，代价是在你检查之前能对它做的事更少。

收窄联合类型

收窄用的是普通的 JavaScript 检查。TypeScript 会跟踪控制流，把已经排除的成员一个个去掉，所以到最后一个检查之后只剩下一个成员：

type Input = string | number | string[] | Date | null;

function normalize(input: Input): string {
  if (input === null) return "(empty)";
  if (typeof input === "string") return input.trim();
  if (typeof input === "number") return input.toFixed(1);
  if (Array.isArray(input)) return input.join(", ");
  return input.toISOString().slice(0, 10); // only Date is left
}

const samples: Input[] = ["  hi  ", 3, ["a", "b"], new Date("2024-03-15T10:30:00Z"), null];
for (const s of samples) console.log(normalize(s));
// hi
// 3.0
// a, b
// 2024-03-15
// (empty)

完整的收窄方式请看类型收窄一页。

字面量类型的联合

由字面量值组成的联合类型就是一组封闭的可选值。这是实际代码中最常见的联合类型：

type Status = "idle" | "loading" | "success" | "error";
type Dice = 1 | 2 | 3 | 4 | 5 | 6;
type Toggle = "on" | "off" | boolean; // boolean is itself true | false

let current: Status = "idle";
current = "loading";   // fine
current = "finished";  // error TS2322: Type '"finished"' is not assignable to type 'Status'.

与字面量比较也会收窄：在 if (current === "error") 之后，else 分支知道 current 是另外三个值之一。在很多代码库中，字面量联合取代了枚举；关于 as const 以及如何从数组推导出这样的联合类型，请参阅字面量类型。

对象类型的联合

当成员是对象类型时，所有成员共有的属性可以直接访问。其余属性要先用 in 检查是否存在：

type Cat = { name: string; meow(): string };
type Fish = { name: string; swim(): string };

function act(pet: Cat | Fish): string {
  const intro = `${pet.name}: `; // name exists on both, so it is allowed
  if ("meow" in pet) {
    return intro + pet.meow();   // pet is Cat here
  }
  return intro + pet.swim();     // pet is Fish here
}

const tom: Cat = { name: "Tom", meow: () => "meow" };
const nemo: Fish = { name: "Nemo", swim: () => "swims away" };

console.log(act(tom));  // Tom: meow
console.log(act(nemo)); // Nemo: swims away

如果联合类型包含好几种对象形状，更清晰的写法是加一个共有的字面量属性，例如 kind: "cat" / kind: "fish"。只需检查这一个属性就能收窄整个对象，对它使用 switch 还能检查是否穷尽了所有情况。这种模式就是可辨识联合。

数组与联合类型

括号的位置会彻底改变含义：

const mixed: (string | number)[] = [1, "two", 3]; // each element may be either
const eitherOr: string[] | number[] = ["a", "b"]; // all strings OR all numbers

// @ts-expect-error: Type '(string | number)[]' is not assignable to type 'string[] | number[]'.
const bad: string[] | number[] = ["a", 1];

const precedence: string | number[] = "not an array"; // | binds looser than []

console.log(mixed, eitherOr, precedence);
// [ 1, 'two', 3 ] [ 'a', 'b' ] not an array

const total = mixed.reduce<number>((sum, x) => sum + (typeof x === "number" ? x : 0), 0);
console.log(total); // 4

遍历 (string | number)[] 时，每个元素都是联合类型，需要先收窄，就像上面 reduce 回调里那样。map 和 filter 这类方法也可以用在 string[] | number[] 上，回调收到的参数类型是 string | number。

与 null 和 undefined 的联合

最常见的联合类型是“一个值或者什么都没有”：string | null、User | undefined。Array.prototype.find 和 Map.prototype.get 返回的就是这种类型，可选属性 name?: string 读取时的类型也是 string | undefined。用 ?.、?? 和 null 检查来处理它们的内容在单独的一页：null 和 undefined。

要在类型层面从已有的联合类型中去掉某些成员，可以使用内置工具类型：Exclude<"a" | "b" | "c", "a"> 得到 "b" | "c"，NonNullable<string | null> 得到 string。