Typescript关于类型声明

关于类型声明文件

声明文件中的内容是外部声明。外部声明用于为已有代码提供静态类型信息以供TypeScript编译器使用。

外部声明是TypeScript语言规范中使用的术语。我们不必纠结于如何划分外部和内部，它是一个相对概念。

外部声明也可以出现在“.ts”文件中，我们只需明确外部声明是类型声明而不是具体实现，外部声明在编译后不会输出任何可执行代码即可。

外部声明包含以下两类：

外部类型声明。

外部模块声明。

模块模式与脚本模式

TypeScript采用两种模式编译TypeScript文件：模块模式和脚本模式。具体编译为哪个模式，通过一项检测确定：文件中有没有import 或 export语句？如果有，使用模块模式：否则，使用脚本模式。

在脚本模式下，声明的顶层变量在项目中的任何文件中都可以使用，无需导入；而且，可以放心使用第三方UMD模块中的全局导出，不用事先导入。

关于书写类型声明

推荐的是使用 @types 统一管理第三方库的声明文件。

@types 的使用方式很简单，直接用 npm 安装对应的声明模块即可，以 jQuery 举例：

npm install @types/jquery --save-dev

书写声明文件

当一个第三方库没有提供声明文件时，我们就需要自己书写声明文件了。

在不同的场景下，声明文件的内容和使用方式会有所区别。

库的使用场景主要有以下几种：

全局变量：通过 <script> 标签引入第三方库，注入全局变量

npm 包：通过 import foo from 'foo' 导入，符合 ES6 模块规范

UMD 库：既可以通过 <script> 标签引入，又可以通过 import 导入

直接扩展全局变量：通过 <script> 标签引入后，改变一个全局变量的结构

在 npm 包或 UMD 库中扩展全局变量：引用 npm 包或 UMD 库后，改变一个全局变量的结构

模块插件：通过 <script> 或 import 导入后，改变另一个模块的结构

全局变量

全局变量是最简单的一种场景，比如： <script> 标签引入 jQuery，注入全局变量 $ 和 jQuery。

注意：这里的全局变量声明，需要在脚本模式（即声明文件没有，import和export关键字）

全局变量的声明文件主要有以下几种语法：

declare var 声明全局变量

declare function 声明全局方法

declare class 声明全局类

declare enum 声明全局枚举类型

declare namespace 声明（含有子属性的）全局对象

interface 和 type 声明全局类型

在类型声明文件中，顶层值要使用declare关键字（ declare let、declare function、declare class等），而顶层类型和接口(类型关键字：type，接口关键字：interface)则不需要（因为类型和接口是typescript独有的，javascript没有）。

`declare var`

在所有的声明语句中，declare var 是最简单的，如之前所学，它能够用来定义一个全局变量的类型。与其类似的，还有 declare let 和 declare const，使用 let 与使用 var 没有什么区别

而当我们使用 const 定义时，表示此时的全局变量是一个常量，不允许再去修改它的值：

// src/jQuery.d.ts
declare let jQuery: (selector: string) => any;

`declare function`

declare function 用来定义全局函数的类型。jQuery 其实就是一个函数，所以也可以用 function 来定义：

// src/jQuery.d.ts
declare function jQuery(selector: string): any;

在函数类型的声明语句中，函数重载也是支持的

// src/jQuery.d.ts
declare function jQuery(selector: string): any;
declare function jQuery(domReadyCallback: () => any): any;

`declare class`

当全局变量是一个类的时候，我们用 declare class 来定义它的类型

// src/Animal.d.ts
declare class Animal {
    name: string;
    constructor(name: string);
    sayHi(): string;
}

`declare enum`

使用 declare enum 定义的枚举类型也称作外部枚举（Ambient Enums）

// src/Directions.d.ts
declare enum Directions {
    Up,
    Down,
    Left,
    Right
}

`declare namespace`

namespace 是 ts 早期时为了解决模块化而创造的关键字，中文称为命名空间。

由于历史遗留原因，在早期还没有 ES6 的时候，ts 提供了一种模块化方案，使用 module 关键字表示内部模块。但由于后来 ES6 也使用了 module 关键字，ts 为了兼容 ES6，使用 namespace 替代了自己的 module，更名为命名空间。

