TypeScript 工具类型大全：完整列表与示例

工具类型是 TypeScript 内置的泛型类型，用来把一个类型转换成另一个类型。不必再写一个所有字段都可选的 User 类型，直接写 Partial<User>；不必复制三个字段，写 Pick<User, "id" | "name"> 即可。它们是全局的，不需要导入。

interface User {
  id: number;
  name: string;
  email: string;
  password: string;
}

type UserPatch = Partial<User>;                 // every field optional
type UserCard = Pick<User, "id" | "name">;      // only id and name
type PublicUser = Omit<User, "password">;       // everything but password
type UsersById = Record<number, PublicUser>;    // an object keyed by id

const patch: UserPatch = { email: "new@example.com" };
const card: UserCard = { id: 1, name: "Ada" };
const users: UsersById = {
  1: { id: 1, name: "Ada", email: "ada@example.com" },
};

console.log(patch, card, users[1].email);
// { email: 'new@example.com' } { id: 1, name: 'Ada' } ada@example.com

User 改变时，这四个派生类型会自动跟着变。TypeScript 标准库（lib.es5.d.ts）一共声明了 22 个工具类型。下面按作用的类型种类分组列出全部工具类型，有详细页面的附上了链接。

对象类型：Partial、Required、Readonly、Pick、Omit、Record

interface Config {
  host: string;
  port?: number;
  debug?: boolean;
}

const defaults: Required<Omit<Config, "host">> = { port: 8080, debug: false };

function withDefaults(config: Config): Readonly<Required<Config>> {
  return { ...defaults, ...config };
}

const cfg = withDefaults({ host: "localhost", debug: true });
console.log(cfg); // { port: 8080, debug: true, host: 'localhost' }
// cfg.port = 1 would be error TS2540: Cannot assign to 'port' because it is a read-only property.

Required<T> 与 Partial<T> 正好相反；Partial 一页同时讲解了这两者，包括像这里这样的展开运算会放进来的显式 undefined。

联合类型：Exclude、Extract、NonNullable

type Status = "draft" | "review" | "published" | "archived";

type Live = Exclude<Status, "draft" | "archived">; // "review" | "published"
type Mixed = string | number | (() => void);
type Callable = Extract<Mixed, (...args: never[]) => unknown>; // () => void

function lookup(id: number): string | undefined {
  return id === 1 ? "Ada" : undefined;
}
type Found = NonNullable<ReturnType<typeof lookup>>; // string

const s: Live = "review";
const run: Callable = () => console.log("called");
const found: Found = lookup(1) ?? "nobody";
run();
console.log(s, found); // review Ada

这三个工具类型作用于联合类型，而不是对象。这是它们和 Pick、Omit 的关键区别：后两者接收的是一个对象类型和它的一组键。

函数和类：Parameters、ReturnType 等

function createOrder(customer: string, items: string[], express = false) {
  return { customer, items, express, total: items.length * 10 };
}

type OrderArgs = Parameters<typeof createOrder>; // [customer: string, items: string[], express?: boolean | undefined]
type Order = ReturnType<typeof createOrder>;     // { customer: string; items: string[]; express: boolean; total: number }

const args: OrderArgs = ["Ada", ["book", "pen"]];
const order: Order = createOrder(...args);
console.log(order.total, order.express); // 20 false

class Point {
  constructor(public x: number, public y: number) {}
}
const coords: ConstructorParameters<typeof Point> = [3, 4];
const p: InstanceType<typeof Point> = new Point(...coords);
console.log(p); // Point { x: 3, y: 4 }

这里需要写 typeof createOrder，因为这些工具类型接收的是类型，而 createOrder 是一个值。类也一样：typeof Point 是构造函数的类型，而直接把 Point 当作类型使用时，它本身就表示实例类型。

NoInfer 控制泛型从哪里获得类型：

function pickColor<C extends string>(colors: C[], fallback: NoInfer<C>): C {
  return colors[0] ?? fallback;
}

console.log(pickColor(["red", "green"], "green")); // red
// @ts-expect-error: "blue" is not "red" | "green"
pickColor(["red", "green"], "blue");

如果没有 NoInfer，TypeScript 会根据两个实参推断 C，并把它拓宽为 "red" | "green" | "blue"，于是 fallback 中的拼写错误也会被接受。

字符串：Uppercase、Lowercase、Capitalize、Uncapitalize

这四个工具类型内置在编译器中，而不是用 TypeScript 写成的。它们在模板字面量类型中最有用，例如用 `on${Capitalize<E>}` 生成事件处理函数的名字。

Promise：Awaited

async function fetchUser(id: number) {
  return { id, name: "Ada" };
}

type Pending = ReturnType<typeof fetchUser>;           // Promise<{ id: number; name: string }>
type User = Awaited<ReturnType<typeof fetchUser>>;      // { id: number; name: string }

async function main() {
  const user: User = await fetchUser(1);
  const all: User[] = await Promise.all([fetchUser(2), fetchUser(3)]);
  console.log(user.name, all.map((u) => u.id)); // Ada [ 2, 3 ]
}
main();

Awaited<ReturnType<typeof fn>> 是给异步函数的结果类型命名的标准写法，无需另外声明。

组合使用工具类型

工具类型可以嵌套。下面几种组合经常出现，值得熟记：

interface Post {
  id: number;
  title: string;
  body: string;
  tags: string[];
}

// Create: everything except the server-generated id
type NewPost = Omit<Post, "id">;
// Update: id required, everything else optional
type PostUpdate = Pick<Post, "id"> & Partial<Omit<Post, "id">>;
// A lookup table of read-only summaries
type PostIndex = Record<number, Readonly<Pick<Post, "id" | "title">>>;

const created: NewPost = { title: "Hello", body: "...", tags: [] };
const update: PostUpdate = { id: 1, title: "Hello again" };
const index: PostIndex = { 2: { id: 2, title: "Idea" } };
console.log(created.title, update, index[2]);
// Hello { id: 1, title: 'Hello again' } { id: 2, title: 'Idea' }

嵌套的工具类型要从里往外读：Readonly<Pick<Post, "id" | "title">> 先保留两个属性，再把它们设为只读。用同样的组件还能写出只让部分键变成可选的 PartialBy 辅助类型；Partial 一页给出了完整写法。

工具类型在运行时不起任何作用

所有工具类型在代码编译时都会被擦除。类型为 Omit<User, "password"> 的值，如果来源对象带有 password，运行时它依然带着：

interface User {
  name: string;
  password: string;
}

const full: User = { name: "Ada", password: "hunter2" };

const leaky: Omit<User, "password"> = full; // allowed: extra properties are fine
console.log(JSON.stringify(leaky)); // {"name":"Ada","password":"hunter2"}

const { password, ...safe } = full;          // this actually removes it
console.log(JSON.stringify(safe));  // {"name":"Ada"}

类型只限制你的代码能读取什么。要从数据中删掉一个字段，就像最后几行那样用解构把它去掉；要在运行时阻止修改，用 Object.freeze，而不是 Readonly。内置工具类型都是一行写成的映射类型和条件类型，所以你也可以用同样的工具编写自己的工具类型。