HOWTO · TypeScript

TypeScript 中的重载构造函数

本教程演示了如何在 TypeScript 中重载构造函数。

本页内容

TypeScript 通过多个重载签名和一个实现来支持构造函数重载。签名描述调用者可以使用的参数形式;它们不会在运行时创建多个构造函数。当类只有少数几种明确的初始化形式时,可以使用重载,并确保共用实现能够处理签名允许的每一种形式。

TypeScript 构造函数重载的工作方式

先写出每个公开的重载签名,再写实现签名。调用会根据重载列表进行检查。实现签名必须足够宽泛,能够接收已声明的各种形式,但它对调用者不可见,也不会增加另一种可接受的调用形式。理解这一区别有助于有意识地设计类的 API:即使某个值符合实现签名中的联合类型,如果没有重载描述该参数组合,调用仍可能被拒绝。

声明重载签名和一个实现

这个类支持三种调用形式:不带参数、传入国家名称,或传入苹果数量、香蕉数量和水果标签。在 TypeScript 中,将这些形式声明为 constructor();、constructor(country: string); 和 constructor(apples: number, bananas: number, fruit: string);,然后提供一个参数能够表示这三种形式的实现。实现使用可选参数,并让第一个参数采用联合类型,再通过 typeof 缩小该联合类型的范围。

实现的类型签名可以写成 constructor(countryOrApples?: string | number, bananas?: number, fruit?: string)。在类中将它放在三个重载声明之后。在函数体中,使用 typeof countryOrApples === "string" 和 typeof countryOrApples === "number" 来缩小联合类型,然后再使用相应的值;剩余分支处理不带参数的调用。这是 TypeScript 语法说明;下方的可执行示例使用 JavaScript,因此无需 TypeScript 编译器配置也能展示相同的运行时行为。

运行以下 JavaScript 示例,查看共用实现的运行时行为。代码块及其显示的输出标签保持英文,以保留示例原文;输出依次展示默认值、国家 India 和苹果数量 8:

本节中的代码以及显示的标签或输出仍为英文。

class Fruits {
  constructor(countryOrApples, bananas, fruit) {
    if (typeof countryOrApples === "string") {
      console.log(`Apple country: ${countryOrApples}`);
    } else if (typeof countryOrApples === "number") {
      console.log(`Apple count: ${countryOrApples}`);
    } else {
      console.log("Using default values");
    }

    this.numBananas = bananas ?? 0;
    this.unknownFruit = fruit ?? "";
  }
}

new Fruits();
new Fruits("India");
new Fruits(8, 4, "Orange");
Using default values
Apple country: India
Apple count: 8

可选参数和联合类型描述实现能够接收哪些内容;它们不会让每种参数组合都成为 TypeScript 调用时的有效形式。重载签名接受不带参数、一个字符串,或带有指定类型的三个参数。如果实现为 fruit 使用联合类型,那么当不同组合需要不同处理方式时,仍必须分支处理或验证这些值。

检查参数并处理运行时行为

new Fruits("India", 4, "Orange") 会被拒绝,因为它不符合三个重载签名中的任何一个,即使实现参数能够表示这些值。此诊断属于 TypeScript 编译时检查,并不是运行时单独产生的构造函数错误。重载应与实现实际支持的参数组合保持一致;将值用作特定类型之前,也要进行必要的类型缩小。

删除重载声明后,调用者便可以使用实现签名。这可能会放行额外的参数组合,例如同时传入字符串形式的国家名称和水果标签,但这并不保证实现能按预期处理这些组合。只有当实现有意处理每种新接受的组合时,才应扩大公开的调用形式。因此,实现签名既是内部参数约定,也提醒我们必须处理每个受支持的分支。

何时改用静态工厂

静态工厂可以为不同的初始化路径命名,例如 Fruits.fromCountry("India") 或 Fruits.fromCounts(8, 4)。每个方法都可以验证自己的输入,然后调用一个简单的构造函数。当重载表达不同含义,或需要大不相同的验证逻辑时,这种做法通常更清晰,也能让调用处的意图更明确。

工厂方法会增加方法名称;如果参数形式只有几种且一目了然,可能没有必要使用它们。当命名能提升可读性,或每条初始化路径都有各自规则时,可以选择工厂方法;如果构造过程仍然简单,且各种调用形式容易区分,则保留构造函数重载。无论采用哪种方式,都应明确说明接受哪些输入,并确保运行时处理与公开 API 一致。