d.ts你知道多少？

作者 | ayqy

现在用ts的小伙伴多么&＃xff1f;

一.简介

经常看到d.ts&＃xff0c;因为一个越来越广泛的应用场景是编辑器智能提示&＃xff08;具体见IntelliSense based on TypeScript Declaration Files&＃xff09;&＃xff1a;

Javascript IntelliSense can be provided for values declared in a .d.ts file (more info), and types such as interfaces and classes declared in TypeScript are available for use as types in JsDoc comments.

d.ts大名叫TypeScript Declaration File&＃xff0c;存放一些声明&＃xff0c;类似于C/C&＃43;&＃43;的.h头文件&＃xff08;#include &＃xff09;&＃xff1a;

We call declarations that don’t define an implementation “ambient”. Typically these are defined in .d.ts files. If you’re familiar with C/C&＃43;&＃43;, you can think of these as .h files.

&＃xff08;摘自Working with Other Javascript Libraries&＃xff09;

P.S.另一个“ambient”&＃xff08;环境&＃xff1f;&＃xff09;相关的概念Ambient Namespace&＃xff0c;指的也是只有声明没有实现的namespace

二.分类

声明文件本身没有类别&＃xff0c;但不同类型的类库在API暴露方式等方面存在差异&＃xff0c;对应的声明文件也有所区别

例如jQuery 1.x通常以global库的方式引用&＃xff1a;

而jQuery 3.x支持模块引用&＃xff1a;

// ES Moduleimport $ from "jquery";// Commonjs Moduleconst $ &＃61; require("jquery");

从声明文件上看&＃xff0c;前者需要声明全局变量jQuery和$&＃xff0c;而后者并不默认暴露这些&＃xff0c;所以jQuery-1.x.d.ts&＃xff1a;

declare var jQuery: JQueryStatic;
declare var $: JQueryStatic;

jQuery-3.x.d.ts&＃xff1a;

export &＃61; jQuery;

因此&＃xff0c;我们把类库分为3类&＃xff1a;

• global&＃xff1a;暴露出全局变量的类库

• module&＃xff1a;不暴露全局变量&＃xff0c;需要通过特定加载机制&＃xff08;如require/define/import&＃xff09;引用的模块形式的类库

• plugin&＃xff1a;会影响其它类库功能的类库&＃xff08;当然&＃xff0c;也可能会影响原声明&＃xff0c;比如添个新API&＃xff09;

3种类库对应的声明文件细分成6种&＃xff0c;模板及适用场景如下&＃xff1a;

• global.d.ts&＃xff1a;适用于global类库

• module-function.d.ts&＃xff1a;适用于暴露出一个Function的module类库

• module-class.d.ts&＃xff1a;适用于暴露出一个Class的module类库

• module.d.ts&＃xff1a;适用于一般module类库&＃xff08;暴露出的东西既不是Function也不是Class&＃xff09;

• module-plugin.d.ts&＃xff1a;适用于module plugin类库&＃xff08;A module plugin changes the shape of another module.&＃xff09;

• global-plugin.d.ts&＃xff1a;适用于global plugin类库&＃xff08;A global plugin is global code that changes the shape of some global.&＃xff09;

• global-modifying-module.d.ts&＃xff1a;适用于module形式的global plugin类库&＃xff08;They’re similar to global plugins, but need a require call to activate their effects.&＃xff09;

P.S.另外&＃xff0c;声明文件也存在全局声明冲突的问题&＃xff0c;建议通过namespace解决

三.引用方式

不同类型的声明文件对应的引用方式也不同&＃xff0c;global类库声明通过/// 指令引用&＃xff0c;例如&＃xff1a;

/// function getThing(): someLib.thing;

module类库声明用import语句引用&＃xff1a;

import * as moment from "moment";function getThing(): moment;

特殊的&＃xff0c;UMD类库既可以作为module类库也可以作为global类库引入&＃xff0c;此时引用方式取决于当前环境。例如global类库依赖UMD类库的话&＃xff0c;仍通过reference指令来引用&＃xff1a;

/// function getThing(): moment;

而module/UMD类库依赖UMD类库时则用import语句&＃xff1a;

import * as someLib from &＃39;someLib&＃39;;

P.S.关于声明文件引用方式的更多信息&＃xff0c;请查看

四.语法格式

全局变量

/** The number of widgets present */
declare var foo: number;

declare var声明了一个数值类型的全局变量foo&＃xff0c;同样&＃xff0c;还有declare const和declare let分别表示只读&＃xff0c;及块级作用域

类型部分与TS基本类型语法一致&＃xff0c;具体见Basic Types

全局函数

declare function greet(greeting: string): void;

declare function声明了一个函数greet&＃xff0c;它接受1个字符串类型参数greeting&＃xff0c;返回undefined或null

全局对象

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

declare namespace声明了一个对象myLib&＃xff0c;身上有个方法makeGreeting接受1个字符串类型参数s&＃xff0c;返回字符串&＃xff0c;还有个数值类型的属性numberOfGreetings

函数重载

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

