DOM 和 Web API 定义

相关源文件

• src/lib/dom.generated.d.ts
• src/lib/dom.iterable.generated.d.ts
• src/lib/webworker.generated.d.ts
• src/lib/webworker.iterable.generated.d.ts
• tests/baselines/reference/baseCheck.errors.txt
• tests/baselines/reference/expressionTypeNodeShouldError.types
• tests/baselines/reference/extendArray.errors.txt
• tests/baselines/reference/globalThisBlockscopedProperties.types
• tests/baselines/reference/intersectionsOfLargeUnions.types
• tests/baselines/reference/intersectionsOfLargeUnions2.errors.txt
• tests/baselines/reference/intersectionsOfLargeUnions2.types
• tests/baselines/reference/jsxFactoryIdentifierWithAbsentParameter.errors.txt
• tests/baselines/reference/jsxFactoryQualifiedNameResolutionError.errors.txt
• tests/baselines/reference/mappedTypeRecursiveInference.errors.txt
• tests/baselines/reference/mappedTypeRecursiveInference.types
• tests/baselines/reference/modularizeLibrary_Dom.iterable.symbols
• tests/baselines/reference/modularizeLibrary_Dom.iterable.types
• tests/baselines/reference/multiExtendsSplitInterfaces1.symbols
• tests/baselines/reference/parserOverloadOnConstants1.types

本文档介绍了 TypeScript 如何管理 DOM 和 Web API 接口的类型定义。这些定义为浏览器中的 TypeScript JavaScript 提供了类型检查和 IntelliSense。有关 ECMAScript 标准库定义的信息，请参阅标准库定义。

概述

TypeScript 包含全面的浏览器 API 类型定义，主要分为：

1. DOM API - 用于 HTML 文档操作的接口
2. Web Worker API - 用于后台线程的接口
3. 可迭代扩展 - 为 DOM 和 Web Worker 环境提供额外的迭代器支持

这些定义允许 TypeScript 为浏览器 JavaScript 提供强类型，而无需开发人员包含其他定义文件。

定义文件结构

DOM 和 Web API 定义分布在四个主要生成文件中：

文件	目的
dom.generated.d.ts	核心 DOM 接口和 Window API
webworker.generated.d.ts	Worker 特定的接口
dom.iterable.generated.d.ts	DOM 的迭代协议扩展
webworker.iterable.generated.d.ts	Worker 的迭代协议扩展

DOM 类型定义

dom.generated.d.ts 文件包含数千个接口定义，代表浏览器对象和 API，包括：

• HTML 元素接口 (HTMLDivElement, HTMLCanvasElement, 等)
• 事件接口 (MouseEvent, KeyboardEvent, 等)
• 核心 DOM 对象 (Document, Element, Node, 等)
• Window/全局 API (fetch, setTimeout, 等)
• Web API 接口 (WebGL, Audio API, Crypto, 等)

来源: src/lib/dom.generated.d.ts1-1067 这些定义允许 TypeScript 在与 DOM 交互时提供适当的类型。

Web Worker API 定义

Worker 环境的全局作用域与浏览器窗口上下文不同。webworker.generated.d.ts 文件定义了 Web Worker 特有的接口，以及在两种上下文中都存在但可能实现不同的共享接口。

来源: src/lib/webworker.generated.d.ts1-80 src/lib/webworker.generated.d.ts984-988

可迭代扩展

现代 DOM 和 Worker API 通常实现迭代协议。另外两个文件提供了这些可迭代接口：

• dom.iterable.generated.d.ts - 为 DOM 集合添加迭代功能
• webworker.iterable.generated.d.ts - 为 Worker 集合添加迭代功能

例如，NodeList 和 HTMLCollection 对象可以直接使用 for...of 循环进行迭代。

来源: src/lib/dom.iterable.generated.d.ts118-132 src/lib/dom.iterable.generated.d.ts228-246

架构和组织

DOM 和 Web API 类型层次结构

来源: src/lib/dom.generated.d.ts4-5210

类型定义组织模式

来源: src/lib/dom.generated.d.ts80-120 src/lib/dom.generated.d.ts575-599

关键接口类型模式

TypeScript 的 DOM 定义遵循一致的模式：

1. 基础接口 - 像 EventTarget、Node 和 Element 这样的基础接口。
2. 专用 DOM 接口 - 像 HTMLDivElement 这样的特定 HTML 元素。
3. 事件接口 - 事件及其初始化对象（*Event 和 *EventInit）。
4. Web API 接口 - 现代浏览器 API（WebGL、Audio、Fetch 等）。
5. 配置对象 - 传递给 API 方法的选项对象。

TypeScript 还通过专用泛型集合提供上下文类型，例如：

这使得 TypeScript 能够正确地为特定 HTML 元素的集合提供类型。

来源: src/lib/dom.iterable.generated.d.ts121-124 tests/baselines/reference/modularizeLibrary_Dom.iterable.types7-11

将字符串字面量映射到元素类型

TypeScript DOM 定义的一个关键特性是使用映射类型将字符串标签名与其对应的元素接口关联起来。

当使用字符串字面量（如 createElement）与 DOM 方法一起使用时，TypeScript 会使用这些映射来提供正确的特定元素类型，而不是通用的 HTMLElement 类型。

来源: tests/baselines/reference/modularizeLibrary_Dom.iterable.types4-15 tests/baselines/reference/parserOverloadOnConstants1.types5-27

特殊注意事项

TypeScript DOM 与运行时 DOM

需要注意的是，TypeScript 的 DOM 定义代表了浏览器 API 的理想化模型，可能不完全匹配每个浏览器的实现。主要考虑因素包括：

1. TypeScript 定义旨在根据规范表示标准 API。
2. 特定于浏览器的扩展可能未被完全表示。
3. 较新的 API 可能在普遍支持之前就被包含在内。

在不同浏览器环境中工作

TypeScript 允许开发人员通过 lib 编译器选项来定位不同的 DOM 环境。

这会选择包含哪些定义文件，从而实现精确的环境定位。

扩展 DOM 定义

当浏览器引入新 API 或开发人员需要增强现有接口时，TypeScript 提供了接口合并功能。

这使得在保持类型安全的同时，可以扩展内置的 DOM 定义。

来源: tests/baselines/reference/intersectionsOfLargeUnions2.ts16-19

与其他类型系统的关系

DOM 和 Web API 类型定义与 TypeScript 类型系统的其他部分进行交互。

1. 它们建立在 string、number 等原始类型之上。
2. 它们利用泛型类型来处理集合（数组、映射）。
3. 它们利用 TypeScript 的联合类型和交叉类型来处理复杂的 API。
4. 它们包含标准 ECMAScript 类型（例如，Promise、Map、Set）。

来源: tests/baselines/reference/globalThisBlockscopedProperties.types74-106 src/lib/dom.generated.d.ts1-100

结论

TypeScript 的 DOM 和 Web API 类型定义为类型安全的浏览器开发提供了重要的基础。接口定义系统模仿了浏览器的对象模型，为 Web 应用程序提供了准确的类型检查。通过将 TypeScript 与这些定义结合使用，开发人员在处理浏览器 API 时可以获得 IntelliSense、错误检测和改进的代码质量。