JavaScript / TypeScript / 系统课时

读取声明文件

读取声明文件

声明文件让 TypeScript 在不读取 JavaScript 实现细节的情况下理解一个 API。会读 .d.ts 后,你就能快速判断模块导出了什么、参数和返回值是什么、类型从哪里进入项目,并区分“类型检查通过”和“运行时真的存在实现”这两件事。

学习目标

  • 区分 JavaScript 实现、TypeScript 源码与 .d.ts 类型声明的职责
  • 从导出、参数、可选属性和返回类型读取 API 契约
  • 找到第三方包实际使用的声明入口并验证类型检查

把声明文件当作类型契约

.d.ts 只描述值和类型“长什么样”,不包含可执行实现,也不会单独生成 JavaScript。对于 TypeScript 库,编译器可以从 .ts 同时产出运行时 .js 和供使用者检查的 .d.ts;对于 JavaScript 库,也可以手写或额外生成声明文件来补充类型信息。

源码、声明文件与运行时产物的关系

因此,看到一个库有完整自动补全,只能说明编辑器找到了类型契约;真正运行时,仍必须有对应 JavaScript 实现或其他运行时提供的值。

从导出入口读取 API

下面的 formatter.d.ts 是一个最小声明文件。它没有函数体,但已经足够让 TypeScript 检查调用方式。

ts
export interface FormatOptions {
  uppercase?: boolean;
  prefix?: string;
}

export function format(
  value: string,
  options?: FormatOptions
): string;

export const version: string;

阅读时先看顶层 export,它决定模块对外暴露哪些名字;再看函数参数和返回类型。options? 表示整个参数可省略,接口中的 uppercase? 与 prefix? 表示这些属性可选。version: string 只声明这个值存在且类型为字符串,并没有为它赋值。

如果声明文件中出现同名函数的多条签名,通常是在描述重载;如果出现 declare,含义是“这个值由别处提供实现”。判断一个名字能否直接导入,仍应以它是否位于模块导出结构中为准。

用消费端验证理解

把上面的声明保存为 formatter.d.ts,再创建一个只做类型检查的消费文件。这里导入 ./formatter.js,TypeScript 在解析时可以通过扩展名替换找到同名声明文件。

ts
import { format, version } from "./formatter.js";

const message = format("hello", {
  uppercase: true,
  prefix: "TS"
});

console.log(version, message);

执行类型检查:

bash
npx tsc consumer.ts --noEmit --strict --module nodenext && echo "typecheck ok"

预期输出:

text
typecheck ok

这次验证只证明调用符合声明,不会执行 console.log,因为 --noEmit 不生成 JavaScript,而且示例没有提供 formatter.js 的运行时实现。若把 format("hello") 改成 format(42),编译器会在参数处报告类型不匹配,这正是声明文件提供的约束。

找到第三方库的声明入口

读取真实依赖时,不要从 node_modules 里随便挑一个 .d.ts。先从你实际写下的导入路径出发,再查看包的 package.json。库可能通过顶层 types 指向声明入口,也可能在 exports 的不同子路径中分别指定类型文件。

json
{
  "name": "formatter",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  }
}

这表示根入口的运行时代码与类型声明是两份不同文件。若库自身没有携带类型,常见做法是安装对应的 @types 包;TypeScript 还会自动加载标准 JavaScript 与所选运行环境相关的内置声明。

警惕声明与实现不一致

声明文件本质上是一份契约,因此它也可能写错。某个函数即使在 .d.ts 中存在,如果实际 .js 没有导出它,类型检查仍可能通过而运行时失败。排查第三方库问题时,应把“声明文件说什么”和“包实际导出什么”分开验证。

读声明文件时始终沿着“导入路径 → 包入口 → .d.ts 导出 → 具体签名”追踪,就能判断编辑器看到的类型来自哪里,也能在类型世界与运行时世界不一致时更快定位问题。

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

目录与阅读设置

阅读设置

17

记录一个想法

读取声明文件

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

登录哪都通