Union type trong TypeScript: toán tử | và ví dụ

Một union type liệt kê các lựa chọn bằng |: một giá trị kiểu string | number là chuỗi hoặc là số. Union là cách TypeScript mô tả những giá trị hợp lệ ở nhiều dạng khác nhau, và trình biên dịch buộc bạn kiểm tra xem mình đang có dạng nào trước khi dùng bất cứ thứ gì riêng của dạng đó.

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

Bên trong mỗi nhánh của phép kiểm tra typeof, id chỉ có một kiểu duy nhất. Bước đó gọi là thu hẹp kiểu (narrowing), và chính nó làm cho union trở nên hữu dụng.

Chỉ được dùng thành viên chung

Trước khi thu hẹp, bạn chỉ dùng được những gì mọi thành viên của union đều hỗ trợ. toString() có ở cả chuỗi lẫn số nên dùng được; toUpperCase() chỉ có ở chuỗi:

// 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'.

Dòng thứ hai chỉ ra thành viên thiếu thuộc tính đó. Quy tắc này cũng áp dụng theo chiều ngược lại: một giá trị string | number không thể truyền vào tham số kiểu string (TS2345), vì nó có thể là một số. Union chấp nhận nhiều giá trị hơn, và đổi lại, cho bạn làm ít việc hơn với chúng cho đến khi bạn kiểm tra.

Thu hẹp một union

Thu hẹp kiểu dùng các phép kiểm tra JavaScript thông thường. TypeScript theo dõi luồng điều khiển và loại bỏ dần các thành viên khi chúng bị loại trừ, nên sau phép kiểm tra cuối cùng chỉ còn lại một thành viên:

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)

Danh sách đầy đủ các cách thu hẹp kiểu có ở trang type narrowing.

Union của literal type

Một union các giá trị literal là một tập hợp đóng các giá trị được phép. Đây là loại union phổ biến nhất trong code thực tế:

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'.

So sánh với một literal sẽ thu hẹp kiểu: sau if (current === "error"), nhánh else biết current là một trong ba giá trị còn lại. Union literal thay thế enum trong nhiều codebase; xem literal type để biết về as const và cách tạo một union như vậy từ một mảng.

Union của kiểu đối tượng

Khi các thành viên là kiểu đối tượng, những thuộc tính mà tất cả đều có sẽ dùng được ngay. Với phần còn lại, hãy kiểm tra thuộc tính có tồn tại không bằng 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

Với union gồm nhiều hình dạng đối tượng, cách gọn gàng hơn là một thuộc tính literal dùng chung như kind: "cat" / kind: "fish". Kiểm tra thuộc tính đó sẽ thu hẹp cả đối tượng, và một switch trên thuộc tính đó có thể được kiểm tra xem đã xét hết mọi trường hợp chưa. Mẫu này gọi là discriminated union.

Mảng và union

Vị trí đặt dấu ngoặc làm thay đổi hoàn toàn ý nghĩa:

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

Khi duyệt một (string | number)[], mỗi phần tử là một union và cần được thu hẹp, như trong callback của reduce ở trên. Các phương thức như map và filter cũng dùng được trên string[] | number[], với callback nhận vào string | number.

Union với null và undefined

Loại union phổ biến nhất là "một giá trị hoặc không có gì": string | null, User | undefined. Đó là thứ mà Array.prototype.find và Map.prototype.get trả về, và một thuộc tính tùy chọn name?: string được đọc là string | undefined. Cách xử lý chúng với ?., ?? và kiểm tra null có trang riêng: null và undefined.

Để loại bỏ thành viên khỏi một union có sẵn ở cấp độ kiểu, hãy dùng các tiện ích có sẵn: Exclude<"a" | "b" | "c", "a"> là "b" | "c", và NonNullable<string | null> là string.