Template literal type trong TypeScript: cú pháp và ví dụ

Template literal type tạo ra string literal type bằng đúng cú pháp backtick của template string trong JavaScript. `on${Capitalize<"click" | "focus">}` là kiểu "onClick" | "onFocus", do trình biên dịch tính ra:

type DomEvent = "click" | "focus" | "blur";

type HandlerName = `on${Capitalize<DomEvent>}`;
// "onClick" | "onFocus" | "onBlur"

const handlers: Record<HandlerName, () => string> = {
  onClick: () => "clicked",
  onFocus: () => "focused",
  onBlur: () => "blurred",
};

console.log(handlers.onFocus()); // focused
// @ts-expect-error: "onHover" is not one of the handler names
handlers.onHover;

Template literal type chỉ tồn tại lúc biên dịch. Chúng kiểm tra chuỗi literal và các giá trị có kiểu trong lúc bạn viết code; chúng không thêm gì vào đầu ra JavaScript. Bảng handler ở trên dùng Record để bắt buộc mỗi tên phải có một hàm.

Cú pháp

Bên trong dấu backtick, bạn viết văn bản literal và các placeholder ${...}. Một placeholder chứa một kiểu, không phải một giá trị: một literal type kiểu string, number, bigint hoặc boolean, một union của chúng, hoặc một trong các kiểu rộng string, number, bigint, boolean, null và undefined.

type Greeting = `hello ${string}`;   // any string that starts with "hello "
type Version = `v${number}`;         // "v1", "v2.5", ...
type Toggle = `is-${boolean}`;       // "is-true" | "is-false"

const g: Greeting = "hello Ada";
const v: Version = "v3";
const t: Toggle = "is-false";

// @ts-expect-error: Type '"hi Ada"' is not assignable to type '`hello ${string}`'
const wrong: Greeting = "hi Ada";

console.log(g, v, t); // hello Ada v3 is-false

Một placeholder với kiểu rộng như string hay number tạo ra một mẫu: kiểu vẫn giữ nguyên là `hello ${string}` và mọi chuỗi khớp mẫu đều được chấp nhận. Một placeholder với union hữu hạn, như boolean, được mở rộng thành từng thành viên của nó.

Union nhân lên

Với nhiều union, kết quả là mọi tổ hợp:

type Size = "sm" | "md" | "lg";
type Tone = "primary" | "danger";

type ButtonClass = `btn-${Size}-${Tone}`;
// "btn-sm-primary" | "btn-sm-danger" | "btn-md-primary" | ... (6 members)

function button(cls: ButtonClass): string {
  return `<button class="${cls}">`;
}

console.log(button("btn-lg-danger")); // <button class="btn-lg-danger">
// button("btn-xl-danger") would be error TS2345

Ba kích thước nhân hai tông màu cho ra sáu thành viên. Số lượng tăng rất nhanh: năm placeholder, mỗi cái chứa một union mười chữ cái, sẽ là 100.000 thành viên, và TypeScript từ chối với error TS2590: Expression produces a union type that is too complex to represent. Hãy dùng một placeholder rộng như ${string} khi bạn không cần từng giá trị chính xác.

Uppercase, Lowercase, Capitalize, Uncapitalize

Bốn kiểu có sẵn đổi chữ hoa chữ thường của string literal type. Chúng là kiểu nội tại (intrinsic): được cài đặt bên trong trình biên dịch, không viết bằng TypeScript.

Chúng chỉ thay đổi kiểu. Để tạo chuỗi tương ứng lúc chạy, bạn vẫn gọi toUpperCase() hoặc tự cắt chuỗi rồi viết hoa, và báo cho TypeScript biết kết quả có kiểu chính xác:

function capitalize<S extends string>(s: S): Capitalize<S> {
  return (s.charAt(0).toUpperCase() + s.slice(1)) as Capitalize<S>;
}

