目录

  1. 什么是 TypeScript 声明文件？
  2. 为什么需要声明文件？
  3. 如何创建声明文件？
  4. 基本的 .d.ts 文件结构
  5. 全局声明 vs 模块声明
  6. 如何使用第三方库的声明文件？
  7. 如何手动编写声明文件
  8. @types 和 DefinitelyTyped
  9. tsconfig.json 中的 types 配置
  10. 参考资料

1. 什么是 TypeScript 声明文件？

在 TypeScript 中，声明文件（Declaration File） 以 .d.ts 结尾，主要用于描述 JavaScript 代码的类型信息，使 TypeScript 了解 JavaScript 代码的结构。

作用：

  • 让 TypeScript 在不修改 JavaScript 代码的情况下获取类型信息。
  • 提供自动补全、类型检查、语法提示等功能。
  • 适用于没有 TypeScript 版本的 JavaScript 库。

2. 为什么需要声明文件？

当我们在 TypeScript 中使用 JavaScript 库（如 jQuery、Lodash 等）时，TypeScript 默认无法知道这些库的类型信息。例如：

📌 没有声明文件的情况

import * as $ from "jquery";

$("#app").css("color", "red"); // ❌ TypeScript 报错：找不到 "$" 的定义

原因：TypeScript 不知道 $ 是什么，它只认识 .ts 或 .d.ts 里的类型。

📌 有声明文件的情况

import * as $ from "jquery"; // ✅ 没有错误，TypeScript 知道 $ 的类型

解决方案：

  • 安装 jQuery 的声明文件：npm install --save-dev @types/jquery
  • TypeScript 读取 .d.ts 文件，获取 $ 的类型信息。

3. 如何创建声明文件？

TypeScript 不会自动为 JavaScript 生成 .d.ts 文件，需要手动创建。

（1）自动生成 .d.ts

如果你有 TypeScript 源代码，可以使用 tsc 生成 .d.ts 文件：

tsc --declaration --emitDeclarationOnly

或者在 tsconfig.json 中启用：

{
  "compilerOptions": {
    "declaration": true,
    "emitDeclarationOnly": true
  }
}

示例： 📌 math.ts

export function add(a: number, b: number): number {
    return a + b;
}

运行 tsc 后生成： 📌 math.d.ts

export declare function add(a: number, b: number): number;

这个 .d.ts 文件可用于 JavaScript 代码的类型推导。

（2）手动创建 .d.ts

如果你要给纯 JavaScript 库添加类型信息，需要手动编写 .d.ts 文件。

📌 lodash.d.ts

declare module "lodash" {
    export function chunk<T>(array: T[], size: number): T[][];
}

4. 基本的 .d.ts 文件结构

.d.ts 文件通常包含：

  1. 变量声明
  2. 函数声明
  3. 类和接口
  4. 模块和命名空间
  5. 泛型和类型别名

📌 完整示例

declare namespace MyLibrary {
    export const version: string;
    export function doSomething(): void;
    export class MyClass {
        constructor(name: string);
        getName(): string;
    }
}

5. 全局声明 vs 模块声明

（1）全局声明

适用于没有模块化的 JavaScript 代码（如 window 全局变量）。

📌 global.d.ts

declare var myGlobal: string;
declare function myFunction(name: string): void;
declare class MyClass {
    constructor(name: string);
}

使用方式：

console.log(myGlobal);
myFunction("Hello");

（2）模块声明

适用于使用 import/export 的模块化库。

📌 myModule.d.ts

declare module "myModule" {
    export function greet(name: string): string;
}

使用方式：

import { greet } from "myModule";
console.log(greet("TypeScript"));

6. 如何使用第三方库的声明文件？

（1）使用 @types 直接安装

如果第三方库（如 lodash）已经有声明文件，直接安装：

npm install --save-dev @types/lodash

然后在代码中直接导入：

import _ from "lodash";
console.log(_.chunk([1, 2, 3, 4, 5], 2));

（2）手动添加 .d.ts

如果库没有声明文件，可以在 @types 目录下创建： 📌 types/customLib.d.ts

declare module "customLib" {
    export function customFunction(name: string): string;
}

然后在 tsconfig.json 中添加：

{
  "compilerOptions": {
    "typeRoots": ["./types"]
  }
}

7. 如何手动编写声明文件

如果你要给一个没有 TypeScript 支持的库写 .d.ts 文件，可以参考以下格式：

declare module "some-library" {
    export function someFunction(param: string): number;
    export const someValue: boolean;
    export class SomeClass {
        constructor(param: string);
        someMethod(): void;
    }
}

8. @types 和 DefinitelyTyped

使用 @types 的好处： ✅ 官方支持，兼容性高
✅ 自动更新，与库的版本同步
✅ 无需手动编写，节省开发时间

9. tsconfig.json 中的 types 配置

TypeScript 可以通过 tsconfig.json 配置是否加载 @types：

{
  "compilerOptions": {
    "types": ["node", "jquery"]
  }
}
  • "types": [] ➝ 只加载指定的类型
  • "types": ["node"] ➝ 只加载 Node.js 的类型
  • 不写 types ➝ 自动加载所有 @types 目录

10. 参考资料

总结

  • .d.ts 文件用于描述 JavaScript 代码的类型信息。
  • TypeScript 可以自动生成 .d.ts，或手动编写。
  • 使用 @types 安装声明文件，避免手写类型定义。
  • .d.ts 可用于全局声明（declare var）或模块声明（declare module）。
  • DefinitelyTyped 提供大量开源声明文件，推荐使用 @types。

🚀 掌握 TypeScript 声明文件，可以更高效地使用 JavaScript 库！