在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

microsoft/TypeScript

菜单

标准库定义

相关源文件

本文档描述了 TypeScript 如何实现 ECMAScript 标准库定义。这些定义提供了 JavaScript 语言规范中内置的 JavaScript 对象、函数和方法的类型信息。TypeScript 的类型系统依靠这些定义来为标准语言特性提供准确的类型检查。

库的组织和结构

TypeScript 的标准库定义根据 ECMAScript 版本和功能集被组织在不同的文件中。这种组织方式允许 TypeScript 支持不同的目标环境和 JavaScript 版本。

库文件层级结构

来源

基础库：ES5

ES5 库（es5.d.ts）构成了 TypeScript 标准库定义的基础。它为 ES5 中所有核心 JavaScript 功能提供了类型定义，包括：

  • 基本类型（Boolean、Number、String 等）
  • 核心对象（Object、Array、Function 等）
  • 全局函数（eval、parseInt、parseFloat 等）
  • 基本接口和类型（PropertyDescriptor、PropertyKey 等）

来源

核心 ES2015 扩展

ES2015 核心库（es2015.core.d.ts）通过 ES2015 (ES6) 功能扩展了基础 ES5 库，作用于现有类型。它为 Array、String、Number 和其他现有对象添加了新方法。

主要新增功能包括：

  • 数组方法，如 find()、findIndex() 和 fill()
  • 字符串方法，如 startsWith()、endsWith() 和 includes()
  • Number 扩展，如 EPSILON、isNaN() 和 isFinite()
  • 对象方法，如 assign() 和 is()

来源

Symbol和Well-Known Symbols

ES2015 引入了 Symbol 原始类型和一组 Well-Known Symbols。TypeScript 在两个文件中表示这些内容：

  1. es2015.symbol.d.ts：定义 Symbol 类型和构造函数。
  2. es2015.symbol.wellknown.d.ts：定义 Well-Known Symbols，如 Symbol.iterator、Symbol.hasInstance 等。

Well-Known Symbols 用于在特定的语言构造中控制对象的行为，例如迭代、方法解析和转换操作。

来源

集合和迭代器

ES2015 引入了新的集合类型和迭代协议。

  1. es2015.collection.d.ts：定义 Map、Set、WeakMap 和 WeakSet。
  2. es2015.iterable.d.ts：定义与迭代相关的接口，并为现有类型添加迭代功能。

迭代协议尤其重要，因为它支持 for...of 循环和展开语法。Symbol.iterator 属性用于定义对象如何被迭代。

来源

其他 ES2015 特性

其他重要的 ES2015 特性也包含在专门的库文件中。

  1. es2015.proxy.d.ts：定义用于元编程的 Proxy 对象。
  2. es2015.reflect.d.ts：定义用于反射操作的 Reflect 对象。

来源

后续 ECMAScript 增补

TypeScript 还包含了后续 ECMAScript 版本中新增功能的库。

  1. es2019.object.d.ts：添加了 Object.fromEntries() 方法。
  2. es2020.bigint.d.ts：添加了 BigInt 原始类型和相关功能。

来源

实现细节

声明合并和接口扩展

TypeScript 使用声明合并和接口扩展来跨文件构建库定义。例如，Object 接口最初在 es5.d.ts 中定义，然后在其他各种库文件中扩展，以添加较新的方法。

ES5 和 ES2015 中 Object 接口的定义和扩展方式如下：

在 ES5 中

在 ES2015 中

通过声明合并，TypeScript 将这些接口组合起来，创建 Object 类型的完整表示，其中包含了 ES5 和 ES2015 的所有方法。

来源

类型安全特性

TypeScript 通过以下附加类型安全特性增强了标准库定义：

  1. 泛型类型：广泛用于处理集合和能处理不同类型的函数。
  2. 联合类型：用于表示可以为不同类型的值。
  3. 函数重载：为根据参数表现不同而行为不同的函数提供精确的类型定义。
  4. Readonly 类型：指示不变性，尤其是在使用 Object.freeze() 等方法后。

例如，Object.freeze() 被类型化为返回 Readonly<T> 类型，从而确保被冻结的对象被正确地作为不可变对象进行类型化。

来源

库选择

在编译 TypeScript 代码时，您可以使用 lib 编译器选项来指定要包含的库定义。这允许您定位特定的 JavaScript 环境和版本。

例如

  • 带 ES5 的浏览器："lib": ["dom", "es5"]
  • 带 ES2015 的 Node.js："lib": ["es2015"]
  • 带 ES2020 的现代浏览器："lib": ["dom", "es2020"]

如果未指定 lib，TypeScript 编译器将根据 target 选项自动选择合适的库定义。

核心类型定义

标准库对象层级结构

来源

实际用法和示例

内置方法的类型安全

TypeScript 的标准库定义为内置方法提供了强类型，确保了正确使用。

来源

集合类型安全

标准库为集合提供了类型安全的定义。

Symbol 用法

Well-known Symbols 使自定义对象行为成为可能。

来源

结论

TypeScript 的标准库定义提供了 JavaScript 内置功能的全面类型信息，涵盖了各种 ECMAScript 版本。这些定义被组织成模块化文件，允许开发者针对特定的 JavaScript 环境和语言版本。通过声明合并和接口扩展，TypeScript 构建了对 JavaScript 标准库的完整而准确的表示，从而实现了强大的类型检查和改进的开发者体验。

库定义会不断更新，以反映新的 ECMAScript 功能和规范，确保 TypeScript 与最新的 JavaScript 发展保持兼容。