JavaScript / TypeScript / 系统课时
声明文件
声明文件
当现有 JavaScript 模块没有类型信息时,TypeScript 无法可靠检查参数、返回值和导出成员。声明文件 .d.ts 用来描述这些已经存在的 API:它只声明“有什么类型”,不提供运行时实现。完成本课后,你可以为一个本地 JavaScript 模块补齐可被编译器识别的类型。
学习目标
- 理解
.d.ts与 JavaScript 实现文件的职责边界 - 为已有模块的函数参数、返回值和可选参数声明类型
- 通过 TypeScript 编译检查验证声明文件是否生效
声明文件解决什么问题
JavaScript 文件决定程序运行时真正执行什么;声明文件只给 TypeScript 编译器提供静态类型信息。两者可以同名并放在一起,例如 legacy-math.js 与 legacy-math.d.ts。当代码导入该模块时,编译器会读取声明来检查调用方式,而 Node.js 仍执行原来的 JavaScript。
在模块型 .d.ts 中,导出的函数、类和接口直接写 export 即可。声明文件本身已经处于声明上下文,不需要给每个导出重复添加 declare。相反,函数体、变量初始化和真实副作用都不应写进 .d.ts。
为现有 JavaScript API 补类型
假设项目里已有一个 CommonJS 模块 legacy-math.js,它提供加法和格式化两个函数:
function add(a, b) {
return a + b;
}
function format(value, prefix = "result") {
return `${prefix}: ${value}`;
}
module.exports = { add, format };为同一个模块创建 legacy-math.d.ts。类型签名必须与真实 API 的行为保持一致:
export function add(a: number, b: number): number;
export function format(value: number, prefix?: string): string;然后在 main.ts 中正常导入。此时编辑器补全、参数检查和返回值推断都会基于声明文件工作:
import { add, format } from "./legacy-math";
const total = add(2, 3);
console.log(format(total, "sum"));使用 TypeScript 编译 JavaScript 实现与 TypeScript 调用代码,再运行生成结果:
npx tsc --strict --allowJs --checkJs false --module commonjs --target ES2020 --outDir dist main.ts legacy-math.js && node dist/main.js预期输出:
sum: 5如果把 add(2, "3") 写进 main.ts,编译阶段会直接报参数类型错误;这正是声明文件带来的价值。错误中的文件位置可能因项目路径不同而变化。
全局声明与模块声明不要混用
如果 JavaScript 通过 <script> 暴露全局变量,可以在一个不含顶层 import 或 export 的 .d.ts 中使用 declare:
declare const APP_VERSION: string;
declare function legacyAlert(message: string): void;这种写法描述的是全局名字,不是可导入模块。对于通过 import 或 require 使用的库,应优先写模块声明或随包提供对应 .d.ts,避免把类型意外泄漏到全局作用域。
声明文件的关键边界
.d.ts 不是“把 JavaScript 再写一遍”。它应只暴露调用者真正需要的公共契约,并与实际运行时保持同步。参数是否可选、返回值是否可能为 undefined、对象属性是否只读,都必须按真实行为声明;过宽的 any 会让类型检查失去意义,过窄的声明则会制造虚假的编译错误。
发布 npm 包时,通常把声明文件随包一起发布,并通过 package.json 的 types 字段或标准文件结构让 TypeScript 找到它。为第三方包单独补类型时,也可以使用社区维护的 @types/* 包;只有在没有现成类型时,才需要自己编写声明。