TypeScript 速查表

快速查阅 TypeScript 常用语法和类型。

基本类型

// 基本类型
let str: string = "hello";
let num: number = 123;
let bool: boolean = true;

// 数组
let arr1: number[] = [1, 2, 3];
let arr2: Array<string> = ["a", "b", "c"];

// 元组
let tuple: [string, number] = ["hello", 123];

// 枚举
enum Color { Red, Green, Blue }
let color: Color = Color.Red;

// 特殊类型
let any: any = "anything";
let unknown: unknown = "value";
let void: void = undefined;
let never: never;  // 永不返回
let null: null = null;
let undefined: undefined = undefined;

接口与类型别名

// 接口
interface User {
    id: number;
    name: string;
    age?: number;           // 可选属性
    readonly email: string; // 只读属性
}

// 类型别名
type ID = string | number;
type Point = { x: number; y: number };
type Callback = (data: string) => void;

// 接口继承
interface Animal { name: string; }
interface Dog extends Animal { breed: string; }

// 交叉类型
type Person = Name & Age;

函数

// 函数类型
function add(a: number, b: number): number {
    return a + b;
}

// 箭头函数
const multiply = (a: number, b: number): number => a * b;

// 可选参数与默认参数
function greet(name: string, greeting?: string): string
function greet(name: string, greeting: string = "Hello"): string

// 剩余参数
function sum(...numbers: number[]): number

// 函数重载
function convert(value: number): string;
function convert(value: string): number;
function convert(value: number | string): number | string

类

class Person {
    // 属性
    private name: string;
    protected age: number;
    public email: string;
    readonly id: number;
    static count: number = 0;
    
    // 构造函数
    constructor(name: string, age: number) {
        this.name = name;
        this.age = age;
    }
    
    // 方法
    greet(): string {
        return `Hello, I'm ${this.name}`;
    }
    
    // Getter/Setter
    get fullName(): string {
        return this.name;
    }
    
    set fullName(value: string) {
        this.name = value;
    }
}

// 继承
class Employee extends Person {
    constructor(name: string, age: number, private salary: number) {
        super(name, age);
    }
}

// 实现接口
interface Printable { print(): void; }
class Document implements Printable {
    print() { console.log("打印"); }
}

泛型

// 泛型函数
function identity<T>(arg: T): T {
    return arg;
}

// 泛型接口
interface Container<T> {
    value: T;
    getValue(): T;
}

// 泛型类
class Box<T> {
    constructor(private value: T) {}
    getValue(): T { return this.value; }
}

// 泛型约束
interface Lengthwise { length: number; }
function logLength<T extends Lengthwise>(arg: T): void

// 多类型参数
function pair<K, V>(key: K, value: V): [K, V]

// 默认类型
interface ApiResponse<T = any> { data: T; }

类型守卫

// typeof
if (typeof value === "string") { ... }

// instanceof
if (obj instanceof Date) { ... }

// in 操作符
if ("name" in obj) { ... }

// 自定义类型守卫
function isUser(obj: any): obj is User {
    return "name" in obj && "email" in obj;
}

// 类型谓词
function isAdmin(user: User | Admin): user is Admin

工具类型

// Partial - 所有属性可选
type PartialUser = Partial<User>;

// Required - 所有属性必需
type RequiredUser = Required<User>;

// Readonly - 所有属性只读
type ReadonlyUser = Readonly<User>;

// Pick - 选取部分属性
type UserName = Pick<User, "name" | "email">;

// Omit - 排除部分属性
type UserWithoutId = Omit<User, "id">;

// Record - 创建对象类型
type UserMap = Record<string, User>;

// ReturnType - 获取返回类型
type Result = ReturnType<typeof func>;

// Parameters - 获取参数类型
type Params = Parameters<typeof func>;

// NonNullable - 排除 null 和 undefined
type NonNull = NonNullable<string | null | undefined>;

// Extract - 提取类型
type Strings = Extract<string | number, string>;

// Exclude - 排除类型
type Numbers = Exclude<string | number, string>;

条件类型

// 基本条件类型
type IsString<T> = T extends string ? true : false;

// infer 关键字
type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
type Parameters<T> = T extends (...args: infer P) => any ? P : never;
type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;

