TypeScript中传递键值对调用addEventListener的类型错误问题咨询

你编写了一个为DOM元素批量添加事件监听的函数：

function addListeners(el: HTMLElement, listeners: { [key in keyof HTMLElementEventMap]: Function }) {
  if (listeners) {
    for (const [key, value] of Object.entries(listeners)) {
      el.addEventListener(key, value);
    }
  }
}

但TypeScript抛出以下两个错误（已翻译为中文）：

没有匹配此调用的重载。
第1个重载（共2个）：(type: keyof HTMLElementEventMap, listener: (this: HTMLElement, ev: Event | ClipboardEvent | UIEvent | AnimationEvent | MouseEvent | ... 还有13种... | WheelEvent) => any, options?: boolean | ... 还有1种... | undefined): void，报错如下：
参数类型“string”无法赋值给类型“keyof HTMLElementEventMap”。
第2个重载（共2个）：(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions | undefined): void，报错如下：
参数类型“Function”无法赋值给类型“EventListenerOrEventListenerObject”。

下面分别分析错误原因并给出修复方案：

错误1：string 类型不匹配 keyof HTMLElementEventMap #

Object.entries() 默认会把对象的键推断为宽泛的string类型，但addEventListener的第一个参数要求是精确的事件类型（即keyof HTMLElementEventMap）。TypeScript无法自动把string缩小到特定的事件类型集合，所以需要手动进行类型断言。

错误2：Function 类型不符合事件回调要求 #

Function是最宽泛的函数类型，没有指定回调函数的上下文（this）和事件参数类型，而addEventListener要求的是符合对应事件规范的回调函数（EventListenerOrEventListenerObject的子集）。我们需要把listeners的值类型约束为对应事件的强类型回调。

修正后的完整代码 #

function addListeners(el: HTMLElement, listeners: Partial<{ [K in keyof HTMLElementEventMap]: (this: HTMLElement, ev: HTMLElementEventMap[K]) => void }>) {
  if (!listeners) return;
  
  // 对Object.entries的结果进行类型断言，明确键为合法事件类型
  for (const [eventType, handler] of Object.entries(listeners) as [keyof HTMLElementEventMap, typeof listeners[keyof HTMLElementEventMap]][]) {
    el.addEventListener(eventType, handler);
  }
}

关键改动说明 #

1. 精确的类型约束：
   • 用Partial<{ [K in keyof HTMLElementEventMap]: (this: HTMLElement, ev: HTMLElementEventMap[K]) => void }>定义listeners类型：
     • Partial允许只传入部分事件类型，不用强制传所有事件的回调；
     • 每个回调函数都明确了this指向当前HTMLElement，以及事件参数的具体类型（比如click事件对应MouseEvent），完全符合addEventListener的要求。
2. 修复键的类型推断：
   • 通过as [keyof HTMLElementEventMap, typeof listeners[keyof HTMLElementEventMap]][]对Object.entries的结果断言，让TypeScript识别遍历的键都是合法的DOM事件类型，解决类型不匹配问题。

这样修改后，TypeScript的类型检查会通过，同时保留了类型安全性，能在编译期就发现事件类型或回调参数的错误。

内容的提问来源于stack exchange，提问作者Edgar Derby