类型声明 👌

什么是类型声明文件

在前面的代码中，我们说从 typescript 编译到 Javascript 的过程中，类型消失了，比如下面的代码：

const str = "hello";
type User = {
  id: number;
  name: string;
  show?: (id: number, name: string) => void;
};

const u: User = {
  id: 1,
  name: "张三",
  show(id, name) {
    console.log(id, name);
  },
};

const users: Array<User> = [
  { id: 1, name: "jack" },
  { id: 2, name: "rose" },
];

function addUser(u: User) {
  // todos...
  return true;
}

addUser(u);

编译成 javascript 之后：

"use strict";
const str = "hello";
const u = {
  id: 1,
  name: "张三",
  show(id, name) {
    console.log(id, name);
  },
};
const users = [
  { id: 1, name: "jack" },
  { id: 2, name: "rose" },
];
function addUser(u) {
  // todos...
  return true;
}
addUser(u);

但是是真的消失了吗？其实并不是，如果大家留意之前我们在Playground上编写代码，专门有一项就叫做DTS，你会发现，我们写的代码都自动转换成了 typescript 类型声明。

当然，这在我们的 VS Code 编辑器中也能生成的。只需要在tsconfig.json文件中加上相关配置即可

{
  "compilerOptions": {
    "target": "es2020",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "outDir": "./dist",
+    "declaration": true,
+    "declarationDir": "./types",
  },
  "include": ["src/**/*.ts"],
  "exclude": ["./node_modules", "./dist", "./types"]
}

运行tsc，最后生成：[文件名].d.ts

declare const str = "hello";
type User = {
  id: number;
  name: string;
  show?: (id: number, name: string) => void;
};
declare const u: User;
declare const users: Array<User>;
declare function addUser(u: User): boolean;

也就是说，类型并不是真的全部消失了，而是被放到了专门的类型声明文件里。

.d.ts结尾的文件，就是类型声明文件。d的含义就是declaration

其实typescript本身就包含两种文件类型

1、.ts文件：既包含类型信息，又包含可执行代码，可以被编译成.js文件后执行，主要是我们编写文件代码的地方

2、.d.ts文件：只包含类型信息的类型声明文件，不会被编译成.js代码，仅仅提供类型信息，所以类型文件的用途就是提供类型信息

类型声明文件的来源

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

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

自动生成

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

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

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

declaration这个属性还与其他属性有强关联：

• declarationDir：指定生成的声明文件d.ts的输出目录

• emitDeclarationOnly：只输出 d.ts 文件，不输出 JavaScript 文件

• declarationMap：为 d.ts 文件创建源映射

内置声明文件

安装 TypeScript 语言时，会同时安装一些内置的类型声明文件，主要是内置的全局对象（JavaScript 语言接口和运行环境 API）的类型声明。这也就是为什么string，number等等基础类型，Javascript 的 api 直接就有类型提示的原因

内置声明文件位于 TypeScript 语言安装目录的lib文件夹内

这些内置声明文件的文件名统一为lib.[description].d.ts的形式，其中description部分描述了文件内容。比如，lib.dom.d.ts这个文件就描述了 DOM 结构的类型。

如果想了解对应的全局对象类型接口，可以去查看这些内置声明文件。

tsconfig.json中的配置target和lib其实就和内置声明文件是有关系的。TypeScript 编译器会自动根据编译目标target的值，加载对应的内置声明文件，默认不需要特别的配置。我们也可以指定加载哪些内置声明文件，自定义配置lib属性即可:

"lib":["es2020","dom","dom.iterable"]

为什么我们没有安装 typescript 之前也有提示？

这是由于我们的VS Code等 IDE 工具在安装或者更新的时候，已经内置了 typescript 的 lib。一般在你的VS Code安装路径 -> resources -> app -> extensios -> node_modules -> typescript 下

如果你的VS Code一直没有升级，就有可能导致本地VS Code的typescript版本跟不上的情况，如果你的项目目录下，也安装了 typescript，我们是可以进行切换的。

在VS Code中使用快捷键ctrl(command) + shift + P，输入TypeScript

选择Select Typescript Version...

你可以选择使用VS Code版本还是项目工作区的版本

外部类型声明文件

如果项目中使用了外部的某个第三方库，那么就需要这个库的类型声明文件。这时又分成三种情况了。

