TypeScript 是 JavaScript 的超集，它通过静态类型检查帮助开发者在编码时发现潜在的问题，提高代码的可靠性和可维护性。TypeScript 的一个核心功能是 声明文件（Declaration Files） ，它为 JavaScript 库提供了静态类型描述，使得 TypeScript 可以在这些库中启用类型检查和智能提示。
一、什么是声明文件？
1.1 定义
声明文件是以 .d.ts 为后缀的 TypeScript 文件，用于定义 JavaScript 模块或库的类型声明。它不会生成实际的 JavaScript 代码，而是为 TypeScript 提供类型信息。
1.2 为什么需要声明文件？
JavaScript 是动态类型语言，没有原生的类型信息，而 TypeScript 则依赖类型检查来工作。当我们使用 JavaScript 库时，TypeScript 无法直接理解这些库的类型，因此需要通过声明文件提供类型定义，解决以下问题：
- 代码提示： 提供 IDE 智能提示功能（例如函数参数、返回值类型）。
- 类型检查： 帮助开发者避免类型错误。
- 文档功能： 提供对第三方库的清晰描述，无需查阅复杂的文档。
二、如何使用声明文件？
2.1 自动安装声明文件
大部分流行的 JavaScript 库都提供了官方或社区维护的声明文件。通过 npm install @types/<库名> 安装。例如：
npm install --save-dev @types/node
安装完成后，TypeScript 会自动加载这些声明文件，无需额外配置。
2.2 本地引用声明文件
如果某个库没有声明文件，你可以手动编写声明文件并将其引入到项目中。方法如下：
- 创建一个
.d.ts文件，例如globals.d.ts。 - 在文件中定义类型声明。
- 将该文件包含在
tsconfig.json的include配置中。
// globals.d.ts
declare module 'my-library' {
export function doSomething(value: string): void;
}
// tsconfig.json
{
"include": ["src", "globals.d.ts"]
}
三、如何编写声明文件？
3.1 基本语法
编写声明文件的语法与 TypeScript 类似，但需要注意以下几点：
- 不包含具体实现，仅提供类型描述。
- 使用
declare关键字标识全局变量、模块等。 - 通过
export或export default提供模块导出类型。
以下是一些常见场景及其对应的声明写法：
3.2 声明全局变量
声明一个全局变量或全局函数：
// global.d.ts
declare const VERSION: string;
declare function logMessage(message: string): void;
// 使用
console.log(VERSION);
logMessage('Hello World');
3.3 声明模块
为一个模块编写声明文件，可以使用 declare module：
// my-library.d.ts
declare module 'my-library' {
export function doSomething(value: string): void;
export const version: string;
}
使用时：
import { doSomething, version } from 'my-library';
doSomething('Hello');
console.log(version);
3.4 声明类
// my-class.d.ts
declare class MyClass {
constructor(name: string);
getName(): string;
static isInstance(obj: any): boolean;
}
export = MyClass;
// 使用
import MyClass = require('./my-class');
const instance = new MyClass('John');
console.log(instance.getName());
3.5 声明类型和接口
// shapes.d.ts
export interface Shape {
x: number;
y: number;
}
export type Circle = Shape & { radius: number };
3.6 函数重载
declare function calculate(a: number, b: number): number;
declare function calculate(a: string, b: string): string;
四、声明文件的工具
4.1 使用 dts-gen 自动生成声明文件
dts-gen 是一个工具，可以根据 JavaScript 库的代码自动生成声明文件：
npx dts-gen -m my-library
虽然dts-gen能够自动生成定义文件，但生成的文件可能不是完全准确的。因为dts-gen基于JavaScript库的源码来推断类型，它可能无法捕获所有的细节和边缘情况。因此，在使用自动生成的定义文件时，建议仔细阅读并可能需要进行一些手动调整。
