跳到主要内容

TypeScript 类型声明文件

TypeScript 是一种强类型的 JavaScript 超集，它允许开发者在编写代码时定义和使用类型。然而，JavaScript 生态系统中有许多库是用纯 JavaScript 编写的，这些库本身并不包含类型信息。为了让 TypeScript 能够理解这些库的类型，我们需要使用 类型声明文件。

什么是类型声明文件？​

类型声明文件（通常以 .d.ts 为扩展名）是 TypeScript 用来描述 JavaScript 库的类型信息的文件。它们不包含实际的实现代码，而是提供了库的 API 的类型定义。通过使用类型声明文件，TypeScript 可以在编译时检查代码的类型安全性，并提供更好的开发体验（如代码补全和类型提示）。

备注

类型声明文件通常用于描述第三方 JavaScript 库的类型信息，但也可以用于描述项目内部的 JavaScript 代码。

类型声明文件的基本结构​

一个简单的类型声明文件可能如下所示：

typescript
// my-library.d.ts
declare module 'my-library' {
  export function greet(name: string): string;
  export const version: string;
}

在这个例子中，我们为名为 my-library 的模块声明了一个类型。它包含一个 greet 函数和一个 version 常量。

使用类型声明文件​

假设我们有一个 JavaScript 库 my-library，它提供了以下功能：

javascript
// my-library.js
function greet(name) {
  return `Hello, ${name}!`;
}

const version = '1.0.0';

module.exports = { greet, version };

为了让 TypeScript 能够理解这个库的类型，我们可以创建一个类型声明文件 my-library.d.ts，然后在 TypeScript 代码中使用它：

typescript
import { greet, version } from 'my-library';

console.log(greet('TypeScript')); // 输出: Hello, TypeScript!
console.log(version); // 输出: 1.0.0

编写类型声明文件的步骤​

1. 声明模块​

在类型声明文件中，我们通常使用 declare module 来声明一个模块。模块的名称通常是库的包名。

typescript
declare module 'my-library' {
  // 类型声明
}

2. 声明函数和变量​

在模块内部，我们可以声明函数、变量、类等。例如：

typescript
declare module 'my-library' {
  export function greet(name: string): string;
  export const version: string;
}

3. 声明类和接口​

如果库中包含了类或接口，我们也可以在类型声明文件中声明它们：

typescript
declare module 'my-library' {
  export class Greeter {
    constructor(name: string);
    greet(): string;
  }

  export interface GreetingOptions {
    prefix?: string;
    suffix?: string;
  }
}

4. 声明全局变量​

有些库可能会在全局作用域中定义变量或函数。我们可以使用 declare 关键字来声明这些全局变量：

typescript
declare const MY_GLOBAL: string;

declare function myGlobalFunction(): void;

实际案例​

假设我们有一个名为 math-utils 的 JavaScript 库，它提供了以下功能：

javascript
// math-utils.js
function add(a, b) {
  return a + b;
}

function multiply(a, b) {
  return a * b;
}

module.exports = { add, multiply };

我们可以为这个库编写一个类型声明文件 math-utils.d.ts：

typescript
// math-utils.d.ts
declare module 'math-utils' {
  export function add(a: number, b: number): number;
  export function multiply(a: number, b: number): number;
}

然后在 TypeScript 代码中使用它：

typescript
import { add, multiply } from 'math-utils';

console.log(add(2, 3)); // 输出: 5
console.log(multiply(2, 3)); // 输出: 6

总结​

类型声明文件是 TypeScript 中非常重要的一个概念，它允许我们为 JavaScript 库提供类型信息，从而在 TypeScript 中获得更好的开发体验。通过编写类型声明文件，我们可以确保代码的类型安全性，并利用 TypeScript 的强大功能，如代码补全和类型检查。

提示

如果你正在使用一个流行的 JavaScript 库，很可能已经有社区维护的类型声明文件。你可以通过 npm 安装这些类型声明文件，通常它们的包名是 @types/<library-name>。

附加资源​

练习​

  1. 尝试为以下 JavaScript 库编写类型声明文件：
javascript
// string-utils.js
function capitalize(str) {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

function reverse(str) {
  return str.split('').reverse().join('');
}

module.exports = { capitalize, reverse };
  1. 在 TypeScript 项目中使用你编写的类型声明文件，并调用 capitalize 和 reverse 函数。