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,它提供加法和格式化两个函数:

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 的行为保持一致:

ts
export function add(a: number, b: number): number;
export function format(value: number, prefix?: string): string;

然后在 main.ts 中正常导入。此时编辑器补全、参数检查和返回值推断都会基于声明文件工作:

ts
import { add, format } from "./legacy-math";

const total = add(2, 3);
console.log(format(total, "sum"));

使用 TypeScript 编译 JavaScript 实现与 TypeScript 调用代码,再运行生成结果:

bash
npx tsc --strict --allowJs --checkJs false --module commonjs --target ES2020 --outDir dist main.ts legacy-math.js && node dist/main.js

预期输出:

text
sum: 5

如果把 add(2, "3") 写进 main.ts,编译阶段会直接报参数类型错误;这正是声明文件带来的价值。错误中的文件位置可能因项目路径不同而变化。

全局声明与模块声明不要混用

如果 JavaScript 通过 <script> 暴露全局变量,可以在一个不含顶层 import 或 export 的 .d.ts 中使用 declare:

ts
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/* 包;只有在没有现成类型时,才需要自己编写声明。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

声明文件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通