TypeScript 书写 .d.ts 文件的一些注意事项

Do’s and Don’ts


永远不要使用类型 Number、String、Boolean、Symbol 或 Object. 这些类型是指几乎从未在 JavaScript 代码中正确使用的非原始装箱对象。


下列用法不推荐:


function reverse(s: String): String;


应该使用下列用法:


function reverse(s: string): string;


any

除非您正在将 JavaScript 项目迁移到 TypeScript,否则不要使用 any 作为类型。 编译器有效地将 any 视为“请关闭此内容的类型检查”。 它类似于在变量的每个用法周围放置@ts-ignore 注释。 当您第一次将 JavaScript 项目迁移到 TypeScript 时,这会非常有用,因为您可以将尚未迁移的内容的类型设置为任何类型,但是在完整的 TypeScript 项目中,您将禁用对程序的任何部分进行类型检查 用它。


如果您不知道要接受什么类型,或者当您想接受任何东西时,因为您会盲目地传递它而不与它交互,则可以使用 unknown.


Return Types of Callbacks

不要将返回类型 any 用于其值将被忽略的回调。下列用法不推荐:


function fn(x: () => any) {

 x();

}

1

2

3

正确做法:使用类型 void 替代 any:


function fn(x: () => void) {

 x();

}

1

2

3

原因:使用 void 更安全,因为它可以防止您以未经检查的方式意外使用 x 的返回值。


function fn(x: () => void) {

 var k = x(); // oops! meant to do something else

 k.doSomething(); // error, but would be OK if the return type had been 'any'

}

1

2

3

4

Return Types of Callbacks

尽量避免在回调函数里定义 optional 参数,除非你觉得实在有必要。


interface Fetcher {

 getObject(done: (data: any, elapsedTime?: number) => void): void;

}

1

2

3

这有一个非常具体的含义:done 回调可能用 1 个参数调用,也可能用 2 个参数调用。 作者可能打算说回调可能不关心 elapsedTime 参数,但是没有必要使参数成为可选参数来实现这一点——提供接受更少参数的回调总是合法的。


重载和回调函数

不要编写仅在回调数量上有所不同的单独重载:


declare function beforeAll(action: () => void, timeout?: number): void;

declare function beforeAll(

 action: (done: DoneFn) => void,

 timeout?: number

): void;

1

2

3

4

5

请使用最大数量编写单个重载:


declare function beforeAll(

 action: (done: DoneFn) => void,

 timeout?: number

): void;

1

2

3

4

函数重载的定义顺序

不要在更具体的重载之前放置更一般的重载:


declare function fn(x: any): any;

declare function fn(x: HTMLElement): number;

declare function fn(x: HTMLDivElement): string;

var myElem: HTMLDivElement;

var x = fn(myElem); // x: any, wat?

1

2

3

4

5

正确做法:从具体到一般


declare function fn(x: HTMLDivElement): string;

declare function fn(x: HTMLElement): number;

declare function fn(x: any): any;

var myElem: HTMLDivElement;

var x = fn(myElem); // x: string, :)

1

2

3

4

5

原因:


TypeScript 在解析函数调用时选择第一个匹配的重载。 当较早的重载比较晚的重载“更通用”时,较晚的重载实际上是隐藏的并且无法调用。


使用可选参数

不要写几个只在尾随参数上不同的重载:


/* WRONG */

interface Example {

 diff(one: string): number;

 diff(one: string, two: string): number;

 diff(one: string, two: string, three: boolean): number;

}

1

2

3

4

5

6

正确做法:尽量使用可选参数:


interface Example {

 diff(one: string, two?: string, three?: boolean): number;

}

1

2

3

使用联合类型

不要编写仅在一个参数位置上因类型不同而不同的重载:


/* WRONG */

interface Moment {

 utcOffset(): number;

 utcOffset(b: number): Moment;

 utcOffset(b: string): Moment;

}

1

2

3

4

5

6

尽可能使用联合类型:


/* OK */

interface Moment {

 utcOffset(): number;

 utcOffset(b: number | string): Moment;

}

8

上一篇:TypeScript 里 .d.ts 文件的用处


下一篇:[CF1278F] Cards 加强版