TypeScript 模板字面量类型：语法与示例

模板字面量类型用和 JavaScript 模板字符串相同的反引号语法来构建字符串字面量类型。`on${Capitalize<"click" | "focus">}` 就是类型 "onClick" | "onFocus"，由编译器计算得出：

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;

模板字面量类型只存在于编译时。它们在你写代码时检查字符串字面量和带类型的值，不会给输出的 JavaScript 增加任何内容。上面的处理函数表用 Record 来要求每个名字都对应一个函数。

语法

在反引号里写字面文本和 ${...} 占位符。占位符里放的是类型而不是值：字符串、数字、bigint 或布尔字面量类型，它们的联合类型，或者宽泛类型 string、number、bigint、boolean、null 和 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

放入 string 或 number 这类宽泛类型的占位符会形成一种模式：类型保持为 `hello ${string}`，任何匹配的字符串都能被接受。放入有限联合类型（比如 boolean）的占位符则会展开为它的各个成员。

联合类型会相乘

有多个联合类型时，结果是所有的组合：

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

三种尺寸乘以两种色调，得到六个成员。数量增长得很快：五个占位符各放一个包含十个字母的联合类型，就会得到 100,000 个成员，TypeScript 会以 error TS2590: Expression produces a union type that is too complex to represent 拒绝。不需要每个确切值时，就用 ${string} 这样的宽泛占位符。

Uppercase、Lowercase、Capitalize、Uncapitalize

有四个内置类型可以改变字符串字面量类型的大小写。它们是内在类型（intrinsic）：在编译器内部实现，而不是用 TypeScript 写成的。

它们只改变类型。要构建对应的运行时字符串，你仍然需要调用 toUpperCase()，或者自己截取字符串并把首字母大写，再告诉 TypeScript 结果的精确类型：

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

之所以需要 as，是因为 toUpperCase() 的返回类型是普通的 string。调用者看到的是函数签名，所以 capitalize("report") 的类型是字面量类型 "Report"。

字符串模式：${number}px 等

模式类型接受某种形状的所有字符串。它很适合 CSS 值，以及带有已知前缀的 id 和键：

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} 接受 JavaScript 能读作数字的任何字符串，这比看上去要宽松："-3px"、"1e3px" 和 "0x10px" 都能通过类型检查。请把这些模式当作防止字面量拼写错误的保护，而不是完整的校验。

模板字面量与映射类型

模板字面量类型最有用的地方是作为映射类型的 as 子句，用其他属性名生成新的属性名：

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 只保留字符串键，因为 Capitalize 不接受数字或 symbol。每个回调函数的参数类型都来自它所监听的那个属性。

用 infer 解析字符串

在条件类型中，模板字面量可以匹配一个字符串，并用 infer 捕获其中的部分。下面从路由模式中提取参数名：

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

调用时漏掉 postId，编译器就会报告缺少它。

模板表达式会被拓宽为 string

普通代码中的模板字符串表达式的类型是 string，即使它的每个部分都是字面量类型。加上 as const 就能保留模板字面量类型：

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

如果没有 as const，把 loose 赋值给 `log:${Level}` 会失败，因为 string 可能是任何内容。