JavaScript / TypeScript / 系统课时

函数重载

函数重载

本课解决同一函数存在多种合法参数组合时的类型描述问题。你将编写重载签名和实现签名,理解调用者只能看到重载签名,并学会避免宽泛实现泄漏为错误用法。

学习目标

  • 编写多个重载签名和一个实现
  • 理解实现签名对调用者不可见
  • 判断何时应使用联合类型替代重载

编写重载签名

函数重载由若干无函数体的重载签名和一个带函数体的实现签名组成。实现签名必须兼容全部重载。

ts
function formatValue(value: number): string;
function formatValue(value: Date): string;
function formatValue(value: number | Date): string {
  if (typeof value === "number") {
    return value.toFixed(2);
  }
  return value.toISOString().slice(0, 10);
}

console.log(formatValue(12.5));
console.log(formatValue(new Date("2026-07-30T00:00:00Z")));

预期输出

text
12.50
2026-07-30

前两行是调用者可见的重载签名,第三个签名只负责实现。调用者只能传入 number 或 Date,不能利用实现签名传入其他联合形式。

实现签名不可直接调用

即使实现参数写得更宽,未在重载签名中公开的调用方式仍不合法。

ts
function createId(value: number): string;
function createId(value: string): string;
function createId(value: number | string): string {
  return "ID-" + value;
}

console.log(createId(1001));
console.log(createId("A88"));

预期输出

text
ID-1001
ID-A88

例如 createId(true) 会在编译阶段失败。实现签名不是额外的一种公开重载,而是覆盖所有公开签名的内部实现契约。

不同参数数量的重载

重载可描述参数数量不同的调用方式,但实现必须正确处理每种情况。

ts
function makePoint(x: number, y: number): string;
function makePoint(value: [number, number]): string;
function makePoint(
  xOrTuple: number | [number, number],
  y?: number
): string {
  const point = Array.isArray(xOrTuple) ? xOrTuple : [xOrTuple, y as number];
  return "(" + point[0] + ", " + point[1] + ")";
}

console.log(makePoint(3, 5));
console.log(makePoint([8, 13]));

预期输出

text
(3, 5)
(8, 13)

实现中的分支应与重载一一对应。若需要大量类型断言,通常说明签名设计还可以继续简化。

何时改用联合类型

如果各调用方式的参数数量相同、返回值也相同,联合类型通常更简单。例如 formatValue(value: number | Date): string 就足以支持两个类型。只有返回值会随输入类型变化,或参数组合差异明显时,重载才更有价值。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

函数重载

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通