【前端进阶之旅】TypeScript中的类型声明文件

文章目录

• • 前言
  • 一、什么是类型声明文件
  • 二、类型声明文件的来源
  • 三、如何自动生成类型声明文件
  • 四、内置声明文件
  • 五、外部类型声明文件

前言

在TypeScript（以下简称TS）的学习和实战中，类型声明文件（.d.ts）是一个贯穿入门到进阶的核心知识点。它不仅能解决“类型缺失”导致的开发提示异常、编译报错，更能让我们在使用第三方JS库时，享受TS带来的类型校验和智能提示，是前端工程化、规范化开发中不可或缺的一环。 本文将从“是什么、为什么用、怎么用”三个维度，结合实战场景，带你彻底搞懂TS类型声明文件，帮你在前端进阶之路上再进一步。

一、什么是类型声明文件

在前面的代码中，我们说从 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本身就包含两种文件类型

二、类型声明文件的来源

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

• 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两点是什么意思？其实我们下载两个常用的第三方库就能很明显的看出问题。

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声明文件的场景一般是：