导语:全面拥抱 TS 的时代,TS 已经成为日常开发中的重要部分。本文主要介绍 TS 声明文件的写法。
声明文件的定义
通俗地来讲,在 TypeScript 中以 .d.ts
为后缀的文件,我们称之为 TypeScript 声明文件。它的主要作用是描述 JavaScript 模块内所有导出接口的类型信息。
什么时候需要写 TS 声明文件
在日常的开发中,绝大多数时候是不需要我们单独去编写一个 TS 声明文件的。如果我们的文件本身是用 TS 编写的,在编译的时候让 TS 自动生成声明文件,并在发布的时候将 .d.ts
文件一起发布即可。
总结了以下三种情况,需要我们手动定义声明文件:
通过 script 标签引入的第三方库
一些通过 CDN 的当时映入的小的工具包,挂载了一些全局的方法,如果在 TS 中直接使用的话,会报 TS 语法错误,这时候就需要我们对这些全局的方法进行 TS 声明。
使用的第三方 npm 包,但是没有提供声明文件
第三方 npm 包如果有提供声明文件的话,一般会以两种形式存在:一是 @types/xxx
,另外是在源代码中提供 .d.ts
声明文件。第一种的话一般是一些使用量比较高的库会提供,可以通过 npm i @type/xxx
尝试安装。如果这两种都不存在的话,那就需要我们自己来定义了。
自身团队内比较优秀的 JS 库或插件,为了提升开发体验
如何编写 TS 声明文件
对于不同形式的声明文件,写法上会有一定的差异。这里需要特别注意一点的是:声明文件中只是对类型的定义,不能进行赋值。
???? 全局变量
全局变量的声明文件主要有以下几种语法:
declare let/const // 声明全局变量
declare function // 声明全局方法
declare class // 声明全局类
declare enum // 声明全局枚举类型
declare namespace // 声明(含有子属性的)全局对象
interface/type // 声明全局类型
这里需要注意的是只是定义类型,不能进行赋值。
// 变量
declare let userName: string;
declare const wx: any;
// 函数、函数重载
declare function getName(uid: number): string;
declare function getName(): string;
declare function getName(cb: () => any): any;
// 类
declare class Course {
cid: number;
constructor(cid){};
getCoursePrice(): number;
}
// 枚举
declare enum Status {
Loading,
Success,
Failed,
}
// 接口 interface declare 可以不需要
interface CourseInfo {
cid: number;
name: string;
}
interface CGIData<T> {
data: T;
retcode: 0;
}
// 命名空间
declare namespace User {
// 局部 Test.User
interface User {
name: string;
age: number;
}
function getUserInfo(name: string): User {
return "";
}
namespace fn {
function extend(obj: any): any;
}
}
// 声明合并
declare function User(id: number): string;
???? npm 包
对于没有提供声明文件的 npm 包,我们可以创建一个 types 目录,来管理自己写的声明文件,同时需要在配置文件 tsconfig.json
中的 paths 和 basrUrl 中配置:
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./", // types文件夹的相对路径
"paths": { "*": ["types/*"]}
}
}
npm 包的声明文件主要有以下几种语法:
export const/let // 导出变量
export namespace // 导出(含有自属性的)对象
export default // ES6 默认导出
export = // commonjs 导出模块
???? 拓展原有模块/全局变量
对于已经有声明定义的模块或者全局变量,可以利用 TS 中的声明合并对其进行拓展。
比如在 window 下挂载的一些全局变量:
interface Window {
readonly request?: any;
readonly devToolsExtension?: any;
readonly wx?: any;
}
对已有模块进行拓展:
declare module "querystring" {
function escape(str: string): string;
function unescape(str: string): string;
}
还可以使用三斜线的方式对声明文件进行引用:
/// <reference path=”custom.d.ts" />
最后
如何让 TS 在编译时自动生成 .d.ts
文件呢?只需要在 tsconfig.json
配置文件中开启即可,TS 编译时就会自动生成 .d.ts
声明文件:
{
"compilerOptions": {
"declaration": true
}
}
参考
TypeScript入门教程–声明文件
爱心三连击
1.看到这里了就点个在看支持下吧,你的在看是我创作的动力。
2.关注公众号脑洞前端,获取更多前端硬核文章!加个星标,不错过每一条成长的机会。
3.如果你觉得本文的内容对你有帮助,就帮我转发一下吧。