const title = capitalize("report"); // type "Report"
const loud: Uppercase<"ok"> = "OK";

console.log(title, loud); // Report OK

Cần dùng as vì toUpperCase() được khai báo là trả về string thông thường. Chữ ký của hàm là thứ nơi gọi nhìn thấy, nên capitalize("report") có literal type "Report".

Mẫu chuỗi: ${number}px và các dạng tương tự

Một kiểu mẫu chấp nhận mọi chuỗi có hình dạng cho trước. Nó tiện cho giá trị CSS, id và khóa có tiền tố biết trước:

type Pixels = `${number}px`;
type UserId = `user_${string}`;
type Semver = `${number}.${number}.${number}`;

function setWidth(w: Pixels) {
  return `width: ${w}`;
}

const id: UserId = "user_42";
const version: Semver = "7.0.2";

console.log(setWidth("120px"), id, version); // width: 120px user_42 7.0.2
// setWidth("120") and setWidth("wide px") would both be error TS2345

${number} chấp nhận mọi chuỗi mà JavaScript đọc được thành số, lỏng hơn bạn tưởng: "-3px", "1e3px" và "0x10px" đều qua được kiểm tra kiểu. Hãy coi các mẫu này là cách chặn lỗi gõ sai trong literal, không phải phép kiểm tra hợp lệ đầy đủ.

Template literal với mapped type

Template literal type hữu ích nhất khi làm mệnh đề as của một mapped type, nơi chúng sinh ra tên thuộc tính từ những tên thuộc tính khác:

type Watchers<T> = {
  [K in keyof T as `on${Capitalize<string & K>}Change`]: (value: T[K]) => void;
};

type Form = { email: string; age: number };

// { onEmailChange: (value: string) => void; onAgeChange: (value: number) => void }
const watch: Watchers<Form> = {
  onEmailChange: (v) => console.log("email is now", v),
  onAgeChange: (v) => console.log("age is now", v.toFixed(0)), // v is number
};

watch.onEmailChange("ada@example.com"); // email is now ada@example.com
watch.onAgeChange(37);                  // age is now 37

string & K chỉ giữ lại các khóa kiểu chuỗi, vì Capitalize không nhận số hay symbol. Mỗi callback nhận kiểu tham số từ chính thuộc tính mà nó theo dõi.

Phân tích chuỗi bằng infer

Trong một conditional type, template literal có thể khớp với một chuỗi và bắt lấy từng phần của nó bằng infer. Ví dụ này lấy ra tên các tham số từ một mẫu route:

type RouteParams<S extends string> =
  S extends `${string}:${infer Param}/${infer Rest}`
    ? Param | RouteParams<`/${Rest}`>
    : S extends `${string}:${infer Param}`
      ? Param
      : never;

type P = RouteParams<"/users/:userId/posts/:postId">; // "userId" | "postId"

function link<S extends string>(pattern: S, params: Record<RouteParams<S>, string>): string {
  return pattern.replace(/:(\w+)/g, (_, key: string) => params[key as RouteParams<S>]);
}

console.log(link("/users/:userId/posts/:postId", { userId: "7", postId: "42" }));
// /users/7/posts/42

Bỏ postId trong lời gọi hàm, trình biên dịch sẽ báo là thiếu.

Biểu thức template bị mở rộng thành string

Một biểu thức template string trong code thông thường có kiểu string, kể cả khi mọi phần của nó đều là literal type. Thêm as const để giữ template literal type:

type Level = "info" | "warn";

function tag(level: Level) {
  const loose = `log:${level}`;          // string
  const exact = `log:${level}` as const; // "log:info" | "log:warn"
  return { loose, exact };
}

const { exact } = tag("warn");
const again: `log:${Level}` = exact; // OK: the exact type fits
console.log(exact, again);           // log:warn log:warn

Không có as const, gán loose cho `log:${Level}` sẽ thất bại, vì string có thể là bất cứ chuỗi nào.