TypeScript 函数重载（Overloads）

本文献给：

已掌握 TypeScript 函数参数与返回值类型注解、可选参数、剩余参数及函数类型表达式的开发者。本文将讲解函数重载的设计原因、语法规则（重载签名与实现签名）及使用限制，帮助你在不同参数类型或数量下返回正确类型。

你将学到：

为什么需要函数重载
重载签名与实现签名的区别与配合
参数类型不同、参数个数不同的重载示例
箭头函数不支持重载的原因与替代方案
常见错误（实现签名不可调用、顺序问题等）

一、为什么需要重载
- [1.1 问题场景](#1.1 问题场景)
- [1.2 重载的解决方案](#1.2 重载的解决方案)
二、重载语法与规则
- [2.1 重载签名（Overload Signatures）](#2.1 重载签名（Overload Signatures）)
- [2.2 实现签名（Implementation Signature）](#2.2 实现签名（Implementation Signature）)
- [2.3 重载解析规则](#2.3 重载解析规则)
- [2.4 参数数量不同的重载](#2.4 参数数量不同的重载)
- [2.5 参数类型不同的重载](#2.5 参数类型不同的重载)
[三、重载 vs 联合类型](#三、重载 vs 联合类型)
四、箭头函数不支持重载
五、常见错误与注意事项
- [5.1 实现签名可调用但不应被外部调用](#5.1 实现签名可调用但不应被外部调用)
- [5.2 重载签名顺序不当导致匹配错误](#5.2 重载签名顺序不当导致匹配错误)
- [5.3 实现签名不够兼容](#5.3 实现签名不够兼容)
- [5.4 不必要的重载](#5.4 不必要的重载)
- [5.5 重载与泛型](#5.5 重载与泛型)
六、综合示例
七、小结

一、为什么需要重载

1.1 问题场景

在 JavaScript 中，同一个函数可能根据传入参数的类型或数量执行不同逻辑并返回不同类型。TypeScript 的类型系统需要准确描述这种关系。

例如，一个函数接收字符串或字符串数组，分别返回翻转后的字符串或翻转后的数组：

typescript 复制代码

function reverse(input: string | string[]): string | string[] {
    if (typeof input === "string") {
        return input.split("").reverse().join("");
    } else {
        return [...input].reverse();
    }
}

const revStr = reverse("hello");   // 类型推断为 string | string[]
const revArr = reverse(["a","b"]); // 类型推断为 string | string[]

问题：调用者知道传入的是字符串，返回的也一定是字符串，但 TypeScript 推断的是联合类型，丢失了精确信息。

1.2 重载的解决方案

通过声明多个重载签名 （overload signatures），告诉 TypeScript 不同参数组合对应的返回值类型，再提供一个实现签名（implementation signature）来实际执行逻辑。

typescript 复制代码

// 重载签名
function reverse(input: string): string;
function reverse(input: string[]): string[];

// 实现签名
function reverse(input: string | string[]): string | string[] {
    if (typeof input === "string") {
        return input.split("").reverse().join("");
    } else {
        return [...input].reverse();
    }
}

const revStr = reverse("hello");   // 类型为 string
const revArr = reverse(["a","b"]); // 类型为 string[]

二、重载语法与规则

2.1 重载签名（Overload Signatures）

写在实现签名之前，可以有多个。
每个重载签名包含参数列表和返回值类型，没有函数体。
参数类型必须具体，不能是联合类型（实现签名中的联合类型是内部使用的）。

typescript 复制代码

function makeDate(timestamp: number): Date;           // 重载1
function makeDate(year: number, month: number, day: number): Date; // 重载2
function makeDate(...args: number[]): Date {           // 实现签名
    if (args.length === 1) {
        return new Date(args[0]);
    } else if (args.length === 3) {
        return new Date(args[0], args[1], args[2]);
    }
    throw new Error("Invalid arguments");
}

2.2 实现签名（Implementation Signature）

必须兼容所有重载签名（参数类型和返回值类型要能覆盖）。
实现签名本身不能直接被调用，只有重载签名暴露给外部。
实现签名中的参数类型通常使用联合类型或可选参数来匹配重载。

2.3 重载解析规则

TypeScript 编译器按顺序匹配重载签名，选择第一个匹配的。因此，应将更具体的重载放在前面，更宽泛的放在后面。

typescript 复制代码

function fn(x: string): string;
function fn(x: number): number;
function fn(x: any): any { return x; }

fn("a");  // 匹配第一个，返回 string
fn(1);    // 匹配第二个，返回 number

如果将 number 重载放在 string 前面，对字符串调用仍会匹配第二个（因为 string 可赋值给 any，但 string 不能赋值给 number，所以不匹配），顺序会影响能否找到正确重载。

2.4 参数数量不同的重载

重载可以基于参数个数区分，但需要实现签名中处理可选参数或剩余参数。

typescript 复制代码

function format(): string;
function format(prefix: string): string;
function format(prefix?: string): string {
    return prefix ? `${prefix}: data` : "data";
}

2.5 参数类型不同的重载

typescript 复制代码

function getLength(value: string): number;
function getLength(value: any[]): number;
function getLength(value: any): number {
    return value.length;
}

getLength("hello"); // 5
getLength([1,2,3]); // 3

注意：如果两个重载的参数类型有重叠（例如 string 和 any），需要确保顺序或使用更精确的类型。

三、重载 vs 联合类型

很多场景下可以用联合类型参数配合类型守卫，而不必使用重载。但重载在返回值类型不同且与参数类型有精确映射关系时更有优势。

场景	推荐方式	原因
参数类型不同，返回值类型也不同（且一一对应）	重载	返回值类型精确
参数类型不同，返回值类型相同	联合类型参数	代码更简洁
参数是联合类型，返回值也是联合类型但无映射关系	联合类型参数 + 类型守卫	避免重载冗余

示例：返回值类型相同，不需要重载。

typescript 复制代码

// 不需要重载
function log(value: string | number): void {
    console.log(value);
}

示例：返回值类型与参数类型一一对应，重载更好。

typescript 复制代码

// 重载
function pick(value: string, start: number, length?: number): string;
function pick<T>(value: T[], start: number, length?: number): T[];
function pick(value: any, start: number, length?: number): any {
    // 实现
}

四、箭头函数不支持重载

箭头函数（函数表达式）不能像函数声明那样写多个重载签名。替代方案：

使用函数声明（function）
使用函数类型表达式 + 交叉类型模拟（不推荐，复杂且可读性差）

typescript 复制代码

// 错误：箭头函数不能有重载
// const reverse = (input: string): string;
// const reverse = (input: string[]): string[]; // ❌

// 正确：使用函数声明
function reverse(input: string): string;
function reverse(input: string[]): string[];
function reverse(input: string | string[]): string | string[] {
    // 实现
}

如果需要保留箭头函数的 this 绑定，可以内部调用一个具名函数。

五、常见错误与注意事项

5.1 实现签名可调用但不应被外部调用

实现签名的类型不会暴露给外部，但如果你直接调用实现签名（例如传入了联合类型的参数），TypeScript 会报错提示"此调用不匹配任何重载"。

typescript 复制代码

function fn(x: string): string;
function fn(x: number): number;
function fn(x: any): any { return x; }

fn("a");   // OK
fn(1);     // OK
fn(true);  // ❌ 不匹配任何重载

5.2 重载签名顺序不当导致匹配错误

typescript 复制代码

function fn(x: any): any;
function fn(x: string): string;
function fn(x: any): any { return x; }

fn("a"); // 匹配第一个（any），返回 any，丢失精确类型

应将更具体的重载放在前面。

5.3 实现签名不够兼容

typescript 复制代码

function fn(x: string): string;
function fn(x: number): number;
// 实现签名参数类型不兼容（缺少 number）
function fn(x: string): string { // ❌ 实现签名与重载不兼容
    return x;
}

实现签名必须能处理所有重载签名的参数。

5.4 不必要的重载

如果一个函数可以用可选参数或默认参数实现，就不需要重载。

typescript 复制代码

// 不必要的重载
function greet(): string;
function greet(name: string): string;
function greet(name?: string): string {
    return name ? `Hello, ${name}` : "Hello";
}

// 更好的写法（默认参数）
function greet(name: string = "Guest"): string {
    return `Hello, ${name}`;
}

5.5 重载与泛型

如果重载逻辑可以用泛型解决，优先考虑泛型（后续文章会讲）。泛型通常更简洁。

typescript 复制代码

// 重载方式
function first(arr: string[]): string;
function first<T>(arr: T[]): T;
function first(arr: any[]): any {
    return arr[0];
}

// 泛型方式（一个签名就够了）
function first<T>(arr: T[]): T {
    return arr[0];
}

六、综合示例

typescript 复制代码

// 定义一个坐标转换函数：支持不同输入格式，返回统一的对象或数组
type Point2D = { x: number; y: number };

// 重载签名
function toPoint(coords: [number, number]): Point2D;
function toPoint(x: number, y: number): Point2D;
function toPoint(coords: string): Point2D;
function toPoint(x: number | string | [number, number], y?: number): Point2D {
    if (typeof x === "number" && typeof y === "number") {
        return { x, y };
    }
    if (Array.isArray(x) && x.length === 2) {
        return { x: x[0], y: x[1] };
    }
    if (typeof x === "string") {
        const parts = x.split(",").map(Number);
        if (parts.length === 2 && !parts.some(isNaN)) {
            return { x: parts[0], y: parts[1] };
        }
    }
    throw new Error("Invalid input");
}

// 使用
const p1 = toPoint(10, 20);           // Point2D
const p2 = toPoint([30, 40]);          // Point2D
const p3 = toPoint("50,60");           // Point2D

// 另一个示例：创建日期，支持时间戳或年月日
function createDate(timestamp: number): Date;
function createDate(year: number, month: number, day: number): Date;
function createDate(arg1: number, arg2?: number, arg3?: number): Date {
    if (arg2 !== undefined && arg3 !== undefined) {
        return new Date(arg1, arg2, arg3);
    }
    return new Date(arg1);
}

const d1 = createDate(1672531200000);   // Date
const d2 = createDate(2025, 3, 20);     // Date

七、小结

概念	说明
重载签名	多个，无函数体，定义外部可调用的参数与返回值组合
实现签名	一个，有函数体，必须兼容所有重载签名
匹配顺序	按重载签名顺序匹配，具体重载在前，宽泛在后
参数数量不同	实现签名中用可选参数或剩余参数处理
参数类型不同	实现签名中用联合类型处理
箭头函数	不支持重载，使用函数声明替代
与泛型关系	部分重载可被泛型简化

觉得文章有帮助？别忘了：

👍 点赞 👍 -- 给我一点鼓励
⭐ 收藏 ⭐ -- 方便以后查看
🔔 关注 🔔 -- 获取更新通知

标签： #TypeScript #函数重载 #Overloads #学习笔记 #前端开发

TypeScript 函数重载（Overloads）

目录

一、为什么需要重载

1.1 问题场景

1.2 重载的解决方案

二、重载语法与规则

2.1 重载签名（Overload Signatures）

2.2 实现签名（Implementation Signature）

2.3 重载解析规则

2.4 参数数量不同的重载

2.5 参数类型不同的重载

三、重载 vs 联合类型

四、箭头函数不支持重载

五、常见错误与注意事项

5.1 实现签名可调用但不应被外部调用

5.2 重载签名顺序不当导致匹配错误

5.3 实现签名不够兼容

5.4 不必要的重载

5.5 重载与泛型

六、综合示例

七、小结