如何创建你自己的TypeScript类型定义文件(.d.ts)?

---

TypeScript是JavaScript的超集，它提供了静态类型检查功能，可以提高代码质量并在编译期间捕获错误。为了充分利用TypeScript的静态类型功能，项目中使用的外部JavaScript库和模块必须有类型定义文件(.d.ts)。这些类型定义文件描述了外部实体公开的类型和接口，使TypeScript编译器能够理解它们的结构和行为。

在本文中，我们将探讨创建自定义TypeScript类型定义文件的逐步过程，使开发人员能够在项目中受益于静态类型检查。

先决条件

类型定义文件(.d.ts)充当JavaScript代码和TypeScript编译器之间的接口。它们描述了JavaScript库或框架中存在的类型、函数、类和模块。这些文件使TypeScript编译器能够执行类型检查并在IDE中提供丰富的IntelliSense支持。

在深入创建类型定义文件之前，请确保你已设置以下先决条件：

• 对TypeScript的基本理解。

• TypeScript已全局安装在你的系统上。你可以使用npm通过以下命令安装它：

npm install -g typescript

步骤1：确定库结构

要创建类型定义文件，你需要了解你要为其创建类型的库或模块的结构。这包括分析JavaScript代码，理解公开的函数、类、对象及其对应的类型。

步骤2：从一个空的.d.ts文件开始

创建一个空的.d.ts文件，其名称与你要为其创建类型的JavaScript库或模块相同。例如，如果你的库名为"my-library"，则类型定义文件的名称应为"my-library.d.ts"。

步骤3：声明模块

创建类型定义文件的步骤是使用declare module语法声明模块。这告诉TypeScript你正在为特定的模块或库定义类型。示例如下：

declare module 'my-library' {
   // Type definitions go here
}

步骤4：定义类型和接口

在模块声明中，你可以定义描述库结构的类型和接口。你可以为对象声明接口，为函数声明类型等等。

让我们考虑一个例子，我们有一个名为"math-library"的库，它有一个名为add的函数，该函数接受两个数字作为参数并返回它们的和：

declare module 'math-library' {
   export function add(a: number, b: number): number;
}

在上面的示例中，我们声明了一个名为"math-library"的模块，并导出一个函数add，它接受两个数字（a和b）作为参数并返回一个数字。

步骤5：导出类型和接口

要使已定义的类型和接口可用于其他TypeScript文件，你需要显式导出它们。在每个类型或接口声明之前使用export关键字。以下是一个扩展我们之前的math-library示例的示例：

declare module 'math-library' {
   export function add(a: number, b: number): number;

   export interface Calculator {
      name: string;
      add(a: number, b: number): number;
   }
}

在更新后的示例中，我们导出一个名为Calculator的新接口，它具有一个name属性和一个与我们之前定义的add函数具有相同签名的add方法。

步骤6：使用环境声明

环境声明允许你为没有TypeScript特定注释的现有JavaScript代码描述类型。它们包含在一个declare global块中。示例如下：

declare global {
   interface Array<T> {
      filter(callbackfn: (value: T, index: number, array: T[]) => boolean): T[];
   }
}

在上面的示例中，我们声明了一个全局接口Array<T>来扩展内置的Array类型。我们添加了一个新的方法filter并使用一个回调函数指定它的签名，该回调函数将值、索引和数组本身作为参数。

步骤7：引用外部类型定义（可选）

如果你的类型定义文件依赖于其他外部类型定义文件，则可以使用/// <reference types="..."/>语法引用它们。例如，如果你的库依赖于流行库"lodash"的类型定义，则可以按如下所示包含引用：

/// <reference types="lodash" />

这确保了TypeScript编译器在编译代码时包含来自"lodash"的类型定义。

步骤8：测试和改进

定义类型定义文件后，务必使用你的代码库对其进行测试。在你的TypeScript项目中导入或引入该库，并使用已定义的类型和接口。如果TypeScript编译器抛出任何错误，或者库的行为与已定义的类型不匹配，请返回你的类型定义文件并相应地改进它。

示例1

让我们考虑一个实际示例。

让我们创建一个名为my-library的模块，它有一个实用程序函数capitalize，该函数接受一个字符串并返回其大写版本。

my-library.js

function capitalize(st) {
   return st.charAt(0).toUpperCase() + st.slice(1);
}
module.exports = {
   capitalize: capitalize,
};

现在，我们将创建一个类型定义文件，以使用编译时类型检查来限制导出capitalize函数的用法：

首先，创建一个名为my-library.d.ts的新文件，内容如下：

declare module 'my-library' {
   export function capitalize(str: string): string;
}

在上面的示例中，我们声明了一个名为"my-library"的模块，并导出一个函数capitalize，它接受一个字符串参数并返回一个字符串。

你现在可以在你的TypeScript代码中使用capitalize函数，并确保类型安全。我们现在创建一个app.ts文件来使用我们的capitalize函数：

app.ts

/// <reference types="node" />
const { capitalize } = require("./my-library");
const result = capitalize("hello");
console.log(result); // Output: Hello

通过添加/// <reference types="node" />指令，你可以通知TypeScript使用已安装的Node.js类型定义来使用require函数。现在，TypeScript应该识别require函数。

通过提供准确的类型定义，TypeScript编译器可以验证capitalize函数的用法，防止任何潜在的类型错误。

输出

它将产生以下输出：

Hello

结论

创建TypeScript类型定义文件(.d.ts)允许开发人员利用静态类型的强大功能，并在使用外部JavaScript库和模块时增强开发体验。通过按照分析库结构、声明模块、定义类型和接口以及测试和改进类型定义的逐步过程，开发人员可以确保其项目的类型定义准确且全面。有了类型定义文件，TypeScript可以提供改进的代码质量、早期错误检测和增强的可维护性。通过投入时间创建精确的类型定义，开发人员可以在其开发工作流程中充分利用TypeScript的优势。