在 TypeScript 中declare module 关键字用法

在 TypeScript 中，declare module 关键字用于声明模块的类型信息，这种声明通常出现在声明文件（通常是 .d.ts 文件）中。这对于当你需要为现有的 JavaScript 库或模块提供类型信息时非常有用，尤其是对于没有提供自己的类型声明的第三方库。

基本用法

通过 declare module，你可以定义一个模块的结构和该模块导出的类型。这样，TypeScript 编译器就可以知道如何处理模块的导入和使用，即使这个模块实际上是用 JavaScript 写的。

示例 1: 声明一个简单模块

假设有一个名为 some-library 的第三方 JavaScript 库，你想在 TypeScript 中安全地使用它：

// some-library.d.ts
declare module 'some-library' {
    export function doSomething(value: string): void;
}
1
2
3
4

在这个例子中，我们声明了一个模块 some-library，它有一个名为 doSomething 的函数，这个函数接受一个字符串参数并且没有返回值。

示例 2: 声明模块内有多个导出

如果 some-library 还包含更多的函数或变量，你可以这样声明：

// some-library.d.ts
declare module 'some-library' {
    export function doSomething(value: string): void;
    export function doSomethingElse(value: number): number;
    export const someValue: number;
}
1
2
3
4
5
6

高级用法

示例 3: 带有命名空间的模块

如果模块有很多内嵌的部分，你可能想使用命名空间来组织它们：

// some-library.d.ts
declare module 'some-library' {
    export namespace Utils {
        export function helperFunction(x: number): number;
    }
    export function doSomething(value: string): void;
}
1
2
3
4
5
6
7

在这里，我们在模块内部声明了一个 Utils 命名空间，里面包含一个 helperFunction 函数。

示例 4: 模块扩展

有时你需要扩展一个已经存在的模块的声明（可能是第三方类型定义文件中的模块），你可以通过再次使用 declare module 来实现：

// 扩展一个存在的库
declare module 'some-existing-library' {
    export function newFunctionAddedByMe(x: number): number;
}
1
2
3
4

这种方式特别有用当你为现有库添加新功能或者在使用库的过程中发现类型声明有误或不完整时。

使用 declare module 的注意事项

1. 确保模块路径正确：在 declare module 中使用的模块名称应与实际导入时使用的字符串完全匹配。
2. 避免全局污染：尽量在类型声明文件中使用局部模块声明，而不是全局声明，以避免命名冲突。
3. 与实际 JavaScript 代码同步：确保你的声明文件反映了实际的库实现。如果库更新了，类型声明也应相应更新。

通过这种方式，declare module 在 TypeScript 中提供了一种强大的机制，以确保即使是非 TypeScript 的库也能在 TypeScript 项目中平滑地集成和使用。