TypeScript 详解之 d.ts 类型声明文件

简介

单独使用的模块，一般会同时提供一个单独的类型声明文件（declaration file），把本模块的外部接口的所有类型都写在这个文件里面，便于模块使用者了解接口，也便于编译器检查使用者的用法是否正确。

类型声明文件里面只有类型代码，没有具体的代码实现。它的文件名一般为[模块名].d.ts的形式，其中的d表示 declaration（声明）。

举例来说，有一个模块的代码如下。

const maxInterval = 12;

function getArrayLength(arr) {
  return arr.length;
}

module.exports = {
  getArrayLength,
  maxInterval,
};

它的类型声明文件可以写成下面这样。

export function getArrayLength(arr: any[]): number;
export const maxInterval: 12;

类型声明文件也可以使用export =命令，输出对外接口。下面是 moment 模块的类型声明文件的例子。

declare module 'moment' {
  function moment(): any;
  export = moment;
}

上面示例中，模块moment内部有一个函数moment()，而export =表示module.exports输出的就是这个函数。

除了使用export =，模块输出在类型声明文件中，也可以使用export default表示。

// 模块输出
module.exports = 3.142;

// 类型输出文件
// 写法一
declare const pi: number;
export default pi;

// 写法二
declare const pi: number;
export= pi;

上面示例中，模块输出的是一个整数，那么可以用export default或export =表示输出这个值。

下面是一个如何使用类型声明文件的简单例子。有一个类型声明文件types.d.ts。

// types.d.ts
export interface Character {
  catchphrase?: string;
  name: string;
}

然后，就可以在 TypeScript 脚本里面导入该文件声明的类型。

// index.ts
import { Character } from "./types";

export const character:Character = {
  catchphrase: "Yee-haw!",
  name: "Sandy Cheeks",
};

类型声明文件也可以包括在项目的 tsconfig.json 文件里面，这样的话，编译器打包项目时，会自动将类型声明文件加入编译，而不必在每个脚本里面加载类型声明文件。比如，moment 模块的类型声明文件是moment.d.ts，使用 moment 模块的项目可以将其加入项目的 tsconfig.json 文件。

{
  "compilerOptions": {},
  "files": [
    "src/index.ts",
    "typings/moment.d.ts"
  ]
}

类型声明文件的来源

类型声明文件主要有以下三种来源。

• TypeScript 编译器自动生成。
• TypeScript 内置类型文件。
• 外部模块的类型声明文件，需要自己安装。

自动生成

只要使用编译选项declaration，编译器就会在编译时自动生成单独的类型声明文件。

下面是在tsconfig.json文件里面，打开这个选项。

{
  "compilerOptions": {
    "declaration": true
  }
}

你也可以在命令行打开这个选项。

$ tsc --declaration

内置声明文件

安装 TypeScript 语言时，会同时安装一些内置的类型声明文件，主要是内置的全局对象（JavaScript 语言接口和运行环境 API）的类型声明。

这些内置声明文件位于 TypeScript 语言安装目录的lib文件夹内，数量大概有几十个，下面是其中一些主要文件。