彻底搞懂 Typescirpt 声明文件

为什么需要声明文件

初始化项目

$ mkdir test-declare 
$ cd test-declare
$ npm init -y
$ yarn add typescript -D
$ npx tsc --init

创建 src/sum/index.js 文件,内容如下:
这是一个最普通不过的 js 文件,对外暴露 sum() 方法,在 nodejs 中运行。

function sum(a, b) {
    return a + b
}

module.exports = sum

创建 src/index.ts 文件,内容如下:
(这是一个 ts 文件,在 ts 文件中导入 js 文件)

import sum from './sum'

console.log(sum(2, 2))

这时,如果使用 Vscode 编辑代码,应该可以看到如下的报错:意思就是没找到 sum 文件的声明文件。

图1

为什么会报这个错误?

typescript 编译器看到的每个变量、方法都必须明确知道它的类型,在 src/index.ts 文件中导入 src/sum/index.js 文件,js 文件中的方法是没有类型的,造成 typescript 不能识别的错误。

解决方法也很简单,编辑 tsconfig.json 文件:

"allowJs": true,
"outDir": "./dist",
"rootDir": "./src",

其中 allowJs 配置告诉 typescript 编辑器将 js 文件中的所有变量和方法都设置 any 类型,这样 typescript 编译器就能识别 js 文件了。

添加配置后报错消失,鼠标移动到 sum() 方法可以看到方法参数确确实实都设置为 any 类型了。

图2

此时目录结构应该如下:

|-- test-declare
    |-- src
        |-- sum
            |-- index.js
        |-- index.ts
    |-- package.json
    |-- tsconfig.json

编译代码

打开黑窗口,编译代码,编译完成后根目录下会生成 dist 目录。

$ npx tsc -w

启动程序

另外打开一个黑窗口,运行程序,可以看到打印出计算结果。

$ node dist/index.js
$ 4

虽然 ts 文件中可以导入 js 文件,并正常运行程序,但但但但但但是,js 文件的方法类型全是 any 很恶心。

我们希望为 js 文件里的变量和方法添加真实的类型,这就需要定义声明文件。

定义类型声明文件

创建 src/sum/index.d.ts 文件,内容如下:

declare function sum(a: number, b: number): number

export default sum

此时再查看 src/index.ts 文件,可以看到导入的 sum() 方法的参数已经有类型提示了。👍

图3

此时目录结构为:

|-- test-declare
    |-- src
        |-- sum
            |-- index.js
            |-- index.d.ts      <=== 类型声明文件
        |-- index.ts
    |-- package.json
    |-- tsconfig.json

给第三方库写声明文件

很多第三方库是用 js 写的,通过设置 allowJs: true 配置可以在 typescript 工程使用这些库,但是没法知道库里面变量的类型以及方法参数的类型,很不友好。

我们期待:在 Vscode 开发时,只要敲出方法,编辑器可以自行提示该方法参数的类型是什么,这样我就不会把原本该写成数值类型的参数写成字符串类型了,大大降低代码出错风险。

图4

如果你是第三方库作者

如果您是第三方库的作者,我们希望您在自己的库里就添加上声明文件。

手动创建 node_modules/subtract 模拟第三方库,切换到 subtract 目录下执行 $ npm init -y 初始化 subtract 工程。

|-- test-declare
    |-- node_modules   <=== 手动创建 subtract 模拟第三方库 
        |-- subtract
            |-- src
                |-- index.js
            |-- index.d.ts
            |-- package.json
    |-- src
    |-- ....

编辑 node_modules/subtract/src/index.js 文件,内容如下:

function subtract(a, b) {
    return a - b
}

module.exports = subtract

编辑 node_modules/subtract/index.d.js 文件,内容如下:

declare function subtract(a: number, b: number): number

export default subtract

修改 package.json 文件,其中 types 指向声明文件路径。

"main": "./src/index.js",
"types": "./index.d.ts",

实测发现,外部库找第三方库声明文件默认路径为第三方库(subtract)根目录下的 index.d.ts 文件,找不到的话,会去找第三方库 package.json 中 types 字段中设置的路径。

