企业官网建设流程全解析

TypeScript 中的声明文件（Declaration Files）详解

声明文件（Declaration Files）是 TypeScript 的核心机制之一，用于为非 TypeScript 编写的代码（如纯 JavaScript 文件、第三方库、浏览器 API、全局变量等）提供类型信息。声明文件以.d.ts为后缀，只包含类型定义，不包含实现代码，编译后不会生成 JavaScript。

1. 为什么需要声明文件？

• JavaScript 库（如 jQuery、Lodash）没有类型信息。
• 浏览器内置 API（如document、window、fetch）是全局的。
• 项目中混用.js文件。
• 第三方 npm 包没有内置类型定义。

使用声明文件后，TypeScript 能在使用这些代码时提供智能提示、类型检查和错误提示。

2. 基本语法与结构

声明文件的核心关键字：

• declare：声明变量、函数、类、模块等存在（不实现）。
• module/namespace：组织全局或模块声明。
• interface/type：定义类型。
• export/import：模块化声明。

3. 常见声明类型

a. 全局变量/函数声明

// globals.d.tsdeclarevarmyGlobalVar:string;// 全局变量declarefunctionmyGlobalFunction(msg:string):void;declareclassGlobalClass{constructor(name:string);say():void;}declareconstBUILD_VERSION:string;// 全局常量

使用：

myGlobalFunction("hello");// 有类型提示

b. 全局命名空间声明（扩展现有对象）

// augmentations.d.tsdeclareglobal{interfaceWindow{myAppConfig:{apiUrl:string;debug:boolean;};}namespaceNodeJS{interfaceProcessEnv{NODE_ENV:"development"|"production";API_KEY:string;}}}// 使用window.myAppConfig.apiUrl;// 有提示process.env.API_KEY;// 类型安全

c. 模块声明（为 JS 模块提供类型）

// declarations/lodash.d.tsdeclaremodule"lodash"{exportfunctionchunk<T>(array:T[],size?:number):T[][];exportfunctiondebounce<TextendsFunction>(func:T,wait:number):T;// ... 其他函数exportdefault_;// 默认导出（如果库是 default）const_:any;}// 使用import_from"lodash";_.chunk([1,2,3,4],2);// 有类型提示

d. 为现有模块添加类型（Module Augmentation）

扩展第三方库（如 express）：

// types/express.d.tsimport"express";declaremodule"express-serve-static-core"{interfaceRequest{user?:{id:number;name:string;};}}// 使用 express 时app.use((req,res,next)=>{req.user?.name.toUpperCase();// 有提示，不报错});

4. DefinitelyTyped —— 社区类型定义

最常用的声明文件来源：@types 组织

安装：

npminstall--save-dev @types/lodashnpminstall--save-dev @types/jquerynpminstall--save-dev @types/node# Node.js 全局类型npminstall--save-dev @types/react

• 超过 10,000+ 个流行库的类型定义。
• 优先使用@types/xxx，避免自己写。

5. 创建自己的声明文件

示例：为一个 JS 文件提供类型

项目结构：

src/ utils.js // 纯 JavaScript utils.d.ts // 类型声明

// utils.jsmodule.exports={formatDate(date){returndate.toISOString();},capitalize(str){returnstr.charAt(0).toUpperCase()+str.slice(1);}};

// utils.d.tsexportfunctionformatDate(date:Date):string;exportfunctioncapitalize(str:string):string;

使用：

import*asutilsfrom"./utils";utils.capitalize("hello");// 有类型提示

示例：为第三方无类型库写声明

// declarations/my-lib.d.tsdeclaremodule"my-lib"{exportinterfaceOptions{timeout?:number;retries?:number;}exportfunctionrequest(url:string,options?:Options):Promise<string>;exportdefaultrequest;}

放在项目中任意位置，TS 会自动识别。

6. tsconfig.json 中的声明文件配置

{"compilerOptions":{"typeRoots":["./node_modules/@types","./types"],// 自定义类型目录"types":["node","lodash"]// 只加载指定 @types},"include":["src/**/*.ts","src/**/*.d.ts",// 包含自定义声明文件"types/**/*.d.ts"]}

7. 最佳实践建议

小结：声明文件类型速查

声明文件是 TypeScript 与 JavaScript 生态无缝衔接的桥梁。掌握它后，你可以安全地使用任何 JS 库，同时享受完整的类型支持。

如果您想看具体示例（如为 jQuery、Axios、或自定义 JS 项目写声明文件），或者如何发布自己的@types包，请告诉我！