TypeScript 声明合并详解：接口、命名空间与模块扩展

在 TypeScript 的类型系统中，声明合并是一项独特且强大的特性，它允许编译器将多个同名的声明自动整合为一个统一的声明结构。这一机制不仅在使用现有 JavaScript 库时十分关键，也为构建复杂的类型抽象提供了极大便利。

本文将深入探讨声明合并的基本概念、常见形式、合并规则与限制，并针对 interface 和 type 等类型的同名合并情况进行具体分析。

一、什么是声明合并？

声明合并（Declaration Merging）指的是：当 TypeScript 编译器检测到多个同名的声明时，会将它们合并为一个声明，最终生成的合并声明将包含所有原始声明的特性。

简而言之，其核心逻辑是：多个同名声明 → 一个完整的复合声明。

二、接口（Interface）合并

最常见的合并形式即为接口合并。

interface Box {
  height: number;
  width: number;
}

interface Box {
  scale: number;
}

const box: Box = { height: 10, width: 20, scale: 1.5 };

合并后的结果如下：

interface Box {
  height: number;
  width: number;
  scale: number;
}

⚠️ 成员冲突规则

对于非函数成员，若名称相同但类型不同，编译器将报错。
对于函数成员，则作为函数重载进行合并，后声明的签名将排在前面。

interface Cloner {
  clone(animal: Animal): Animal;
}
interface Cloner {
  clone(animal: Dog): Dog;
  clone(animal: Cat): Cat;
}

合并后的最终结果：

interface Cloner {
  clone(animal: Dog): Dog;
  clone(animal: Cat): Cat;
  clone(animal: Animal): Animal;
}

📌 字面量类型优先

当函数参数包含单一字符串字面量时，该重载将被“提升”至重载列表的顶部：

interface Document {
  createElement(tagName: any): Element;
}
interface Document {
  createElement(tagName: "div"): HTMLDivElement;
  createElement(tagName: "span"): HTMLSpanElement;
}
interface Document {
  createElement(tagName: string): HTMLElement;
  createElement(tagName: "canvas"): HTMLCanvasElement;
}

合并后的最终结果：

interface Document {
  createElement(tagName: "canvas"): HTMLCanvasElement;
  createElement(tagName: "div"): HTMLDivElement;
  createElement(tagName: "span"): HTMLSpanElement;
  createElement(tagName: string): HTMLElement;
  createElement(tagName: any): Element;
}

三、命名空间（Namespace）合并

多个同名的 namespace 可以相互合并，其成员最终被聚合为一个单一的命名空间：

namespace Animals {
  export class Dog {}
}
namespace Animals {
  export interface Legged {
    numberOfLegs: number;
  }
}

合并后的结果：

namespace Animals {
  export class Dog {}
  export interface Legged {
    numberOfLegs: number;
  }
}

❗ 非导出成员不可见

namespace Animal {
  let hidden = true;
  export function canSeeHidden() {
    return hidden; // ✅ OK
  }
}
namespace Animal {
  export function tryToAccessHidden() {
    return hidden; // ❌ 报错
  }
}

四、模块与全局声明扩展（Augmentation）

模块扩展（Module Augmentation）

// observable.ts
export class Observable<T> {}

// map.ts
import { Observable } from './observable';

declare module './observable' {
  interface Observable<T> {
    map<U>(fn: (x: T) => U): Observable<U>;
  }
}

模块扩展不能新增顶级声明，仅能扩展现有结构，且仅支持具名导出。

全局扩展（Global Augmentation）

declare global {
  interface Array<T> {
    toObservable(): Observable<T>;
  }
}

五、命名空间与其他类型合并

TypeScript 支持将命名空间与某些其他类型进行合并，这常见于表达“内部类”或“静态成员扩展”等高级模式。

1. 命名空间 + 类（class）

class Album {
  label: Album.Label;
}
namespace Album {
  export class Label {}
}

此时 Album.Label 成为合法的引用方式。

2. 命名空间 + 函数（function）

function buildLabel(name: string): string {
  return buildLabel.prefix + name + buildLabel.suffix;
}
namespace buildLabel {
  export let prefix = "Hello, ";
  export let suffix = "!";
}

支持 buildLabel("TypeScript") 与 buildLabel.prefix 等调用方式。

3. 命名空间 + 枚举（enum）

enum Color {
  Red = 1,
  Green = 2,
}
namespace Color {
  export function mix(): number {
    return Color.Red + Color.Green;
  }
}

这样我们就可以使用 Color.mix() 作为枚举的“静态方法”。

六、type alias 与 interface 能否合并？

这是许多开发者关心的问题：TypeScript 不支持 type 与 interface 同名合并。

interface Foo {
  x: number;
}
type Foo = { y: number }; // ❌ 报错：重复标识符 "Foo"

目前为止，interface 与 interface 可以合并，namespace 与其他部分类型也可以合并，但 type 与 interface 属于不同的结构，不能合并。

七、总结

合并类型	是否支持
interface 与 interface	✅
namespace 与 namespace	✅
namespace 与 class	✅
namespace 与 function	✅
namespace 与 enum	✅
type alias 与 interface	❌
class 与 class	❌
class 与 variable	❌

声明合并是 TypeScript 类型系统中的一项核心机制，熟练掌握它不仅可以更好地使用第三方类型定义，还能让我们构建更强大、灵活的类型表达。

八、参考资料

Declaration Merging

到此这篇关于TypeScript 声明合并的具体使用的文章就介绍到这了,更多相关TypeScript 声明合并内容请搜索本站以前的文章或继续浏览下面的相关文章希望大家以后多多支持本站！

TypeScript 声明合并的具体使用