编辑 src/index.ts 文件,导入 subtract 库并执行方法,鼠标移动到 subtract() 方法上,可以看到也是有参数类型提示的,测试成功。

图5

如果你是第三方库的使用者

如果您是第三方库的使用者,您是没法直接修改第三方库的源码,只能改自己的代码。

手动创建 node_modules/multiply 模拟第三方库,切换到 multiply 目录下执行 $ npm init -y 初始化 multiply 工程。

|-- test-declare
    |-- node_modules   <=== 手动创建 multiply 模拟第三方库 
        |-- multiply
            |-- index.js
            |-- package.json
    |-- src
    |-- ....

编辑 test-declare/node_modules/multiply/index.js 文件:

function multiply(a, b) {
    return a * b
}

module.exports = multiply

修改 test-declare/src/index.ts 文件,导入 multiply 模块,可以看到报错:没有找到 multiply 模块的声明文件。

图7

报错信息也提供了两种解决方案:

  • npm install @types/multiply 这种方案前提是有人已经写好了声明文件,我们可以直接安装下就哦了;
  • add a new declaration(.d.ts) file containing "declare module multiply" 如果没有 @types/multiply 包,还可以在根目录下新建 global.d.ts,内容写上 declare module 'multiply'。这样做只能保证代码不报错,但是鼠标移动到 multiply 上面是没有参数类型提示的,这明显不是我们想要的。
图8

(如果前面创建了 global.d.ts,删除它)

创建 test-declare/types/multiply/index.d.ts 文件写声明文件,types 下目录的名字一定要和第三方库的名字一毛一样,这里为第三方库 multiply 写声明文件,因此创建 types/multiply 目录。

declare function multiply(a: number, b: number): number

export default multiply

编辑 tsconfig.json 文件,告诉 typescirpt 去哪里找我们自己定义的声明文件。

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

回过头看下 src/index.ts 文件,multiply() 方法的参数类型已经可以显示了。

图9

此时目录结构为:

|-- test-declare
    |-- ...
    |-- src
    |-- types
        |-- multiply
            |-- index.d.ts        <=== 声明文件
    |-- ....

如何写声明文件

还剩最后一个话题,如何编写声明文件,这需要掌握 Typescript 基本语法。

导出一个方法

上面👆写的所有声明方法都是对外暴露一个方法,暴露变量类似。

源码 index.js

function divide (a, b) {
    return a / b
}

为 index.js 编写声明文件:

// index.d.ts
declare function divide(a: number, b: number): number
export default divide

导出一个对象字面量

想要导出一个对象字面量,这个对象字面量内包含了很多方法和变量,如何做?

源码 my-math.js

function multiply(a, b) {
    return a * b
}

function divide(a, b) {
    return a / b
}

const num1 = 4
const num2 = 2

module.exports = {
    multiply, divide, num1, num2
}

使用 namespace 对外导出一个对象字面量,对应的声明文件:

// index.d.ts
declare namespace obj {
    function multiply(a: number, b: number): number
    function divide(a: number, b: number): number
    const num1: number
    const num2: number
}

export default obj

使用:

// index.ts
import math from 'multiply'
console.log(math.multiply(math.num1, math.num2))

推荐阅读更多精彩内容

  • 点击原文 now我们来看一看TS怎么声明文件, 在JS里面我们经常会使用各种第三方类库,引入方式也不太相同,常见的...
    videring阅读 2,073评论 0 3
  • 当使用第三方库时,我们需要引用它的声明文件,才能获得对应的代码补全、接口提示等功能。这是因为前端第三方库大多都是非...
    学贤社阅读 2,668评论 1 3
  • 为TypeScript引用的JS写声明文件 写TypeScript声明文件的时候会有三个困惑,一个是声明文件是什么...
    心淡然如水阅读 20,724评论 1 2
  • core package 概要:Core是所有其他包的基础包.它提供了大部分功能包括metadata,templa...
    LOVE小狼阅读 1,842评论 0 3
  • 为什么要使用TS? 获得更好的开发体验,解决JS中一些难以解决的问题 JS存在的问题: 使用了不存在的变量函数或者...
    小丹子1o1阅读 110评论 0 0