TypeScript 类型声明文件

引言

在现代 JavaScript 应用中，第三方库的引入十分常见。无论这些库是用 TypeScript 还是 JavaScript 编写的，最终都会编译成 JavaScript 代码供开发者使用。虽然 TypeScript 提供了强大的类型系统，例如代码提示、类型保护等特性，但绝大多数第三方库都会配套提供对应的 TypeScript 类型声明文件。这类声明文件会为纯 JavaScript 库补充完整的类型信息，让我们在 TypeScript 项目中使用这些库时，能享受到和原生 TypeScript 代码一致的类型检查与开发体验。

文件类型区分

.ts 实现文件

同时包含类型信息和可执行代码：.ts 文件是 TypeScript 的核心源码文件，既支持书写接口、泛型、类型注解等类型定义，也能编写可执行的业务逻辑代码
可编译为 .js 文件：通过 TypeScript 编译器（tsc）编译后，.ts 文件会生成对应的 .js 文件，最终在浏览器 /Node.js 环境中运行
核心用途：用于编写项目的实际业务逻辑、功能实现，是程序运行的核心载体

.d.ts 类型声明文件

全称：TypeScript Declaration File（类型声明文件）

仅包含类型信息：文件内只有接口、类型别名、泛型、函数类型等类型定义，无任何可执行的 JavaScript 代码
不生成 .js 文件：TypeScript 编译器仅在开发阶段读取该文件做类型校验，编译时会直接忽略，不会产出任何运行时代码
核心用途：为纯 JavaScript 库、全局变量、自定义模块补充类型约束，解决 JS 库在 TS 项目中无类型提示的问题
其他补充：社区主流 JS 库的官方类型声明，可通过 npm 安装 @types/xxx 包获取（例如 @types/lodash、@types/react）

声明文件使用规则

加载方式

手动引入：通过 TS 三斜线指令 /// <reference path="文件路径" /> 显式引入声明文件，适合小型项目或临时使用
自动识别：在 tsconfig.json 中配置 include 字段，匹配到的 .d.ts 文件会被项目全局自动加载，是大型项目的主流用法

适用场景

为无类型的第三方 JavaScript 库自定义类型约束
定义项目全局通用的类型、接口
补充浏览器 /Node.js 未内置的全局变量类型

自定义类型声明

我们通过自定义数组类型，为 forEach 方法添加严格的类型约束，实现开发时的类型提示与校验。

创建类型声明文件

创建名为 my.d.ts 的类型声明文件，代码如下：

/**
 * 自定义 Array 类型约束
 * 泛型 T 继承 string 类型，限定数组元素只能是字符串
 */
interface MyArray<T extends string> {
    /**
     * 自定义 forEach 方法类型
     * @param callbackfn 回调函数：value 数组元素，index 元素索引，array 当前数组
     */
    forEach(callbackfn: (value: T, index: number, array: T[]) => void): void;
}

使用类型声明文件

在 TypeScript 项目中引入声明文件并使用自定义类型：

// 三斜线指令：手动引入自定义类型声明文件
/// <reference path="my.d.ts" />

// 声明自定义数组类型，约束元素为 string 类型
let myArray: MyArray<string> = ["a", "b", "c"];
// 调用 forEach 时，自动获得参数类型提示与校验
myArray.forEach((value, index) => {
  console.log(`${index}: ${value}`);
});

通过声明文件补充类型信息后，编辑器会精准提示回调函数的参数类型，同时 TypeScript 会自动校验赋值、传参是否符合类型约束，大幅提升开发效率与代码健壮性。

总结

.ts 文件：兼顾类型定义 + 可执行代码，编译为 .js 运行，是业务代码的载体
.d.ts 文件：仅包含类型定义，无运行代码，专为 JS 库 / 自定义类型提供类型支持
声明文件是 TS 兼容 JS 生态的核心，配合编辑器可实现完整的类型提示与校验能力