随着 ES6 的广泛应用，现在已经不建议再使用 ts 中的 namespace，而推荐使用 ES6 的模块化方案了，故我们不再需要学习 namespace 的使用了。

namespace 被淘汰了，但是在声明文件中，declare namespace 还是比较常用的，它用来表示全局变量是一个对象，包含很多子属性。

比如 jQuery 是一个全局变量，它是一个对象，提供了一个 jQuery.ajax 方法可以调用，那么我们就应该使用 declare namespace jQuery 来声明这个拥有多个子属性的全局变量。

// src/jQuery.d.ts
declare namespace jQuery {
    function ajax(url: string, settings?: any): void;
}

注意，在 declare namespace 内部，我们直接使用 function ajax 来声明函数，而不是使用 declare function ajax。类似的，也可以使用 const, class, enum 等语句;

外部命名空间的成员默认为导出成员，不需要使用export关键字来明确地导出它们，但使用了export关键字也没有错误。

嵌套的命名空间

如果对象拥有深层的层级，则需要用嵌套的 namespace 来声明深层的属性的类型

// src/jQuery.d.ts
declare namespace jQuery {
    function ajax(url: string, settings?: any): void;
    namespace fn {
        function extend(object: any): void;
    }
}

`interface` 和 `type`

除了全局变量之外，可能有一些类型我们也希望能暴露出来。在类型声明文件中，我们可以直接使用 interface 或 type 来声明一个全局的接口或类型

// src/jQuery.d.ts
interface AjaxSettings {
    method?: 'GET' | 'POST'
    data?: any;
}
declare namespace jQuery {
    function ajax(url: string, settings?: AjaxSettings): void;
}

防止命名冲突

暴露在最外层的 interface 或 type 会作为全局类型作用于整个项目中，我们应该尽可能的减少全局变量或全局类型的数量。故最好将他们放到 namespace

// src/jQuery.d.ts
declare namespace jQuery {
    interface AjaxSettings {
        method?: 'GET' | 'POST'
        data?: any;
    }
    function ajax(url: string, settings?: AjaxSettings): void;
}

注意，在使用这个 interface 的时候，也应该加上 jQuery 前缀：

// src/index.ts
let settings: jQuery.AjaxSettings = {
    method: 'POST',
    data: {
        name: 'foo'
    }
};
jQuery.ajax('/api/post_something', settings);

声明合并

假如 jQuery 既是一个函数，可以直接被调用 jQuery('#foo')，又是一个对象，拥有子属性 jQuery.ajax()（事实确实如此），那么我们可以组合多个声明语句，它们会不冲突的合并起来

// src/jQuery.d.ts
declare function jQuery(selector: string): any;
declare namespace jQuery {
    function ajax(url: string, settings?: any): void;
}

npm 包

一般我们通过 import foo from 'foo' 导入一个 npm 包，这是符合 ES6 模块规范的。

在我们尝试给一个 npm 包创建声明文件之前，需要先看看它的声明文件是否已经存在。一般来说，npm 包的声明文件可能存在于两个地方：

与该 npm 包绑定在一起。判断依据是 package.json 中有 types 字段，或者有一个 index.d.ts 声明文件。这种模式不需要额外安装其他包，是最为推荐的，所以以后我们自己创建 npm 包的时候，最好也将声明文件与 npm 包绑定在一起。

发布到 @types 里。我们只需要尝试安装一下对应的 @types 包就知道是否存在该声明文件，安装命令是 npm install @types/foo --save-dev。这种模式一般是由于 npm 包的维护者没有提供声明文件，所以只能由其他人将声明文件发布到 @types 里了。

假如以上两种方式都没有找到对应的声明文件，那么我们就需要自己为它写声明文件了。由于是通过 import 语句导入的模块，所以声明文件存放的位置也有所约束，一般有两种方案：

创建一个 node_modules/@types/foo/index.d.ts 文件，存放 foo 模块的声明文件。这种方式不需要额外的配置，但是 node_modules 目录不稳定，代码也没有被保存到仓库中，无法回溯版本，有不小心被删除的风险，故不太建议用这种方案，一般只用作临时测试。

