使用索引签名时为何丢失TypeScript事件类型推断？

问题场景 #

正常调用addEventListener时，TypeScript编译器能根据事件类型自动推断处理函数的参数类型，比如keyup事件对应KeyboardEvent：

const foo = document.getElementById("foo");

if (foo !== null) {
  foo.addEventListener("keyup", (e) => {
    console.log("hey", e); // e被推断为KeyboardEvent
  });
}

但使用带联合类型的索引签名时，类型推断会失效：

interface DOMElements {
  [index: string]: HTMLElement | HTMLInputElement;
}

class Baz {
  $: DOMElements;

  constructor() {
    this.$ = {
      bar: document.getElementById("bar") as HTMLElement,
    };
  }
}

const baz = new Baz();

baz.$.bar.addEventListener("keyup", (e) => { 
  console.log("hey", e); // e被编译器识别为Event，而非KeyboardEvent
});

若显式指定参数类型为KeyboardEvent，会触发编译错误：

Argument of type '(e: KeyboardEvent) => void' is not assignable to parameter of type 'EventListenerOrEventListenerObject'.
Type '(e: KeyboardEvent) => void' is not assignable to type 'EventListener'.
Types of parameters 'e' and 'evt' are incompatible.
Type 'Event' is missing the following properties from type 'KeyboardEvent': altKey, charCode, code, ctrlKey, and 17 more.

tsconfig配置如下：

{
  "compilerOptions": {
    "target": "ESNext",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ESNext", "DOM"],
    "moduleResolution": "Node",
    "strict": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "noEmit": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

技术原因 #

1. 联合类型的方法签名合并规则：TypeScript对联合类型的方法调用，会取所有类型方法签名的交集。HTMLElement和HTMLInputElement的addEventListener虽然都支持keyup事件，但联合类型下，编译器会将方法参数类型收敛到所有可能类型的公共父类型——也就是通用的Event，而非具体的KeyboardEvent。因此回调函数只能接收Event类型，无法兼容更具体的KeyboardEvent。
2. 索引签名的类型覆盖：尽管构造函数中对document.getElementById("bar")做了HTMLElement的类型断言，但赋值给DOMElements类型的this.$.bar后，其类型被覆盖为HTMLElement | HTMLInputElement联合类型，精确的类型信息丢失，导致后续事件类型推断失效。

解决方案 #

方案1：使用精确接口定义（推荐） #

放弃索引签名，明确指定每个元素的具体类型，让编译器保留精确的类型信息：

interface DOMElements {
  bar: HTMLElement;
  // 可根据需求添加其他元素的精确类型，比如：input: HTMLInputElement;
}

class Baz {
  $: DOMElements;

  constructor() {
    this.$ = {
      bar: document.getElementById("bar") as HTMLElement,
    };
  }
}

const baz = new Baz();
baz.$.bar.addEventListener("keyup", (e) => {
  console.log("hey", e); // e自动推断为KeyboardEvent
});

方案2：类型缩小（Type Narrowing） #

通过类型守卫缩小元素的类型范围，恢复精确类型：

const barElement = baz.$.bar;
// 使用instanceof做类型守卫
if (barElement instanceof HTMLElement) {
  barElement.addEventListener("keyup", (e) => {
    console.log("hey", e); // e推断为KeyboardEvent
  });
}

方案3：泛型类保留动态类型 #

如果需要动态管理元素集合，用泛型来保留每个元素的具体类型：

class Baz<T extends Record<string, HTMLElement | HTMLInputElement>> {
  $: T;

  constructor(elements: T) {
    this.$ = elements;
  }
}

const baz = new Baz({
  bar: document.getElementById("bar") as HTMLElement,
});

baz.$.bar.addEventListener("keyup", (e) => {
  console.log("hey", e); // e推断为KeyboardEvent
});

方案4：显式类型断言（不推荐） #

若以上方案无法适用，可在调用时临时断言元素类型，但会跳过类型检查，存在风险：

(baz.$.bar as HTMLElement).addEventListener("keyup", (e: KeyboardEvent) => {
  console.log("hey", e);
});

内容的提问来源于stack exchange，提问作者Preston Bourne