TypeScript 断言用于告诉编译器「你比它更了解类型」，让编译器信任开发者的判断。

1. 类型断言 (Type Assertions)

基本语法

1
2
3
4
5
6
7
// 方式1: 尖括号语法
let someValue: any = "this is a string";
let strLength: number = (<string>someValue).length;

// 方式2: as 语法 (推荐，尤其在 JSX 中)
let strLengthAs: number = (someValue as string).length;

常见使用场景

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// 1. 将 any 断言为具体类型
let unknownValue: any = "hello world";
let str1: string = (<string>unknownValue);
let str2: string = (unknownValue as string);

// 2. 将联合类型断言为其中一个类型
interface Cat {
  name: string;
  meow(): void;
}

interface Dog {
  name: string;
  bark(): void;
}

function getPet(): Cat | Dog {
  return { name: "Buddy", meow: () => console.log("meow") } as Cat;
}

let pet = getPet();
(pet as Cat).meow(); // 断言为 Cat 类型

// 3. 将父类断言为更具体的子类
class Animal {
  constructor(public name: string) {}
}

class Bird extends Animal {
  fly() {
    console.log(`${this.name} is flying`);
  }
}

let animal: Animal = new Bird("Sparrow");
(animal as Bird).fly(); // 断言为 Bird 类型

2. 非空断言 (Non-null Assertion)

使用 ! 运算符断言值不为 null 或 undefined。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// 1. 变量非空断言
function liveDangerously(x?: number | null) {
  // 使用非空断言，告诉编译器 x 不会是 null 或 undefined
  console.log(x!.toFixed());
}

// 2. 函数调用非空断言
interface User {
  name: string;
  address?: {
    street: string;
    city: string;
  };
}

let user: User = { name: "John" };
console.log(user.address!.city); // 断言 address 存在

// 3. 数组访问非空断言
let array: number[] = [1, 2, 3];
let firstElement = array[0]!; // 断言第一个元素存在

// 4. 与可选链结合使用
let city = user.address?.city!; // 如果 address 存在，则 city 一定存在

3. 常量断言 (Const Assertions)

使用 as const 将类型收窄为最具体的字面量类型。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// 1. 基本类型常量断言
let x = "hello" as const; // 类型: "hello"
let y = 42 as const; // 类型: 42
let z = true as const; // 类型: true

// 2. 数组常量断言
let array = [1, 2, 3] as const; // 类型: readonly [1, 2, 3]
// array[0] = 4; // 错误: 无法分配到 "0"，因为它是只读属性

// 3. 对象常量断言
const user = {
  name: "Alice",
  age: 30,
  hobbies: ["reading", "swimming"]
} as const;

// user.name = "Bob"; // 错误: 无法分配到 "name"，因为它是只读属性
// user.hobbies.push("coding"); // 错误: 属性 'push' 在类型 'readonly ["reading", "swimming"]' 上不存在

// 4. 函数返回常量断言
function getConfig() {
  return {
    host: "localhost",
    port: 8080,
    ssl: true
  } as const;
}

const config = getConfig();
// config.host = "127.0.0.1"; // 错误: 无法分配到 "host"

4. 断言函数 (Assertion Functions)

用于在运行时验证条件，并在类型层面反映验证结果。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// 1. 断言函数 - 简单形式
function assert(condition: any, msg?: string): asserts condition {
  if (!condition) {
    throw new Error(msg);
  }
}

function processValue(value: number | string) {
  assert(typeof value === "number", "Value must be a number");
  // 这里 value 的类型被收窄为 number
  return value.toFixed(2);
}

// 2. 断言函数 - 类型谓词形式
function isString(value: any): value is string {
  return typeof value === "string";
}

function assertIsString(value: any): asserts value is string {
  if (!isString(value)) {
    throw new Error("Value must be a string");
  }
}

function example(x: number | string) {
  assertIsString(x);
  // 这里 x 的类型被收窄为 string
  return x.toUpperCase();
}

// 3. 复杂类型断言函数
interface Cat {
  meow(): void;
}

interface Dog {
  bark(): void;
}

function isCat(pet: Cat | Dog): pet is Cat {
  return (pet as Cat).meow !== undefined;
}

function assertIsCat(pet: Cat | Dog): asserts pet is Cat {
  if (!isCat(pet)) {
    throw new Error("Pet is not a cat");
  }
}

5. 双重断言 (Double Assertion)

当两种类型没有直接关系时，可以先断言为 any 或 unknown。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// 1. 双重断言示例
interface ButtonProps {
  onClick: () => void;
  children: string;
}

