--- theme: fancy highlight: srcery --- --- # 揭秘 .d.ts文件与 declare --- TypeScript 系列进阶篇：(八) 声明文件 -- 从编写到发布 --- 在接触TS的过程中，时常能看到使用`declare`关键字来进行声明，而它基本都是出现在`.d.ts`文件中。你是否好奇过，使用`declare`关键字到底有什么作用？它与不使用`declare`关键字的声明又有何不同？本文与你一同探索`declare`的奥秘，讲述如何写好一个声明文件 (`.d.ts`文件)，需要小伙伴们拥有一定的`typescript`基础。如果阅读本文过程中遇到不了解的知识点，可查阅我之前的基础篇的文章。 [toc] ## 一、Declaration Reference 声明指南我们先来了解到如何**根据`API`文档和用法示例**来编写相关的声明。这部分内容十分简单，基本看一遍过去就`ok`了。 ### 1. 对象和属性我们通常使用命名空间来声明对象。 - 文档：全局变量`myLib`，它有一个`greet`方法来创建问候语，一个`numberOfGreetings`属性来记录创建的问候语的数量。 - 示例： ```typescript let greeting = myLib.greet("hello, cc!") console.log(greeting) let count = myLib.numberOfGreetings ``` - **声明**： ```typescript declare namespace myLib { function greet(greeting: string): string; numberOfGreetings: number; } ``` ### 2. 重载函数 - 文档：函数`printName`，接收一个字符串并打印该字符串，或者接收一个字符串数组，打印其中所有的字符串，以逗号连接，最终都返回打印的名字的数量； - 示例： ```typescript let x = printName("cc"); // x=1，控制台输出 "cc" let y = printName(["cc", "yy"]); // y=2，控制台输出 "cc","yy" ``` - **声明**： ```typescript declare function printName(name: string): number; declare function printName(name: string[]): number; ``` ### 3. 类型 / 接口先来看`interface`的声明。 - 文档：使用`greet`函数指定问候语时，需要传递一个`Option`类型的对象作为参数，其具有以下几个属性： 1. `greeting`：问候语的内容，为一个字符串； 2. `color`：问候语的颜色，为一个表示颜色的字符串，可选； - 示例： ```typescript // color 可选 greet({greeting: "hello, cc!", color: "#ccc"}); greet({greeting: "hello, yy!"}); ``` - **声明**： ```typescript interface Option { greeting: string; color?: string; } declare function greet(opt: Option): void; ``` 很简单对不对，类型别名也很几乎一样，就演示了。 ### 4. 类 `classes` - 文档：可以创建一个`Greeter`实例，也可以通过继承来自定义一个类； - 示例： ```typescript const myGreeter = new Greeter("hello, world"); myGreeter.greeting = "hello, cc!"; myGreeter.showGreeting(); // 自定义类 class SpecialGreeter extends Greeter { constructor() { super("Very special greetings"); } } ``` - **声明**： ```typescript // 使用 declare class 来声明 declare class Greeter { constructor(greeting: string); greeting: string; showGreeting(): void; } ``` ### 5. 全局变量 - 文档：全局变量`foo`表示函数的总数量； - 示例： ```typescript console.log(`一共有 ${foo} 个函数。`) ``` - **声明**： ```typescript declare var foo: number; ``` ### 6. 全局函数 - 文档：传入一个字符串来调用`greet`； - 示例： ```typescript greet("hello, cc!") ``` ## 二、Library Structures 库的结构广义而言，声明文件的构建方式取决于库的使用方式。而在`JavaScript`中，库的使用方式有多种，因此，我们需要鉴别不同的使用方式，并编写匹配的声明文件。 ### 1. 如何识别库的种类编写声明文件的第一步便是识别库的结构。下面我们来了解一下如何根据库的 **用法** 和 **代码** 来识别库的种类。查看库时主要注意两点： 1. 如何获取该库？例如，是否只能通过`npm`或者`CDN`来获取； 2. 如何导入该库？该库是否添加了一个全局对象？是否使用`require`或者`import/export`语句。现代的库基本都属于 **模块**系列。从 **代码** 方面识别，我们可以关注以下的关键字和语句： - 无条件调用`require`或`define`； - 声明语句，如`import * as x from "ModuleX"`或`export x`； - 赋值给`exports`或`module.exports`； - 赋值给全局变量`window`或`global`。属于模块系列的模板大概有基础模块`modue.d.ts`，函数模块`module-function.d.ts`，类模块`module-class.d.ts`，和插件模块`module-plugin.d.ts`，这些将在后面的 **声明模板** 小节来介绍。 ### 2. Global Libraries 全局库全局库是无需使用`import`等语句导入，便可以在全局作用域下使用的库。有些库会暴露一个或多个全局变量来供我们使用。例如，用过`jQuery`的同学应该会知道全局变量`$`。往常，我们使用这些全局库，可以通过在`html`文件中使用`