读懂 DOM 声明:事件名如何决定回调类型
阅读 addEventListener 的真实声明,追踪字面量、联合和 string 怎样影响事件类型与安全访问。
本章目录CONTENTS ↓
注册点击事件时,回调需要读取指针坐标;注册键盘事件时,回调需要读取按键。一个易用的事件 API 应根据事件名提供对应的事件类型,同时允许动态字符串和自定义事件名。
这两个要求之间存在取舍:名称越具体,编译器越容易确定事件类型;允许的名称越宽泛,声明就越难保证事件对象具有哪些专属属性。DOM 的 addEventListener 用事件映射、泛型和重载共同表达这份契约。
从使用需求读到真实声明
本章把前面自定义事件表的推导放到真实库声明中核对:先看一个较宽签名会丢掉什么,再定位实际声明中保存名称、读取载荷和接受宽泛名称的三个位置。
假设只有一个接收任意字符串的签名:
declare function listenBasic( type: string, listener: (ev: Event) => void): void;这个声明没有连接事件名与事件对象的具体类型。即使传入 "click",回调仍只得到基础的 Event,无法直接访问指针坐标 clientX。也可以为每个事件分别写重载,但事件多了,签名会反复描述相同结构。事件映射表可以集中保存这组对应关系。
以下内容以 TypeScript 6.0.3 的 DOM 声明 为准。GlobalEventHandlersEventMap 中,click 对应 PointerEvent,keydown 对应 KeyboardEvent;HTMLElementEventMap 通过继承获得这些成员。只提取本章需要的两项,可以写成:
type RelevantEvents = Pick<HTMLElementEventMap, "click" | "keydown">;// { click: PointerEvent; keydown: KeyboardEvent }真实的 HTMLElement 包含下面两条方法签名。为单独展示,将它们摘录到一个接口中:
interface HTMLElementListenerDeclaration { addEventListener<K extends keyof HTMLElementEventMap>( type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions ): void;
addEventListener( type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions ): void;}阅读时先抓住三个位置:第一个参数的 K、回调参数的 HTMLElementEventMap[K],以及另一条签名中的一般 string。其余部分可以按需查阅:this: HTMLElement 是回调的 this 类型标注,不占一个实参位置;options 配置监听行为;第二条签名也允许提供具有 handleEvent 方法的对象。本章只分析直接传入箭头函数的调用,该后备签名给回调提供 Event 参数。
这两条签名描述同一个浏览器方法允许怎样被调用,没有创建两个运行时方法。以下比较用于解释当前契约的收益与成本,不是对这份声明历史动机的叙述。
字面量调用:让一个键连接两个位置
const el: HTMLElement = document.createElement("button");
el.addEventListener("click", ev => { console.log(ev.type); // string console.log(ev.clientX); // number // @ts-expect-error PointerEvent 没有 key 属性 console.log(ev.key);});这次调用使用泛型事件名重载。事件名实参是 "click",本例推导出的 K 也是 "click";它满足事件键约束。随后把这个 K 代入回调参数类型:
type ClickEvent = HTMLElementEventMap["click"]; // PointerEvent因此回调的 ev 从期望签名获得 PointerEvent 类型,无需再次标注。约束限定 K 可以取哪些键,推导确定本次调用具体取哪个类型,索引访问读取它对应的事件类型。 约束不是本次推导结果,不会迫使每次 K 都成为所有事件名的联合。
事件映射是编译时的类型描述。HTMLElementEventMap[K] 不会生成一个运行时查表操作,也不会把普通事件对象转换成指针事件;事件的创建与分发仍由浏览器及应用代码负责。
联合调用:回调必须处理全部候选
事件名可能来自一次运行时选择:
const eventName = Math.random() > 0.5 ? "click" : "keydown";
el.addEventListener(eventName, ev => { console.log(ev.type); // @ts-expect-error KeyboardEvent 不保证 clientX console.log(ev.clientX); // @ts-expect-error PointerEvent 不保证 key console.log(ev.key);});调用处的事件名类型是 "click" | "keydown",这两个键都合法,因此仍使用泛型重载。K 保存这个联合,索引结果随之成为两个事件类型的联合:
type SelectedEvent = HTMLElementEventMap["click" | "keydown"];// PointerEvent | KeyboardEvent注册时实际选择了哪种事件,运行时会确定;编译器在此处只知道两种可能。未收窄的回调必须适用于全部候选,因此可以访问共有的 type,不能直接依赖某一成员独有的 clientX 或 key。
检查事件对象本身,就能安全地分支处理:
el.addEventListener(eventName, ev => { if ("clientX" in ev) { console.log(ev.clientX); // ev: PointerEvent } else { console.log(ev.key); // ev: KeyboardEvent }});本例联合只有 PointerEvent 与 KeyboardEvent,前者声明了必填的 clientX,后者没有声明这个属性,所以 in 检查能区分它们。使用 else if ("key" in ev) 也合法,只是在当前候选范围内不必再检查一次。若联合加入其他成员,或用于区分的属性变为可选,就需要重新检查各分支的类型,不能照搬这个简化。
DOM 事件的 type 属性在这里是一般 string,并未声明成各成员不同的字面量。因此,比较 ev.type 的值,也不能直接获得判别联合那样的收窄:
el.addEventListener(eventName, ev => { if (ev.type === "keydown") { // @ts-expect-error type: string 不能区分这两个事件子类型 console.log(ev.key); }});能否联动收窄,取决于类型是否表达了成员之间的差别。自己设计事件模型时,可以在每个成员中使用不同的字面量判别字段;相关机制见事件 API。
一般 string:使用后备重载,保留基础保证
const unknownName: string = "click";
el.addEventListener(unknownName, ev => { console.log(ev.type); // ev: Event // @ts-expect-error Event 不保证 clientX console.log(ev.clientX); // @ts-expect-error Event 不保证 key console.log(ev.key);});变量的初始化值虽然是 "click",但显式标注的静态类型是一般 string。const 禁止重新赋值,不会把这个类型标注自动改成字面量。一般 string 包含映射表以外的名称,无法满足有限事件键的约束,所以这个调用使用 string 后备重载,回调得到 Event。
这里的限制不是“只有单个字面量能用于索引”。合法键的联合、keyof,以及受约束的泛型参数,都可以作为索引:
type EventAt<K extends keyof HTMLElementEventMap> = HTMLElementEventMap[K];type EitherEvent = EventAt<"click" | "keydown">;type AnyKnownEvent = EventAt<keyof HTMLElementEventMap>;
// @ts-expect-error 这个映射没有接受任意字符串的索引签名type ArbitraryEvent = HTMLElementEventMap[string];关键是索引所代表的键是否被目标类型支持。有字符串索引签名的其他类型可以支持一般 string,不能把这个 DOM 事件表的边界推广到所有对象类型。
从调用差异看 API 的取舍
| 事件名的静态类型 | 本例使用的重载 | 回调参数类型 | 未收窄时可访问 |
|---|---|---|---|
“click” | 泛型事件名重载 | PointerEvent | type、clientX |
“click” | “keydown” | 泛型事件名重载 | PointerEvent | KeyboardEvent | type |
string | string 后备重载 | Event | type |
事件映射与泛型统一表达已知事件的关系;后备重载允许动态字符串和自定义名称,代价是失去专属事件类型的保证。它也会接受拼错的名称:
el.addEventListener("clcik", ev => { console.log(ev.type); // 通过 string 重载,ev 为 Event});如果业务 API 的事件集合是封闭的,可以只提供受约束的泛型签名,让未知名称立即报错;如果必须支持开放名称,就需要决定这些名称能获得什么基础保证,以及是否提供独立的注册入口。这里读懂的是 DOM 这组具体重载,不应据此假定所有 API 都会自动提供后备签名。
设计自己的 API 时,还需要决定如何表达输入与输出的关系。普通联合、逐项重载和泛型条件返回各有适用范围;泛型与类型关联中的设计对比以单个与批量输入说明返回精度、联合实参许可和实现成本。
读一个类似声明时,可以沿同一条线追踪:实参的静态类型 → 可用重载 → 泛型参数 → 索引结果 → 回调可以安全执行的操作。声明描述编译时契约,并不验证应用手动创建或外部传入的任意运行时事件。
本章代码以 TypeScript 6.0.3、strict 和 DOM 类型库核对;它们展示静态检查结果,不构成浏览器事件逻辑的运行测试。遇到 click 事件类型与这里不同的项目,应先检查项目实际安装的 TypeScript 版本及其 lib.dom.d.ts。
官方查阅入口:Generics、Indexed Access Types、Function Overloads、The in operator narrowing。回查泛型关联与函数兼容性,或返回全景路线。
这一页,先记到这里。