TypeScript 类型别名：type 关键字用法与示例

类型别名就是给一个类型起名字。写下 type Name = ... 之后，凡是需要类型的地方都可以使用 Name。和接口不同，别名可以命名任何类型，而不只是对象形状。

type UserId = string;                         // a primitive
type Point = { x: number; y: number };        // an object shape
type Status = "active" | "banned";            // a union of literals
type Pair = [string, number];                 // a tuple
type Formatter = (value: number) => string;   // a function

const id: UserId = "u_42";
const start: Point = { x: 0, y: 0 };
const current: Status = "active";
const entry: Pair = ["score", 90];
const money: Formatter = (v) => `$${v.toFixed(2)}`;

console.log(id, start, current, entry, money(3.5));
// u_42 { x: 0, y: 0 } active [ 'score', 90 ] $3.50

别名只存在于编译期。编译出的 JavaScript 中不会有任何一行 type。

语法

type Name = SomeType;
type Name<T> = SomeTypeUsing<T>;       // generic
export type Name = SomeType;           // exported from a module

按照惯例，名字使用 PascalCase。等号右边可以是任何类型表达式，别名也可以使用其他别名，包括它自己（见下文的递归类型）。别名在声明它的整个作用域内都可用，甚至在声明那一行之前也可以，因为类型是在编译期检查的，不会像 const 或 let 那样按顺序执行。

对象类型

描述对象形状时，别名和接口的写法几乎一样。别名使用 =，通常以分号结尾。

type User = {
  id: number;
  name: string;
  email?: string;           // optional
  readonly createdAt: string; // cannot be reassigned
};

type Admin = User & { permissions: string[] }; // extend with an intersection

const root: Admin = {
  id: 1,
  name: "root",
  createdAt: "2024-03-15",
  permissions: ["*"],
};

console.log(`${root.name} can do ${root.permissions.join(", ")}`); // root can do *

别名不能使用 extends，交叉类型 & 承担了这个角色。多余属性检查、可选属性和只读属性的行为与接口完全相同。描述对象形状时该选哪一个，在 interface 与 type 的对比页面中有讲解。

联合类型、元组和函数

这些是只有别名才能命名的情况，也是 type 存在的主要原因。联合类型别名列出所有可选类型，元组别名固定数组的长度和元素类型，函数别名描述一个函数签名。

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

type Span = [start: number, end: number]; // labeled tuple elements

type Transform = (shape: Shape, factor: number) => Shape;

const scale: Transform = (shape, factor) =>
  shape.kind === "circle"
    ? { kind: "circle", radius: shape.radius * factor }
    : { kind: "rect", width: shape.width * factor, height: shape.height * factor };

const r: Span = [10, 20];
console.log(scale({ kind: "circle", radius: 2 }, 3)); // { kind: 'circle', radius: 6 }
console.log(r[1] - r[0]);                              // 10

在 scale 中，参数不需要标注类型：Transform 别名已经提供了它们的类型。元组语法在 元组 中讲解，联合类型的收窄在联合类型页面中讲解。

泛型类型别名

类型参数让一个别名适用于多种类型。和函数参数一样，类型参数也可以有默认值。

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0
    ? { ok: true, value: n }
    : { ok: false, error: `not an age: ${text}` };
}

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? `age ${r.value}` : r.error);
}
// age 36
// not an age: abc

Result<number> 使用了默认值 E = string。在实际代码中，type Nullable<T> = T | null 或 type Dict<T> = Record<string, T> 这样的小型泛型别名很常见。内置的工具类型（Partial<T>、Pick<T, K>、ReturnType<F>）也是泛型别名，声明在标准库中。

别名只是名字，不是新类型

别名不会创建一个独立的类型。它只是右边那个类型的第二个名字，编译器把两者视为完全相同。两个 string 的别名可以完全互换：

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: UserId and OrderId are both just string

这段代码输出 cancelling u_42，没有任何错误，这正是别名无法防止的 bug。别名对阅读代码的人仍有帮助（类型为 OrderId 的参数比 string 表达得更多），但如果混用两种 id 必须是编译错误，就要使用品牌类型，例如 string & { readonly __brand: "OrderId" }。

递归类型别名

别名可以引用自身，树、嵌套列表和 JSON 就是这样描述的：

type Json =
  | string
  | number
  | boolean
  | null
  | Json[]
  | { [key: string]: Json };

type TreeNode = {
  value: number;
  children: TreeNode[];
};

function sum(node: TreeNode): number {
  return node.value + node.children.reduce((total, child) => total + sum(child), 0);
}

const tree: TreeNode = {
  value: 1,
  children: [
    { value: 2, children: [] },
    { value: 3, children: [{ value: 4, children: [] }] },
  ],
};

const payload: Json = { ok: true, items: [1, "two", null], meta: { page: 1 } };

console.log(sum(tree));               // 10
console.log(JSON.stringify(payload)); // {"ok":true,"items":[1,"two",null],"meta":{"page":1}}

Json 别名会拒绝 JSON 无法表示的值：把 { when: new Date() } 或 { f: undefined } 赋给 Json 都是编译错误（TS2322）。

从值得到类型：typeof

如果值已经存在，可以直接拿到它的类型并命名，而不必手写一遍。typeof 类型运算符读取一个变量的类型，还可以和其他运算符组合使用：

const defaults = { retries: 3, verbose: false, level: "info" };

type Options = typeof defaults;
// { retries: number; verbose: boolean; level: string }

type OptionKey = keyof typeof defaults;
// "retries" | "verbose" | "level"

function start(port: number) {
  return { port, startedAt: new Date() };
}
type Server = ReturnType<typeof start>;
// { port: number; startedAt: Date }

值始终是唯一的数据来源：给 defaults 添加一个属性，Options 也会跟着变。更多内容见 typeof。

导出和导入别名

别名的导出和导入方式与值相同。import type 明确表示只导入类型，所以这条导入语句总会从 JavaScript 输出中移除：

// shapes.ts
export type Point = { x: number; y: number };
export type Shape = { kind: "circle"; center: Point; radius: number };

// main.ts
import type { Point, Shape } from "./shapes.js";

const p: Point = { x: 1, y: 2 };