JavaScript / TypeScript / 系统课时

使用函数重载

使用函数重载

函数重载适合“同一个函数名支持多种参数组合,并且不同输入对应不同返回类型”的场景。正确拆分重载签名与实现签名后,调用方能获得精确提示,实现内部也能安全缩小类型。

学习目标

  • 声明多组对外可见的重载签名
  • 编写兼容全部重载的实现签名
  • 判断何时应使用重载,何时联合类型更简单

重载由两部分组成

TypeScript 重载先写一组没有函数体的重载签名,最后再写一个带函数体的实现签名。调用者只能看到前面的重载签名,不能直接按照实现签名随意调用。

下面的 formatValue 支持格式化字符串,也支持按指定小数位格式化数字:

ts
// 对外签名分别描述字符串与数字两种调用方式
function formatValue(value: string): string;
function formatValue(value: number, digits?: number): string;
function formatValue(
  value: string | number,
  digits = 2
): string {
  // 实现签名覆盖全部输入,并在函数体内缩小类型
  if (typeof value === "number") {
    return value.toFixed(digits);
  }

  return value.trim().toUpperCase();
}

console.log(formatValue("  typescript  "));
console.log(formatValue(12.3456));
console.log(formatValue(12.3456, 3));

预期输出

text
TYPESCRIPT
12.35
12.346

实现签名使用 string | number 覆盖所有重载的首个参数,并让 digits 可选,从而兼容仅传字符串、仅传数字以及传数字和精度三种调用方式。

实现签名必须足够兼容

每个重载签名都必须能够落入实现签名。若某个重载允许 number,实现参数就不能只写 string;若某个重载返回 number,实现返回类型也必须覆盖 number。

实现内部仍要通过 typeof、in 或自定义类型谓词缩小类型。不要仅用类型断言跳过分支检查,否则重载表面上精确,运行时仍可能处理错误。

重载顺序影响匹配结果

TypeScript 会从上到下匹配重载,因此应把更具体的签名放在更宽泛的签名前面。若先声明一个过宽的签名,例如接受 unknown,后面的精确签名可能失去作用,调用结果也会被推断成宽泛类型。

重载之间还应保持可区分性。仅靠两个几乎相同的可选参数组合,容易让调用者和编译器都难以判断意图;此时可改用带判别字段的对象参数。

何时不用重载

如果所有调用形式都接收相同数量的参数,返回类型也相同,联合类型通常更简洁。例如 function print(value: string | number): void 不需要拆成两个重载。

当不同输入与不同返回值存在稳定映射时,重载更有价值,例如传入 string 返回解析后的对象,传入对象则返回序列化字符串。若组合数量持续增长,优先考虑泛型、配置对象或判别联合,避免维护大量重复签名。

常见错误检查

  • 只写重载签名却遗漏最终实现,函数将无法运行
  • 把实现签名当成公开签名,误以为联合类型中的任意组合都能调用
  • 让实现参数或返回类型比某个重载更窄,导致编译错误
  • 把宽泛签名放在前面,使后续精确重载无法提供预期推断

本课总结

  • 重载签名描述对外调用方式,实现签名负责统一承接并执行
  • 实现参数和返回类型必须覆盖全部重载,并在函数体内完成类型缩小
  • 简单同返回类型场景优先联合类型,输入输出映射明确时再使用重载

下一课预告

下一课将继续整理泛型函数的写法,用类型参数保留输入与输出之间的关联,减少重复重载。

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

目录与阅读设置

阅读设置

17

记录一个想法

使用函数重载

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

登录哪都通