创建一个 types 目录，专门用来管理自己写的声明文件，将 foo 的声明文件放到 types/foo/index.d.ts 中。这种方式需要配置下 tsconfig.json 中的 paths 和 baseUrl 字段。

目录结构：

/path/to/project
├── src
|  └── index.ts
├── types
|  └── foo
|     └── index.d.ts
└── tsconfig.json

tsconfig.json 内容：

{
    "compilerOptions": {
        "module": "commonjs",
        "baseUrl": "./",
        "paths": {
            "*": ["types/*"]
        }
    }
}

如此配置之后，通过 import 导入 foo 的时候，也会去 types 目录下寻找对应的模块的声明文件了。

注意 module 配置可以有很多种选项，不同的选项会影响模块的导入导出模式。

npm 包的声明文件主要有以下几种语法：

export 导出变量

export namespace 导出（含有子属性的）对象

export default ES6 默认导出

export = commonjs 导出模块

`export`

npm 包的声明文件与全局变量的声明文件有很大区别。在 npm 包的声明文件中，使用 declare 不再会声明一个全局变量，而只会在当前文件中声明一个局部变量。只有在声明文件中使用 export 导出，然后在使用方 import 导入后，才会应用到这些类型声明。

export 的语法与普通的 ts 中的语法类似，区别仅在于声明文件中禁止定义具体的实现

// types/foo/index.d.ts
export const name: string;
export function getName(): string;
export class Animal {
    constructor(name: string);
    sayHi(): string;
}
export enum Directions {
    Up,
    Down,
    Left,
    Right
}
export interface Options {
    data: any;
}

对应的导入和使用模块应该是这样：

// src/index.ts
import { name, getName, Animal, Directions, Options } from 'foo';
console.log(name);
let myName = getName();
let cat = new Animal('Tom');
let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];
let options: Options = {
    data: {
        name: 'foo'
    }
};

混用 `declare` 和 `export`

我们也可以使用 declare 先声明多个变量，最后再用 export 一次性导出。上例的声明文件可以等价的改写为

// types/foo/index.d.ts
declare const name: string;
declare function getName(): string;
declare class Animal {
    constructor(name: string);
    sayHi(): string;
}
declare enum Directions {
    Up,
    Down,
    Left,
    Right
}
interface Options {
    data: any;
}
export { name, getName, Animal, Directions, Options };

注意，与全局变量的声明文件类似，interface 前是不需要 declare 的

`export namespace`

与 declare namespace 类似，export namespace 用来导出一个拥有子属性的对象

// types/foo/index.d.ts
export namespace foo {
    const name: string;
    namespace bar {
        function baz(): string;
    }
}

`export default`

在 ES6 模块系统中，使用 export default 可以导出一个默认值，使用方可以用 import foo from 'foo' 而不是 import { foo } from 'foo' 来导入这个默认值。

在类型声明文件中，export default 用来导出默认值的类型

// types/foo/index.d.ts
export default function foo(): string;

// src/index.ts
import foo from 'foo';
foo();

注意，只有 function、class 和 interface 可以直接默认导出，其他的变量需要先定义出来，再默认导出

// types/foo/index.d.ts
export default enum Directions {
// ERROR: Expression expected.
    Up,
    Down,
    Left,
    Right
}

上例中 export default enum 是错误的语法，需要使用 declare enum 定义出来，然后使用 export default 导出

// types/foo/index.d.ts
declare enum Directions {
    Up,
    Down,
    Left,
    Right
}
export default Directions;

`export =`

在 commonjs 规范中，我们用以下方式来导出一个模块

// 整体导出
module.exports = foo;
// 单个导出
exports.bar = bar;

在 ts 中，针对这种模块导出，有多种方式可以导入，第一种方式是 const ... = require

// 整体导入
const foo = require('foo');
// 单个导入
const bar = require('foo').bar;

第二种方式是 import ... from，注意针对整体导出，需要使用 import * as 来导入：

// 整体导入
import * as foo from 'foo';
// 单个导入
import { bar } from 'foo';

第三种方式是 import ... require，这也是 ts 官方推荐的方式：

// 整体导入
import foo = require('foo');
// 单个导入
import bar = foo.bar;