getWidget函数有两个签名&＃xff0c;其一接受1个数值类型参数n&＃xff0c;返回Widget&＃xff0c;其二接受1个字符串类型参数s&＃xff0c;返回Widget数组

接口

interface GreetingSettings {
 greeting: string;
 duration?: number;
 color?: string;}
declare function greet(setting: GreetingSettings): void;

interface是一种可复用的类型&＃xff0c;上例声明了GreetingSettings的结构&＃xff0c;要求参数setting具有greeting以及可选的duration和color属性&＃xff0c;类型分别为字符串、数值、字符串

类型别名

type GreetingLike &＃61; string | (() &＃61;> string) | MyGreeter;
declare function greet(g: GreetingLike): void;

type也是一种可复用类型&＃xff0c;上例声明了类型别名GreetingLike&＃xff0c;要求参数g是字符串或返回字符串的函数或MyGreeter实例

类型“模块”

declare namespace GreetingLib {
   interface LogOptions {
       verbose?: boolean;
   }
   interface AlertOptions {
       modal: boolean;
       title?: string;
       color?: string;
   }}

类似于namespace能够组织代码模块&＃xff08;把一组相关代码放在一起&＃xff09;&＃xff0c;declare namespace能用来组织类型“模块”&＃xff08;把一组相关类型声明放在一起&＃xff09;

P.S.同样&＃xff0c;嵌套namespace也是支持的&＃xff0c;如declare namespace GreetingLib.Options {/…/}

类

declare class Greeter {
   constructor(greeting: string);
greeting: string;
   showGreeting(): void;}

declare class声明了一个类Greeter&＃xff0c;拥有构造函数和成员变量greeting以及成员方法showGreeting

五.实践规范

除了遵循基本的语法格式外&＃xff0c;实践中还应该遵守这些规范约束&＃xff1a;

• 用基础类型&＃xff08;number, string, boolean, object&＃xff09;&＃xff0c;不要用包装类型&＃xff08;Number, String, Boolean, Object&＃xff09;

• 不要出现未使用的泛型参数&＃xff0c;会导致类型无法正确推断

• 无返回值的callback参数返回类型用void&＃xff0c;不要用any

• callback的可选参数没必要在类型上标出来&＃xff0c;因为callback允许少传/不传参数

• 函数重载需要注意声明顺序&＃xff0c;应该从特殊到一般自上而下排列&＃xff08;例如any会短路其它重载声明&＃xff0c;类似于模式匹配的机制&＃xff09;

• 能用可选参数&＃xff08;如two?: string&＃xff09;描述的就别用函数重载了

• 能用组合类型&＃xff08;如b: number|string&＃xff09;描述的就别用函数重载了

六.类型&＃xff0c;值和命名空间

实际上&＃xff0c;类型&＃xff0c;值和命名空间&＃xff0c;这3个基本概念构成了TS灵活多样的类型系统

具体的&＃xff0c;类型有5种声明方式&＃xff1a;

// 类型别名
type sn &＃61; number | string;// 接口interface I { x: number[]; }// 类class C { }// 枚举enum E { A, B, C }// 类型引用import * as m from &＃39;someModule&＃39;;

值有6种声明方式&＃xff1a;

// 变量let, const, var// 模块namespace, module// 枚举enum// 类class// 值引用import// 函数function

命名空间可以用来组织类型&＃xff0c;例如let x: A.B.C表示变量x的类型是来自A.B命名空间下的C

发现class、enum、import具有双重含义&＃xff0c;没错&＃xff0c;它们既声明值也提供类型&＃xff0c;于是出现了一些有意思的事情&＃xff1a;

// 值与类型的结合export var Bar: { a: Bar };export interface Bar {
 count: number;}// 类型与类型的结合interface Foo {
 x: number;}class Foo {
 y: number;}// ... elsewhere ...interface Foo {
 z: number;}let a: Foo &＃61; ...;
console.log(a.x &＃43; a.y &＃43; a.z);

// OK// 命名空间与类型的结合class C {}

// ... elsewhere ...namespace C {
 export let x: number;}let y &＃61; C.x;

// OK// 命名空间与命名空间的结合namespace X {
 export interface Y { }
 export class Z { }}// ... elsewhere ...namespace X {
 export var Y: number;
 export namespace Z {
   export class C { }
 }}
type X &＃61; string;

基本原则是&＃xff0c;只要不冲突就是合法的&＃xff0c;具体而言&＃xff0c;相同命名空间下的同名值存在冲突&＃xff0c;同名类型别名存在冲突&＃xff0c;而命名空间不会和其它东西冲突&＃xff1a;

Values always conflict with other values of the same name unless they are declared as namespaces, types will conflict if they are declared with a type alias declaration (type s &＃61; string), and namespaces never conflict.

所以上例中的某些命名&＃xff08;Bar、Foo&＃xff09;虽然存在多种含义&＃xff0c;但都不冲突&＃xff0c;仍然是合法的

七.自动生成

dts-gen&＃xff08;不建议用&＃xff09;

# 全局安装dts-gen
npm install -g dts-gen

