如何用JSDoc扩展自定义HTMLElement的addEventListener事件类型文档

我正在实现一个自定义HTMLElement，希望通过JSDoc为其编写文档，以获取VS Code IntelliSense的智能提示功能——比如调用.addEventListener()时，VS Code会展示所有可用事件。我需要在不覆盖原有内置文档的前提下，仅为.addEventListener()的type参数新增可选事件类型，且未重写该方法。我尝试使用@name、@method和@memberof等标签，但均未生效，示例代码如下：

/**
 * @name addEventListener
 * @method
 * @memberof Puzzle
 * 
 * @param {keyof HTMLElementEventMap | PuzzleEventKeyMap} type
 */

要实现保留原生addEventListener文档的同时扩展事件类型提示，核心是通过扩展内置事件映射并将其关联到自定义元素类型，具体步骤如下：

1. 定义自定义事件映射 #

先明确你的自定义事件及其对应的事件对象类型：

/**
 * 自定义Puzzle元素的事件集合
 * @typedef {Object} PuzzleEventMap
 * @property {CustomEvent} puzzle-solved 拼图完成时触发，事件对象可携带完成耗时等数据
 * @property {CustomEvent} puzzle-reset 拼图重置时触发
 */

2. 关联自定义元素与扩展事件映射 #

在自定义元素的类注释中，通过@augments继承HTMLElement，同时通过类型交集扩展addEventListener的参数类型，让VS Code识别新增的事件：

/**
 * 自定义拼图元素
 * @augments {HTMLElement}
 * @this {HTMLElement & {
 *   addEventListener<K extends keyof (HTMLElementEventMap & PuzzleEventMap)>(
 *     type: K,
 *     listener: (this: Puzzle, ev: (HTMLElementEventMap & PuzzleEventMap)[K]) => any,
 *     options?: boolean | AddEventListenerOptions
 *   ): void;
 * }}
 */
class Puzzle extends HTMLElement {
  // 你的元素实现逻辑
}

customElements.define('puzzle-component', Puzzle);

3. 验证效果 #

当你在VS Code中调用puzzleInstance.addEventListener(时，会同时看到原生HTML事件（如click、input）和自定义的puzzle-solved、puzzle-reset事件，且原生方法的文档说明会被完整保留。

为什么之前的方法失效 #

你之前用@name+@memberof的方式，本质是试图重新定义一个方法，而非扩展原生方法的参数类型。VS Code无法将这种定义与原生addEventListener的文档关联，因此既不会保留原生提示，也无法正确识别新增类型。只有通过类型交集扩展事件映射并绑定到自定义元素的this类型上，才能实现需求。

内容的提问来源于stack exchange，提问作者Filinto Delgado