查看原文
其他

【第1499期】d.ts

ayqy 前端早读课 2019-06-04

前言

现在用ts的童鞋多么?今日早读文章由@ayqy授权分享。

正文从这开始~~

一.简介

经常看到d.ts,因为一个越来越广泛的应用场景是编辑器智能提示(具体见IntelliSense based on TypeScript Declaration Files):

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,存放一些声明,类似于C/C++的.h头文件(#include <stdio.h>):

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++, you can think of these as .h files.

(摘自Working with Other JavaScript Libraries)

P.S.另一个“ambient”(环境?)相关的概念Ambient Namespace,指的也是只有声明没有实现的namespace

二.分类

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

例如jQuery 1.x通常以global库的方式引用:

<script type="text/javascript" src="script/jquery.min.js"></script>
<script>
 $
( "button.continue" ).html( "Next Step..." )
</script>

而jQuery 3.x支持模块引用:

// ES Module
import $ from "jquery";
// Commonjs Module
const $ = require("jquery");

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

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

jQuery-3.x.d.ts:

export = jQuery;

因此,我们把类库分为3类:

  • global:暴露出全局变量的类库

  • module:不暴露全局变量,需要通过特定加载机制(如require/define/import)引用的模块形式的类库

  • plugin:会影响其它类库功能的类库(当然,也可能会影响原声明,比如添个新API)

3种类库对应的声明文件细分成6种,模板及适用场景如下:

  • global.d.ts:适用于global类库

  • module-function.d.ts:适用于暴露出一个Function的module类库

  • module-class.d.ts:适用于暴露出一个Class的module类库

  • module.d.ts:适用于一般module类库(暴露出的东西既不是Function也不是Class)

  • module-plugin.d.ts:适用于module plugin类库(A module plugin changes the shape of another module.)

  • global-plugin.d.ts:适用于global plugin类库(A global plugin is global code that changes the shape of some global.)

  • global-modifying-module.d.ts:适用于module形式的global plugin类库(They’re similar to global plugins, but need a require call to activate their effects.)

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

三.引用方式

不同类型的声明文件对应的引用方式也不同,global类库声明通过/// <reference types="..." />指令引用,例如:

/// <reference types="someLib" />
function getThing(): someLib.thing;

module类库声明用import语句引用:

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

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

/// <reference types="moment" />
function getThing(): moment;

而module/UMD类库依赖UMD类库时则用import语句:

import * as someLib from 'someLib';

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

四.语法格式

全局变量
/** The number of widgets present */
declare
var foo: number;

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

类型部分与TS基本类型语法一致,具体见Basic Types

全局函数
declare function greet(greeting: string): void;

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

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

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

函数重载
declare function getWidget(n: number): Widget;
declare
function getWidget(s: string): Widget[];

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

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

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

类型别名
type GreetingLike = string | (() => string) | MyGreeter;
declare
function greet(g: GreetingLike): void;

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

类型“模块”
declare namespace GreetingLib {
   
interface LogOptions {
       verbose
?: boolean;
   
}
   
interface AlertOptions {
       modal
: boolean;
       title
?: string;
       color
?: string;
   
}
}

类似于namespace能够组织代码模块(把一组相关代码放在一起),declare namespace能用来组织类型“模块”(把一组相关类型声明放在一起)

P.S.同样,嵌套namespace也是支持的,如declare namespace GreetingLib.Options {//}

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

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

五.实践规范

除了遵循基本的语法格式外,实践中还应该遵守这些规范约束:

  • 用基础类型(number, string, boolean, object),不要用包装类型(Number, String, Boolean, Object)

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

  • 无返回值的callback参数返回类型用void,不要用any

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

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

  • 能用可选参数(如two?: string)描述的就别用函数重载了

  • 能用组合类型(如b: number|string)描述的就别用函数重载了

六.类型,值和命名空间

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

具体的,类型有5种声明方式:

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

值有6种声明方式:

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

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

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

// 值与类型的结合
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 = ...;
console
.log(a.x + a.y + a.z); // OK
// 命名空间与类型的结合
class C {
}
// ... elsewhere ...
namespace C {
 
export let x: number;
}
let y = 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
= string;

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

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 = string), and namespaces never conflict.

所以上例中的某些命名(Bar、Foo)虽然存在多种含义,但都不冲突,仍然是合法的

七.自动生成

dts-gen(不建议用)
# 全局安装dts-gen
npm install
-g dts-gen

Microsoft/dts-gen是官方脚手架工具(已经1年不更新了,但聊胜于无),能为JS生成d.ts:

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

能够帮助生成基本的API列表,例如:

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

具体用法如下:

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

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

用法有些奇怪,因为这个东西是运行时的:

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

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

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

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

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生成的东西太弱了,那么,有没有更厉害的方式?

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

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.

(摘自Declaration files)

tsc(推荐)

安装:

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

使用:

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

仅支持TS文件,—allowJs选项在这里不可用(更多相关信息见Allow —declaration with —allowJs):

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

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

/**
* 是不是一个emoji * @param {String} str */

declare
function isEmoji(str?: string): boolean;
/**
* 是否含有emoji * @param {String}} str */

declare
function containsEmoji(str?: string): boolean;
declare
var emoutils: {
   isEmoji
: (str?: string) => boolean;
   containsEmoji
: (str?: string) => boolean;
   str2unicodeArray
: (str?: string) => string[];
   length
: (str?: string) => number;
   substr
: (str?: string, start?: number, len?: number) => string;
   toArray
: (str?: string) => any[];
};
export default emoutils;
export { isEmoji, containsEmoji, str2unicodeArray, length, substr, toArray };

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

八.发布

经常看到类似@types/xxx的npm模块,其实它们都来自DefinitelyTyped/DefinitelyTyped

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

除了发布独立的typings模块,还可以随功能模块一起发,有两种方式:

  • index.d.ts:把index.d.ts放在模块根目录下发布出去

  • 指定types/typings:在package.json里添上types(或者typings)字段,例如”types”: “./lib/main.d.ts”

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

安装

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

npm install --save @types/lodash

像功能模块一样正常引用即可:

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

参考资料

  • TypeScript Declaration File

  • Writing Declaration Files for @types

  • Declaration file

关于本文
作者:@ayqy
原文:http://blog.ayqy.net/

最后,为你推荐


【第1491期】如何编写 Typescript 声明文件

【第1207期】TypeScript 实践分享

他曾分享过

专访|@黯羽轻扬,CSS2.1规范中文版译者

    您可能也对以下帖子感兴趣

    文章有问题?点此查看未经处理的缓存