Microsoft/dts-gen是官方脚手架工具&＃xff08;已经1年不更新了&＃xff0c;但聊胜于无&＃xff09;&＃xff0c;能为JS生成d.ts&＃xff1a;

dts-gen is a tool that generates TypeScript definition files (.d.ts) from any Javascript object.

能够帮助生成基本的API列表&＃xff0c;例如&＃xff1a;

export function containsEmoji(...args: any[]): any;export function isEmoji(...args: any[]): any;export namespace containsEmoji {
   const prototype: {
   };}export namespace isEmoji {
   const prototype: {
   };}

具体用法如下&＃xff1a;

// 从npm模块生成
dts-gen -m emoutils
// 从本地文件生成
dts-gen -e "require(&＃39;/absolute-path-to/emoutils.js&＃39;)"

P.S.require本地文件要写绝对路径&＃xff0c;否则无法正确加载&＃xff0c;具体见expression-file doesn’t seem to work; ‘Couldn’t load module “undefined”‘

用法有些奇怪&＃xff0c;因为这个东西是运行时的&＃xff1a;

It simply examines the objects as they appear at runtime, rather than needing the source code that creates the object.

所以&＃xff0c;得到的API列表肯定全&＃xff0c;但参数类型、JSDoc等就无能为力了&＃xff0c;算是一种取舍&＃xff1a;

This means no matter how the object was written, anything, including native objects, can be given an inferred shape.

代价是生成产物缺少很多源码相关的静态信息&＃xff1a;

Keep in mind dts-gen doesn’t figure out everything – for example, it typically substitutes parameter and return values as any, and can’t figure out which parameters are optional.

dts-gen生成的东西太弱了&＃xff0c;那么&＃xff0c;有没有更厉害的方式&＃xff1f;

有。TypeScript编译源码时本来就会推断校验参数类型&＃xff0c;函数签名等&＃xff0c;这些信息输出出来就是d.ts&＃xff1a;

When a TypeScript script gets compiled there is an option to generate a declaration file (with the extension .d.ts) that functions as an interface to the components in the compiled Javascript.

&＃xff08;摘自Declaration files&＃xff09;

tsc&＃xff08;推荐&＃xff09;

安装&＃xff1a;

# 全局安装typescript
npm install typescript -g
# 测试安装是否成功
tsc --version

使用&＃xff1a;

# 后缀名改为.ts
cp ./path-to/my-file.js ./my-file.ts
# 从.ts生成d.ts
tsc --declaration my-file.ts

仅支持TS文件&＃xff0c;—allowJs选项在这里不可用&＃xff08;更多相关信息见Allow —declaration with —allowJs&＃xff09;&＃xff1a;

error TS5053: Option ‘allowJs’ cannot be specified with option ‘declaration’.

静态语义分析比运行时强大很多&＃xff0c;能够推断参数类型、识别JSDoc&＃xff0c;生成结果如下&＃xff1a;

/**
* 是不是一个emoji
* &＃64;param {String} str
*/
declare function isEmoji(str?: string): boolean;/**
* 是否含有emoji
* &＃64;param {String}} str
*/
declare function containsEmoji(str?: string): boolean;
declare var emoutils: {
   isEmoji: (str?: string) &＃61;> boolean;
   containsEmoji: (str?: string) &＃61;> boolean;
   str2unicodeArray: (str?: string) &＃61;> string[];
   length: (str?: string) &＃61;> number;
   substr: (str?: string, start?: number, len?: number) &＃61;> string;
   toArray: (str?: string) &＃61;> any[];};export default emoutils;

export { isEmoji, containsEmoji, str2unicodeArray, length, substr, toArray };



相当完美&＃xff0c;所以推荐使用这种方式&＃xff0c;唯一缺点是要改后缀名&＃xff0c;可以参考How do I rename the extension for a batch of files?

八.发布

经常看到类似&＃64;types/xxx的npm模块&＃xff0c;其实它们都来自DefinitelyTyped/DefinitelyTyped

当然&＃xff0c;也可以把自己模块的API声明放上去&＃xff0c;具体见How can I contribute?以及Microsoft/types-publisher工具

除了发布独立的typings模块&＃xff0c;还可以随功能模块一起发&＃xff0c;有两种方式&＃xff1a;

• index.d.ts&＃xff1a;把index.d.ts放在模块根目录下发布出去

• 指定types/typings&＃xff1a;在package.json里添上types&＃xff08;或者typings&＃xff09;字段&＃xff0c;例如”types”: “./lib/main.d.ts”

但types/typings都是非npm标准字段&＃xff0c;所以建议使用第一种方式

安装

如果依赖的功能模块没附带types&＃xff0c;可以通过TypeSearch搜索想要的typings模块&＃xff0c;再单独安装&＃xff0c;例如&＃xff1a;

npm install --save &＃64;types/lodash

像功能模块一样正常引用即可&＃xff1a;

import * as _ from "lodash";
_.padStart("Hello TypeScript!", 20, " ");

参考资料

• TypeScript Declaration File

• Writing Declaration Files for &＃64;types

• Declaration file

关于本文
作者&＃xff1a;&＃64;ayqy
原文&＃xff1a;http://blog.ayqy.net/