模块增强是 TypeScript 中扩展已有模块类型声明的强大功能，允许你为第三方模块或内置模块添加额外的类型定义，而无需修改原始代码。

基本概念

模块增强使用 declare module 语法来扩展已有模块的类型定义：

// 原始模块声明
declare module "existing-module" {
  export interface OriginalInterface {
    existingProp: string;
  }
}

// 模块增强
declare module "existing-module" {
  export interface OriginalInterface {
    newProp: number; // 添加新属性
  }

  export function newFunction(): void; // 添加新函数
}

常见使用场景

1. 扩展第三方库类型

// 扩展express的Request类型
declare module "express" {
  export interface Request {
    user?: {
      id: string;
      name: string;
    };
  }
}

2. 为 JavaScript 库添加类型

// 为无类型声明的JS库添加类型
declare module "untyped-library" {
  export function doSomething(config: { timeout: number }): Promise<void>;
}

3. 扩展内置类型

// 扩展Array原型
declare global {
  interface Array<T> {
    shuffle(): T[];
  }
}

Array.prototype.shuffle = function () {
  // 实现代码
  return this.sort(() => Math.random() - 0.5);
};

增强方式

1. 值增强 (Value Augmentation)

declare module "my-module" {
  export const version: string; // 添加新常量
}

2. 类型增强 (Type Augmentation)

declare module "my-module" {
  export interface Options {
    debug?: boolean; // 扩展接口
  }
}

3. 命名空间增强 (Namespace Augmentation)

declare module "my-module" {
  export namespace Utils {
    function formatDate(date: Date): string;
  }
}

最佳实践

1. 保持增强集中：将模块增强放在单独的 .d.ts 文件中
2. 避免冲突：确保不与原始模块定义冲突
3. 类型安全：增强时保持类型一致性
4. 文档化：为增强部分添加注释说明

实际示例

扩展 Vue 的类型

// vue-augmentations.d.ts
import Vue from "vue";

declare module "vue/types/vue" {
  interface Vue {
    $myProperty: string;
    $myMethod(): void;
  }
}

扩展 Node.js 的 Process 类型

declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: "development" | "production" | "test";
    API_KEY: string;
  }
}

模块增强是 TypeScript 类型系统中非常实用的功能，特别适合在不修改原始代码的情况下扩展类型定义，使你的代码能够更好地与现有库和框架集成。

更新日志

2025/8/24 08:17

查看所有更新日志

• e7112-1于 2025/8/24