对于这种使用 commonjs 规范的库，假如要为它写类型声明文件的话，就需要使用到 export = 这种语法

// types/foo/index.d.ts
export = foo;
declare function foo(): string;
declare namespace foo {
    const bar: number;
}

需要注意的是，上例中使用了 export = 之后，就不能再单个导出 export { bar } 了。所以我们通过声明合并，使用 declare namespace foo 来将 bar 合并到 foo 里。

准确地讲，export = 不仅可以用在声明文件中，也可以用在普通的 ts 文件中。实际上，import ... require 和 export = 都是 ts 为了兼容 AMD 规范和 commonjs 规范而创立的新语法，由于并不常用也不推荐使用，所以这里就不详细介绍了，感兴趣的可以看官方文档。

由于很多第三方库是 commonjs 规范的，所以声明文件也就不得不用到 export = 这种语法了。但是还是需要再强调下，相比与 export =，我们更推荐使用 ES6 标准的 export default 和 export。

UMD 库

既可以通过 <script> 标签引入，又可以通过 import 导入的库，称为 UMD 库。相比于 npm 包的类型声明文件，我们需要额外声明一个全局变量，为了实现这种方式，ts 提供了一个新语法 export as namespace

`export as namespace`

一般使用 export as namespace 时，都是先有了 npm 包的声明文件，再基于它添加一条 export as namespace 语句，即可将声明好的一个变量声明为全局变量，举例如下

// types/foo/index.d.ts
export as namespace foo;
export = foo;
declare function foo(): string;
declare namespace foo {
    const bar: number;
}

当然它也可以与 export default 一起使用：

// types/foo/index.d.ts
export as namespace foo;
export default foo;
declare function foo(): string;
declare namespace foo {
    const bar: number;
}

直接扩展全局变量

有的第三方库扩展了一个全局变量，可是此全局变量的类型却没有相应的更新过来，就会导致 ts 编译错误，此时就需要扩展全局变量的类型。比如扩展 String 类型

interface String {
    prependHello(): string;
}
'foo'.prependHello();

通过声明合并，使用 interface String 即可给 String 添加属性或方法

也可以使用 declare namespace 给已有的命名空间添加类型声明

// types/jquery-plugin/index.d.ts
declare namespace JQuery {
    interface CustomOptions {
        bar: string;
    }
}
interface JQueryStatic {
    foo(options: JQuery.CustomOptions): string;
}

// src/index.ts
jQuery.foo({
    bar: ''
});

在 npm 包或 UMD 库中扩展全局变量

如之前所说，对于一个 npm 包或者 UMD 库的声明文件，只有 export 导出的类型声明才能被导入****。所以对于 npm 包或 UMD 库，如果导入此库之后会扩展全局变量，则需要使用另一种语法在声明文件中扩展全局变量的类型，那就是 declare global

`declare global`

使用 declare global 可以在 npm 包或者 UMD 库的声明文件中扩展全局变量的类型

// types/foo/index.d.ts
declare global {
    interface String {
        prependHello(): string;
    }
}
export {};

注意即使此声明文件不需要导出任何东西，仍然需要导出一个空对象，用来告诉编译器这是一个模块的声明文件，而不是一个全局变量的声明文件。

模块插件

有时通过 import 导入一个模块插件，可以改变另一个原有模块的结构。此时如果原有模块已经有了类型声明文件，而插件模块没有类型声明文件，就会导致类型不完整，缺少插件部分的类型。ts 提供了一个语法 declare module，它可以用来扩展原有模块的类型。

`declare module`

如果是需要扩展原有模块的话，需要在类型声明文件中先引用原有模块，再使用 declare module 扩展原有模块

// types/moment-plugin/index.d.ts
import * as moment from 'moment';
declare module 'moment' {
    export function foo(): moment.CalendarKey;
}

// src/index.ts
import * as moment from 'moment';
import 'moment-plugin';
moment.foo();

declare module 也可用于在一个文件中一次性声明多个模块的类型

// types/foo-bar.d.ts
declare module 'foo' {
    export interface Foo {
        foo: string;
    }
}
declare module 'bar' {
    export function bar(): string;
}

// src/index.ts
import { Foo } from 'foo';
import * as bar from 'bar';
let f: Foo;
bar.bar();

