在 TypeScript 中，函数重载（Function Overload） 是指为同一个函数提供多个不同的调用签名（参数类型和返回值类型的组合），但函数体只有一个实现。这样可以让函数在不同的输入下表现出不同的行为，同时保持类型安全。

一、函数重载的基本概念

1. 重载签名（Overload Signatures）

声明函数可以接受的不同参数类型和返回值类型，但不包含函数体。

2. 实现签名（Implementation Signature）

实际的函数实现，参数类型必须兼容所有重载签名，返回值类型也需符合重载签名的约束。

二、示例：函数重载的使用

1. 基础重载示例

typescript

// 重载签名 1：接受数字，返回数字的平方
function calculate(x: number): number;// 重载签名 2：接受字符串，返回字符串的长度
function calculate(x: string): number;// 实现签名：兼容所有重载签名
function calculate(x: number | string): number {if (typeof x === 'number') {return x * x; // 处理数字} else {return x.length; // 处理字符串}
}// 使用示例
const result1 = calculate(5);     // 返回 25（数字）
const result2 = calculate("abc"); // 返回 3（字符串长度）
// const result3 = calculate(true); // 错误：不匹配任何重载签名

2. 多个参数的重载

typescript

// 重载签名 1：合并两个字符串
function merge(a: string, b: string): string;// 重载签名 2：合并两个数组
function merge(a: number[], b: number[]): number[];// 实现签名
function merge(a: string | number[], b: string | number[]): string | number[] {if (typeof a === 'string' && typeof b === 'string') {return a + b; // 字符串拼接} else if (Array.isArray(a) && Array.isArray(b)) {return [...a, ...b]; // 数组合并}throw new Error("Invalid arguments");
}// 使用示例
const mergedStr = merge("Hello", "World"); // 返回 "HelloWorld"
const mergedArr = merge([1, 2], [3, 4]);    // 返回 [1, 2, 3, 4]

三、函数重载的注意事项

重载签名与实现签名的关系

实现签名的参数类型必须是所有重载签名参数类型的超集。
实现签名的返回值类型必须能赋值给所有重载签名的返回值类型。

typescript

// 错误示例：实现签名的参数类型不兼容重载签名
function add(a: number, b: number): number;
function add(a: string, b: string): string;
function add(a: number | string, b: number): number | string { // 错误：第二个参数必须兼容 stringreturn a + b;
}

重载解析规则
- TypeScript 会从上到下匹配第一个符合参数类型的重载签名。
- 因此，重载签名的顺序很重要，通常应将更具体的签名放在前面。
typescript
```
function fn(x: string): string;
function fn(x: any): any;
function fn(x: any): any { return x; }fn("hello"); // 匹配第一个重载（更具体）
fn(123);     // 匹配第二个重载
```

四、替代方案：联合类型与泛型

对于简单的函数重载场景，可以使用联合类型或泛型替代，使代码更简洁：

1. 联合类型

typescript

function calculate(x: number | string): number {if (typeof x === 'number') {return x * x;} else {return x.length;}
}

2. 泛型

typescript

function identity<T>(arg: T): T {return arg;
}

五、函数重载的应用场景

根据参数类型返回不同类型

typescript

function parseJSON(json: string): any;
function parseJSON(json: null): null;
function parseJSON(json: string | null): any | null {return json ? JSON.parse(json) : null;
}

可选参数的不同组合

typescript

function createElement(tag: string): HTMLElement;
function createElement(tag: string, className: string): HTMLElement;
function createElement(tag: string, className?: string): HTMLElement {const el = document.createElement(tag);if (className) el.className = className;return el;
}

总结

特性	说明
定义方式	先声明多个重载签名，再实现一个兼容所有签名的函数体。
类型检查	调用时必须匹配某个重载签名，实现签名内部需自行处理类型逻辑。
适用场景	函数需要根据不同参数类型返回不同类型，或处理多种参数组合。
替代方案	简单场景可使用联合类型或泛型，但函数重载能提供更精确的类型控制。