interface DivProps {
  className: string;
  children: React.ReactNode;
}

let buttonProps: ButtonProps = {
  onClick: () => console.log("clicked"),
  children: "Click me"
};

// 直接断言会报错，因为 ButtonProps 和 DivProps 不兼容
// let divProps: DivProps = buttonProps as DivProps; // 错误

// 使用双重断言
let divProps: DivProps = buttonProps as any as DivProps;

// 2. 更安全的做法 - 使用 unknown
let saferDivProps: DivProps = buttonProps as unknown as DivProps;

// 3. 实际应用场景 - 处理第三方库类型
function handleEvent(event: Event) {
  // 假设我们需要 MouseEvent 的特有属性
  const mouseEvent = event as unknown as MouseEvent;
  console.log(mouseEvent.clientX, mouseEvent.clientY);
}

6. 实际应用示例

示例 1: DOM 操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 1. 获取 DOM 元素
const input = document.getElementById("myInput") as HTMLInputElement;
input.value = "Hello"; // 现在可以访问 HTMLInputElement 的属性

// 2. 事件处理
const button = document.querySelector(".submit-btn") as HTMLButtonElement;
button.addEventListener("click", (e: Event) => {
  const mouseEvent = e as MouseEvent;
  console.log(`Clicked at: ${mouseEvent.clientX}, ${mouseEvent.clientY}`);
});

// 3. 非空断言在 DOM 中的使用
const form = document.getElementById("myForm")!; // 确定这个元素存在
form.addEventListener("submit", handleSubmit);

示例 2: API 响应处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
interface ApiResponse<T> {
  data: T;
  status: "success" | "error";
  message?: string;
}

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

// 假设我们从 API 获取数据
async function fetchUser(userId: number): Promise<User> {
  const response = await fetch(`/api/users/${userId}`);
  const result = await response.json() as ApiResponse<User>;

  // 使用断言确保数据格式
  if (result.status === "success") {
    return result.data;
  } else {
    throw new Error(result.message);
  }
}

// 使用常量断言定义配置
const API_CONFIG = {
  baseUrl: "https://api.example.com",
  timeout: 5000,
  retries: 3
} as const;

示例 3: 状态管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
type AppState = {
  user: {
    id: number;
    name: string;
    email: string;
  } | null;
  loading: boolean;
  error: string | null;
};

function updateUserProfile(state: AppState, updates: Partial<AppState["user"]>) {
  // 使用非空断言，因为我们确定此时 user 存在
  const currentUser = state.user!;

  return {
    ...state,
    user: {
      ...currentUser,
      ...updates
    }
  };
}

// 使用断言函数进行运行时验证
function validateUser(user: any): user is AppState["user"] {
  return user &&
          typeof user.id === "number" &&
          typeof user.name === "string" &&
          typeof user.email === "string";
}

function setUser(state: AppState, userData: any) {
  if (validateUser(userData)) {
    state.user = userData;
  } else {
    throw new Error("Invalid user data");
  }
}

7. 最佳实践和注意事项

应该使用断言的情况：

  1. DOM 操作：确定元素类型时
  2. API 响应：处理已知结构的数据时
  3. 测试代码：模拟特定场景时
  4. 迁移代码：从 JavaScript 迁移时

应该避免的情况：

1
2
3
4
5
6
7
8
9
10
11
12
13
// ❌ 错误的用法 - 掩盖了真正的类型错误
let value: string = "hello";
let numberValue = value as any as number; // 危险！

// ✅ 更好的做法 - 进行类型检查
function safeConvert(str: string): number {
  const num = Number(str);
  if (isNaN(num)) {
    throw new Error("Invalid number");
  }
  return num;
}

断言 vs 类型守卫：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// 使用类型守卫 (更安全)
function isNumber(value: any): value is number {
  return typeof value === "number";
}

function process(value: string | number) {
  if (isNumber(value)) {
    // TypeScript 知道这里 value 是 number
    return value.toFixed(2);
  } else {
    // TypeScript 知道这里 value 是 string
    return value.toUpperCase();
  }
}

// 使用断言 (需要开发者确保正确性)
function processWithAssert(value: string | number) {
  // 开发者需要确保 value 确实是 number
  return (value as number).toFixed(2);
}

总结：断言是 TypeScript 中的强大工具，但应该谨慎使用。优先考虑类型守卫和正确的类型设计，只在确实比编译器更了解类型的情况下使用断言。