TypeScript 声明合并（Declaration Merging）全解析

Interface 的合并规则

当多个 interface 使用相同的名称时，编译器会将它们合并。合并遵循以下核心规则：

第1步：处理非函数成员

目的：理解同名属性的冲突处理逻辑。
操作：检查相同名称的非函数成员类型是否一致。
结果：如果类型不同，编译器报错；如果类型相同或可兼容，则视为同一成员。

若两个 interface 都声明了一个名称相同但类型不同的非函数成员，编译器将提示错误。例如：

interface Box { 
   height: number; 
 }

interface Box {
   height: string; 
 } // 编译错误：属性 'height' 的类型不同

第2步：处理函数成员（重载合并）

目的：利用声明合并实现函数重载。
操作：为同一接口名定义多个具有相同函数名的方法，参数类型或数量不同。
重要参数：参数类型的特殊性（如字面量类型）会影响排序优先级。

对于 函数成员，每个 相同名称 的成员被视为同一函数的重载。通常情况下，后声明的 interface 具有更高优先级，但这主要体现在结构上。最终的合并顺序通常如下所示：

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

interface Cloner {
  clone(animal: Sheep): Sheep;
}

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

// 最终合并结果
interface Cloner {
  clone(animal: Dog): Dog;
  clone(animal: Cat): Cat;
  clone(animal: Sheep): Sheep;
  clone(animal: Animal): Animal;
}

例外情况（字面量优先级）：
当函数参数类型为单字面量类型（single string literal type）时，编译器会依据优先级排序，将字面量参数放在声明顶部，以便更具体的匹配优先于通用匹配。例如：

// 合并后，字面量类型根据冒泡排序置于顶部
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 的 导出的成员 会被添加到第一个 namespace 中。

namespace Animals {
  export class Zebra {}
}

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

// 合并结果
namespace Animals {
  export interface Legged { ... }
  export class Zebra {} // 来自第一个 namespace
  export class Dog {}   // 来自第二个 namespace
}

第3步：注意未导出成员的访问限制

风险提醒：合并后的 namespace 无法直接访问其他合并分块中的 未导出成员。这可能导致编译错误或运行时问题，因为内部变量仅在各自的作用域内可见。

示例中，haveMuscles 是未导出常量，第二个 namespace 试图访问它时会报错：

namespace Animal {
  const haveMuscles = true;
  export function animalsHaveMuscles() {
    return haveMuscles; // OK
  }
}

namespace Animal {
  export function doAnimalsHaveMuscles() {
    return haveMuscles; // Error: haveMuscles is not accessible here
  }
}

运行时的行为也反映了这一隔离性，具体表现可通过观察编译后的 JavaScript 代码确认（见下图）：

Class、Enum、Function 与 Namespace 的结合

除了同类合并，TypeScript 还支持不同类型与 namespace 之间的交叉合并，这在扩展现有类型时非常实用。

第4步：Class 与 Namespace 合并

作用：为类添加静态属性或关联类型。
操作：定义同名 class 和 namespace。

class 可以访问 namespace 中导出的 类型 和 值。例如：

class Album {
  label: Album.AlbumLabel; // 引用 namespace 中定义的接口/类
}

namespace Album {
  export class AlbumLabel {}
}

第5步：Function 与 Namespace 合并（挂载属性）

作用：在函数对象上附加辅助数据，类似于 JavaScript 中给函数加属性的做法。
操作：定义同名 function 和 namespace。

这使得我们可以将相关常量绑定到函数主体上，便于统一管理：

function buildLabel(name: string): string {
  return buildLabel.prefix + name + buildLabel.suffix;
}

namespace buildLabel {
  export const suffix = '';
  export const prefix = 'Hello, ';
}

console.log(buildLabel('Sam Smith')); // Hello, Sam Smith

编译后的代码证实了属性被直接挂载到了函数对象上：

第6步：Enum 与 Namespace 合并

作用：为枚举添加静态操作方法。
操作：定义同名 enum 和 namespace。

enum Color {
  red = 1,
  green = 2,
  blue = 4,
}

namespace Color {
  export function mixColor(colorName: string) {
    if (colorName == 'yellow') return Color.red + Color.green;
    // ... 其他逻辑
  }
}

这种方式允许在不污染枚举值的同时，提供相关的工具函数：

Module 扩展与全局类型增强

module（即 ES Modules）之间不支持直接的声明合并，因为每个文件是一个独立的封闭作用域。但我们可以通过特定语法实现类似的效果。

第7步：本地模块扩展（Declare Module）

场景：需要为非自己维护的第三方库添加新方法。

虽然可以直接 import 并修改原型（如 Observable.prototype.map = ...），但这会导致编辑器缺乏智能提示。正确做法是使用 declare module 扩展接口声明：

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

// 扩展声明：告诉 TS Observable 多了一个 map 方法
declare module "./observable" {
  interface Observable<T> {
    map<U>(f: (x: T) => U): Observable<U>;
  }
} 

// 实际实现
Observable.prototype.map = function (f) {
  // ...
};

第8步：全局扩展（Declare Global）

场景：在全局范围（如浏览器环境）扩展原生对象的行为。

如果在一个文件中使用 declare global，可以在不导入模块的情况下扩展全局类型：

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

// 在这里扩展
declare global {
  interface Array<T> {
    toObservable(): Observable<T>;
  }
}

Array.prototype.toObservable = function () {
  // ...
};

总结

声明合并是 TypeScript 类型系统中“约定优于配置”的体现。通过合理使用 interface 的重载合并、namespace 的成员聚合以及 declare module 的外部扩展，开发者可以构建出既符合语义又具备良好开发体验的类型体系。需要注意的是，class 本身不支持合并，如需类似功能应考虑 Mixins 模式；同时在进行模块扩展时，务必保持接口声明与运行时实现的一致性。

以上就是 TypeScript 中声明合并介绍的详细内容，更多关于 TypeScript 声明合并机制优化的资料请关注本站其它相关文章！