TypeScript 中如何编写声明文件？

本文将循序渐进教大家如何给现有项目中的 JavaScript 代码「编写声明文件」。

1. 描述全局命名空间对象

❝

全局变量 myLib 上有一个函数 makeGreeting 用于创建问候语，以及一个属性numberOfGreetings，表示到目前为止已经制作的问候语数量。

❞

代码案例

let result = myLib.makeGreeting('hello world');
console.log('greeting: ', result);

let count = myLib.numberOfGreetings;

声明方式

通过 declare namespace 声明命名空间
在命名空间内部({})声明函数类型和变量类型(用分号 ; 隔开)，描述命名空间下可以访问的函数或值（通过点运算符(dotted notation)）。

declare namespace myLib {
  function makeGreeting(s: string): string;
  let numberOfGreetings: number;
}

2. 描述全局变量和函数

❝

全局变量 foo 表示 widgets 展现次数。

全局函数 greet 可以接受字符串参数调用，向用户展示问候信息

❞

代码案例

console.log("Half the number of widgets is " + foo / 2);
greet3("hello, world");

声明方式

使用 declare var 声明全局变量
使用 declare function 声明全局函数

declare var foo: number;
declare function greet3(s: string): string;

3. 描述重载函数

所谓重载函数（Overloaded Functions），即函数调用方式不止一种。

❝

getWidget 函数接受一个数字并返回一个 Widget，或者接受一个字符串并返回一个Widget 数组。

❞

代码案例

let x = getWidget(43);
let arr = getWidget('all of them');

声明方式

因为不是声明命名空间，而是一个全局函数，所以使用 declare function 就行。

declare function getWidget(n: number): Widget;
declare function getWidget(s: string): Widget[];

4. 描述函数的对象类型参数

❝

调用 greet 函数时，您必须传递一个 GreetingSettings 对象。该对象具有以下属性：

greeting：必填字符串

duration：可选时间长度（以毫秒为单位）

color：可选字符串，例如‘＃ff00ff’

❞

代码案例

greet({
  greeting: 'hello world',
  duration: 4000
});

声明方式

GreetingSettings 是个对象类型，所以要使用 interface 声明了
greet 函数依旧使用 declare function 声明

interface GreetingSettings {
  greeting: string;
  duration?: number;
  color?: string;
}

declare function greet(settings: GreetingSettings): void;

5. 描述函数的联合类型参数

❝

调用 greet 函数时，您可以提供一个字符串、或返回字符串的函数、或 Greeter 实例。

❞

代码案例

greet2(() => '');
greet2('hello');

声明方式

greet 函数依旧使用 declare function 声明
其参数 GreetingLike 是个联合类型

type GreetingLike = string | (() => string);

declare function greet2(settings: GreetingLike): void;

6. 描述类（构造函数、属性和方法）

❝

创建 Greeter2 类的实例对象 myGreeter, 支持扩展 Greeter2 类型（比如 SpecialGreeter）的方式创建自定义 greeter 对象。

❞

代码案例

const myGreeter = new Greeter2('hello world');
myGreeter.greeting = 'howdy';
myGreeter.showGreeting();

class SpecialGreeter extends Greeter2 {
  constructor() {
    super('Very special greeting');
  }
}

声明方式

本题我们会借用 declare class 描述 class 或类 class 对象。有属性、有方法还有构造函数。

declare class Greeter2 {
  constructor(s: string);

  greeting: string;
  showGreeting(): void;
}

7. 描述类实例上方法的参数

❝

greeter 对象可以记录到文件方法（.log()）或显示提示方法（.alert()）。可以向 .log(...) 提供 LogOptions 并向 .alert(...) 提供 AlertOptions

❞

代码案例

const g = new Greeter('hello world');
g.log({ verbose: true });
g.alert({ modal: false, title: 'Current Greeting' });

声明方式

LogOptions 和 AlertOptions 也可以通过 declare namespace 方式声明的，与在“描述全局命名空间对象”中不同的是，前者只声明了类型，后者则是声明了函数/变量。

declare namespace myLib {
  interface LogOptions {
    verbose: boolean;
  }
  
  interface AlertOptions {
    modal: boolean;
    title: string;
  }
}

declare class Greeter {
  constructor(s: string);

  log(logOptions: myLib.LogOptions): void;
  alert(alertOptions: myLib.AlertOptions): void;
}