声明文件中的依赖

一个声明文件有时会依赖另一个声明文件中的类型，比如在前面的 declare module 的例子中，我们就在声明文件中导入了 moment，并且使用了 moment.CalendarKey 这个类型

// types/moment-plugin/index.d.ts
import * as moment from 'moment';
declare module 'moment' {
    export function foo(): moment.CalendarKey;
}

除了可以在声明文件中通过 import 导入另一个声明文件中的类型之外，还有一个语法也可以用来导入另一个声明文件，那就是三斜线指令。

三斜线指令

与 namespace 类似，三斜线指令也是 ts 在早期版本中为了描述模块之间的依赖关系而创造的语法。随着 ES6 的广泛应用，现在已经不建议再使用 ts 中的三斜线指令来声明模块之间的依赖关系了。

但是在声明文件中，它还是有一定的用武之地。

类似于声明文件中的 import，它可以用来导入另一个声明文件。与 import 的区别是，当且仅当在以下几个场景下，我们才需要使用三斜线指令替代 import：

当我们在书写一个全局变量的声明文件时

当我们需要依赖一个全局变量的声明文件时

书写一个全局变量的声明文件

这些场景听上去很拗口，但实际上很好理解——在全局变量的声明文件中，是不允许出现 import, export 关键字的。一旦出现了，那么他就会被视为一个 npm 包或 UMD 库，就不再是全局变量的声明文件了。

故当我们在书写一个全局变量的声明文件时，如果需要引用另一个库的类型，那么就必须用三斜线指令了

// types/jquery-plugin/index.d.ts
/// <reference types="jquery" />
declare function foo(options: JQuery.AjaxSettings): string;

三斜线指令的语法如上，/// 后面使用 xml 的格式添加了对 jquery 类型的依赖，这样就可以在声明文件中使用 JQuery.AjaxSettings 类型了。

注意，三斜线指令必须放在文件的最顶端，三斜线指令的前面只允许出现单行或多行注释。

依赖一个全局变量的声明文件

在另一个场景下，当我们需要依赖一个全局变量的声明文件时，由于全局变量不支持通过 import 导入，当然也就必须使用三斜线指令来引入了

// types/node-plugin/index.d.ts
/// <reference types="node" />
export function foo(p: NodeJS.Process): string;

在上面的例子中，我们通过三斜线指引入了 node 的类型，然后在声明文件中使用了 NodeJS.Process 这个类型。最后在使用到 foo 的时候，传入了 node 中的全局变量 process。

由于引入的 node 中的类型都是全局变量的类型，它们是没有办法通过 import 来导入的，所以这种场景下也只能通过三斜线指令来引入了。

以上两种使用场景下，都是由于需要书写或需要依赖全局变量的声明文件，所以必须使用三斜线指令。在其他的一些不是必要使用三斜线指令的情况下，就都需要使用 import 来导入。

拆分声明文件

当我们的全局变量的声明文件太大时，可以通过拆分为多个文件，然后在一个入口文件中将它们一一引入，来提高代码的可维护性。比如 jQuery 的声明文件就是这样的：

// node_modules/@types/jquery/index.d.ts
/// <reference types="sizzle" />
/// <reference path="JQueryStatic.d.ts" />
/// <reference path="JQuery.d.ts" />
/// <reference path="misc.d.ts" />
/// <reference path="legacy.d.ts" />
export = jQuery;

其中用到了 types 和 path 两种不同的指令。它们的区别是：types 用于声明对另一个库的依赖，而 path 用于声明对另一个文件的依赖。

上例中，sizzle 是与 jquery 平行的另一个库，所以需要使用 types="sizzle" 来声明对它的依赖。而其他的三斜线指令就是将 jquery 的声明拆分到不同的文件中了，然后在这个入口文件中使用 path="foo" 将它们一一引入

其他三斜线指令

除了这两种三斜线指令之外，还有其他的三斜线指令，比如 /// <reference no-default-lib="true"/>, /// <amd-module /> 等，但它们都是废弃的语法，故这里就不介绍了，详情可见官网。

自动生成声明文件

