如何为Shadow DOM添加keydown事件监听器？

问题描述 #

我正尝试为特定Web Component实现keydown事件监听器，该监听器需内置在组件中以便在其他项目复用。已实现的onclick监听器可正常触发——Shadow DOM和document层面的回调均会执行，但keydown事件却无响应，keyup和keypress事件也存在相同问题。

已知keydown事件具备composed = true属性，理应可正常使用，但始终无法触发Shadow DOM内的监听器。

示例代码如下：

<custom-template></custom-template>

<template id="custom-template">
  <button>Click me</button>
  <div>This is a div</div>
</template>

class CustomElement extends HTMLElement {
  constructor() {
    super();
    let template = document.getElementById("custom-template");

    this.attachShadow({ mode: "open" });
    this.shadowRoot.appendChild(template.content.cloneNode(true));
  }

  connectedCallback() {
    this.shadowRoot.addEventListener("click", (e) => {
      alert("click from shadow dom");
    });
    this.shadowRoot.addEventListener("keydown", (e) => {
      e.stopPropagation();
      alert("keydown from shadow dom"); // 不会执行
    });
  }
}

window.customElements.define("custom-template", CustomElement);

document.addEventListener("click", (e) => {
  alert(`click from document; composed: ${e.composed}`);
});

document.addEventListener("keydown", (e) => {
  alert(`keydown from document; composed: ${e.composed}`);
});

问题根源：焦点缺失 #

键盘事件（keydown/keyup/keypress）只会发送到当前拥有焦点的元素及其祖先节点。你的代码存在两个核心问题：

• 自定义元素<custom-template>本身默认不具备焦点能力（不属于focusable元素）
• Shadow DOM内的<button>虽然是focusable，但只有当用户点击它让它获得焦点后，键盘事件才会传递到它的祖先（包括shadowRoot）；如果焦点不在组件内的任何元素上，键盘事件不会触发shadowRoot的监听器。

解决方法 #

方案1：让自定义元素可聚焦 #

给自定义元素添加tabindex属性，使其能够获得焦点，这样当组件获得焦点时，键盘事件会传递到shadowRoot：

修改组件的connectedCallback方法：

connectedCallback() {
  // 让自定义元素可聚焦，tabindex=0表示按Tab键可正常聚焦
  this.setAttribute('tabindex', '0');
  
  this.shadowRoot.addEventListener("click", (e) => {
    alert("click from shadow dom");
  });
  this.shadowRoot.addEventListener("keydown", (e) => {
    alert("keydown from shadow dom");
  });
}

也可以直接在HTML中声明：

<custom-template tabindex="0"></custom-template>

用户可以通过Tab键聚焦到组件，也可以在代码中调用this.focus()主动获取焦点。

方案2：确保内部元素始终获得焦点 #

如果希望键盘事件只在内部特定元素（比如button）有焦点时触发，可以在组件挂载后主动让button获得焦点：

connectedCallback() {
  const button = this.shadowRoot.querySelector('button');
  button.focus(); // 页面加载后主动让button获得焦点
  
  this.shadowRoot.addEventListener("click", (e) => {
    alert("click from shadow dom");
  });
  this.shadowRoot.addEventListener("keydown", (e) => {
    alert("keydown from shadow dom");
  });
}

这样页面加载后button就持有焦点，键盘事件会正常触发shadowRoot的监听器。

方案3：全局监听并判断事件归属 #

如果需要全局监听键盘事件，但只处理组件内的情况，可以在document的keydown监听器中判断事件目标是否属于当前组件的Shadow DOM：

document.addEventListener("keydown", (e) => {
  if (this.shadowRoot.contains(e.target)) {
    alert("keydown from component shadow dom");
  }
});

这种方式更适合全局键盘快捷键的场景，不如前两种方案优雅。

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