1、第三方库自带了类型声明文件

2、社区制作的类型声明文件

3、没有类型声明文件

没有类型声明这个很容易理解，我们现在不纠结这种情况，而且大多数情况下，我们也不应该去纠结他，关键是 1,2 两点是什么意思？其实我们下载两个常用的第三方库就能很明显的看出问题。

npm i axios lodash

注意：引入模块之前，涉及到模块的查找方式，因此在 tsconfig.json 中需要配置module

对于现代 Node.js 项目，我们可以配置NodeNext，注意这个配置会影响下面的配置：

"moduleResolution": "NodeNext",
"esModuleInterop": true

当然，具体模块化的配置，不同的环境要求是不一样的，有一定的区别，比如是 nodejs 环境，还是 webpack 的打包环境，或者说是在写一个第三方库的环境，对于模块化的要求是不一样的。而且还涉及到模块化解析方式等问题。这里就先不详细深入讲解了

在nodejs环境下，我们先简单配置为"module":"NodeNext"

在webapck/vite等打包环境下，设置为：

"module": "ESNext"

"moduleResolution": "bundler"

引入相关模块：

其实打开这两个库的源代码就能发现问题，axios 是有.d.ts文件的，而 lodash 没有，也就是说根本没有类型声明，那当然就和提示的错误一样，无法找到模块的声明文件。

第三方库如果没有提供类型声明文件，社区往往会提供。TypeScript 社区主要使用 DefinitelyTyped，各种类型声明文件都会提交到那里，已经包含了几千个第三方库。上面代码提示的错误，其实就是让我们到@types名称空间去下载 lodash 对应的类型声明，如果存在的话。当然，你也可以到npm上进行搜索。几乎你知道的所有较大的库，都会在上面找到，所以一般来说也要下载或者搜索都比较简单，@types开头，/后面加上第三方库原来的名字即可，比如：

@types/lodash，@types/jquery，@types/node，@types/react，@types/react-dom等等

npm i --save-dev @types/lodash

import lodash from "lodash";

const result = lodash.add(1, 2);
console.log(result);

默认情况下，所有可见的“@types”包都会包含在你的编译中。任何包含文件夹中node_modules/@types的包都被视为可见。“任何包含文件夹”意味着不仅是项目的直接node_modules/@types目录会被搜索，上层目录中的相应文件夹也会被递归搜索。

可以通过typeRoots选项设置查找的文件路径，如果指定了typeRoots，则只会包含typeRoots下的包。例如：

{
  "compilerOptions": {
    "typeRoots": ["./typings", "./vendor/types"]
  }
}

这个配置文件将会包含./typings和./vendor/types下的所有包，但不会包含./node_modules/@types下的任何包。所有路径都是相对于tsconfig.json文件的。

也就是说，如果你要手动指定typeRoots，那就需要自己手动指定所有需要查找的目录，如果你的项目中有深层次的目录结构，并且你希望包含其中的类型声明，你需要确保这些目录都被明确地添加到typeRoots中。

其实，nodejs 本身也没有 TypeScript 的类型声明，因此你会发现在.ts文件中直接引入 nodejs 相关的模块同样会报错

import path from "path"; // error 找不到模块"path"或其相应的类型声明

同样，我们直接在DefinitelyTyped下载即可

npm i @types/node -D

类型声明文件的用途

我们自己当然也能编写类型声明文件，但是声明文件.d.ts大多数时候是第三方库一起使用的，我们写代码教学阶段在 nodejs 环境下，单独去声明.d.ts文件没有太大的意义，首先大家要知道这个问题。所以，要使用.d.ts声明文件的场景一般是：

1、自己写了一个主要是 Javascript 代码的第三方库，需要给这写 Javascript 代码加上类型声明，以便用户使用的时候可以得到类型声明，方便调用 API。

2、自己下载了别人写的第三方库，但是没有 typescript 类型声明，在社区 DefinitelyTyped中也没有找到对应的类型声明，但是我们一定要用这个库，可以手动为这个库添加一些简单的类型声明，以免我们自己项目在使用这个第三方库没有类型声明报出错误提示。

3、在做应用项目的时候，需要补充一些全局的类型声明的时候，我们可能需要自己动手写.d.ts文件，其实这种情况大多数还是和第 2 点有关系