如果库的源码本身就是由 ts 写的，那么在使用 tsc 脚本将 ts 编译为 js 的时候，添加 declaration 选项，就可以同时也生成 .d.ts 声明文件了。

我们可以在命令行中添加 --declaration（简写 -d），或者在 tsconfig.json 中添加 declaration 选项。这里以 tsconfig.json 为例：

{
    "compilerOptions": {
        "module": "commonjs",
        "outDir": "lib",
        "declaration": true,
    }
}

上例中我们添加了 outDir 选项，将 ts 文件的编译结果输出到 lib 目录下，然后添加了 declaration 选项，设置为 true，表示将会由 ts 文件自动生成 .d.ts 声明文件，也会输出到 lib 目录下。

运行 tsc 之后，目录结构如下

/path/to/project
├── lib
|  ├── bar
|  |  ├── index.d.ts
|  |  └── index.js
|  ├── index.d.ts
|  └── index.js
├── src
|  ├── bar
|  |  └── index.ts
|  └── index.ts
├── package.json
└── tsconfig.json

在这个例子中，src 目录下有两个 ts 文件，分别是 src/index.ts 和 src/bar/index.ts，它们被编译到 lib 目录下的同时，也会生成对应的两个声明文件 lib/index.d.ts 和 lib/bar/index.d.ts。它们的内容分别是：

// src/index.ts
export * from './bar';
export default function foo() {
    return 'foo';
}

// src/bar/index.ts
export function bar() {
    return 'bar';
}

// lib/index.d.ts
export * from './bar';
export default function foo(): string;

// lib/bar/index.d.ts
export declare function bar(): string;

可见，自动生成的声明文件基本保持了源码的结构，而将具体实现去掉了，生成了对应的类型声明。

使用 tsc 自动生成声明文件时，每个 ts 文件都会对应一个 .d.ts 声明文件。这样的好处是，使用方不仅可以在使用 import foo from 'foo' 导入默认的模块时获得类型提示，还可以在使用 import bar from 'foo/lib/bar' 导入一个子模块时，也获得对应的类型提示。

除了 declaration 选项之外，还有几个选项也与自动生成声明文件有关，这里只简单列举出来，不做详细演示了：

declarationDir 设置生成 .d.ts 文件的目录

declarationMap 对每个 .d.ts 文件，都生成对应的 .d.ts.map（sourcemap）文件

emitDeclarationOnly 仅生成 .d.ts 文件，不生成 .js 文件

参考：类型声明文件

posted @ 2024-04-21 20:56 CD、小月阅读(517) 评论(0) 收藏举报

刷新页面返回顶部

一纾

Typescript关于类型声明

关于类型声明文件

模块模式与脚本模式

关于书写类型声明

书写声明文件

全局变量

`declare var`

`declare function`

`declare class`

`declare enum`

`declare namespace`

嵌套的命名空间

`interface` 和 `type`

防止命名冲突

声明合并

npm 包

`export`

混用 `declare` 和 `export`

`export namespace`

`export default`

`export =`

UMD 库

`export as namespace`

直接扩展全局变量

在 npm 包或 UMD 库中扩展全局变量

`declare global`

模块插件

`declare module`

声明文件中的依赖

三斜线指令

书写一个全局变量的声明文件

依赖一个全局变量的声明文件

拆分声明文件

其他三斜线指令

自动生成声明文件

公告

一纾

Typescript关于类型声明

关于类型声明文件

模块模式与脚本模式

关于书写类型声明

书写声明文件

全局变量

declare var

declare function

declare class

declare enum

declare namespace

嵌套的命名空间

interface 和 type

防止命名冲突

声明合并

npm 包

export

混用 declare 和 export

export namespace

export default

export =

UMD 库

export as namespace

直接扩展全局变量

在 npm 包或 UMD 库中扩展全局变量

declare global

模块插件

declare module

声明文件中的依赖

三斜线指令

书写一个全局变量的声明文件

依赖一个全局变量的声明文件

拆分声明文件

其他三斜线指令

自动生成声明文件

公告

`declare var`

`declare function`

`declare class`

`declare enum`

`declare namespace`

`interface` 和 `type`

`export`

混用 `declare` 和 `export`

`export namespace`

`export default`

`export =`

`export as namespace`

`declare global`

`declare module`