satisfies 操作符（TS 4.9+）

// 验证类型约束，同时保留具体类型
type Colors = Record<string, string | number[]>;

const palette = {
    red: "#FF0000",
    blue: [0, 0, 255],
    green: "#00FF00"
} satisfies Colors;

// palette.red 是 string 类型（不是 string | number[]）
// palette.blue 是 number[] 类型
palette.red.toUpperCase();  // OK
palette.blue.push(128);     // OK

// 与类型注解的区别
const palette2: Colors = { red: "#FF0000", blue: [0, 0, 255] };
// palette2.red 是 string | number[] 类型，丢失了具体信息

const 类型参数（TS 5.0+）

// 没有 const 修饰符 - 推断为 string[]
function getNames<T extends readonly string[]>(names: T): T {
    return names;
}
const names1 = getNames(["Alice", "Bob"]);
// names1 类型是 string[]

// 有 const 修饰符 - 推断为字面量元组
function getNamesConst<const T extends readonly string[]>(names: T): T {
    return names;
}
const names2 = getNamesConst(["Alice", "Bob"]);
// names2 类型是 readonly ["Alice", "Bob"]

// 实际应用：精确的事件类型
function createEmitter<const T extends readonly string[]>(
    ...events: T
): { on<E extends T[number]>(event: E, handler: () => void): void } {
    // 实现...
    return { on: () => {} };
}

const emitter = createEmitter("click", "focus");
emitter.on("click", () => {});    // OK
// emitter.on("hover", () => {}); // 错误：hover 不是有效事件

标准装饰器（TS 5.0+）

// ECMAScript 标准装饰器（推荐）
function logged(
    target: any,
    context: ClassMethodDecoratorContext
) {
    const methodName = String(context.name);
    return function (this: any, ...args: any[]) {
        console.log(`调用 ${methodName}`);
        return target.call(this, ...args);
    };
}

class Example {
    @logged
    method() {}
}

// 自动访问器
class Counter {
    accessor count = 0;  // 自动创建 getter/setter
    
    @logged
    accessor name = "default";  // 可装饰
}

映射类型

// 基本映射
type Readonly<T> = { readonly [K in keyof T]: T[K] };
type Partial<T> = { [K in keyof T]?: T[K] };

// 键重映射
type Getters<T> = {
    [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

// 过滤属性
type StringProps<T> = {
    [K in keyof T as T[K] extends string ? K : never]: T[K];
};

模板字面量类型

type EventName = `on${Capitalize<string>}`;
type Greeting = `hello ${string}`;

// 内置字符串工具类型
type Upper = Uppercase<"hello">;      // "HELLO"
type Lower = Lowercase<"HELLO">;      // "hello"
type Cap = Capitalize<"hello">;       // "Hello"
type Uncap = Uncapitalize<"Hello">;   // "hello"

声明文件

// 声明变量
declare const API_URL: string;
declare function fetch(url: string): Promise<Response>;

// 声明模块
declare module "my-library" {
    export function doSomething(value: string): number;
    export interface Config {
        timeout: number;
    }
}

// 声明全局类型
declare global {
    interface Window {
        myCustomProperty: string;
    }
}

// 扩展模块
declare module "express" {
    interface Request {
        user?: User;
    }
}

tsconfig.json 常用配置

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "sourceMap": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

常用操作符

操作符	用途	示例
|	联合类型	string | number
&	交叉类型	Name & Age
keyof	获取键类型	keyof User
typeof	获取类型	typeof obj
infer	类型推断	infer R
as	类型断言	value as string
!	非空断言	obj!.property
?.	可选链	obj?.property
??	空值合并	value ?? default
satisfies	类型验证（TS 4.9+）	obj satisfies Type

常见错误解决

// 对象字面量额外属性检查
const user: User = { name: "张三", extra: 1 } as User;

// 绕过只读检查
const arr: ReadonlyArray<number> = [1, 2, 3];
const mutable = arr as number[];

// 类型守卫避免错误
if (value && typeof value === "object") {
    // value 是对象
}

// 类型断言解决不确定类型
const element = document.getElementById("app") as HTMLDivElement;