源码解析：深入理解 Shadow DOM 与事件穿透

最新推荐文章于 2026-06-25 10:26:00 发布

原创最新推荐文章于 2026-06-25 10:26:00 发布 · 550 阅读

10 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#javascript #前端 #react.js

引言

在开发 AutoForm SDK 的过程中，我们大量使用了 Shadow DOM 来实现样式隔离。然而，Shadow DOM 在带来隔离便利的同时，也给事件处理带来了巨大的挑战。

很多开发者在使用 Web Component 时会遇到这样的问题：

“为什么我在 document 上监听不到组件内部的点击事件？”
“为什么 React 的合成事件在 Shadow DOM 中失效了？”

本文将从源码角度，深入解析 Shadow DOM 的事件机制及 AutoForm 的解决方案。

Shadow DOM 的事件重定向（Retargeting）

当事件从 Shadow DOM 内部冒泡出来时，为了封装性，浏览器会对事件目标（event.target）进行重定向。

现象：
假设结构为：<my-button>#shadow-root <button>Click Me</button></my-button>

在 Shadow DOM 内部监听，target 是 <button>。
在外部 document 监听，target 变成了 <my-button>。

源码原理：
浏览器在冒泡过程中，会检查事件是否跨越了 Shadow Boundary。如果是，它会将 target 修正为该 Shadow Root 的宿主元素（Host）。

遇到的坑：React 合成事件失效

React 16 及更早版本将所有事件代理到 document 上。由于事件重定向，React 接收到的 target 是宿主元素（<my-button>），而不是真正的触发元素（<button>）。这导致 React 无法正确分发事件，组件内部的 onClick 根本不会触发。

AutoForm 的解决方案：

虽然 AutoForm 内部使用 Svelte，但我们需要支持宿主页面是 React 的情况。如果我们的 SDK 注入了一些 UI 到页面中，必须确保不破坏 React 的事件系统。

对于 React 17+，它将事件代理到了 Root 节点，情况有所好转，但如果 React 应用本身运行在 Shadow DOM 内，依然需要特殊处理。

我们采用了 composed: true 的自定义事件来主动通知外部：

// 在 Shadow DOM 内部
element.dispatchEvent(new CustomEvent('my-click', {
  bubbles: true,
  composed: true, // 关键：允许穿透 Shadow Boundary
  detail: { originalTarget: element }
}));

深度穿透：composedPath()

有时候我们需要知道事件的真实路径，即使它被重定向了。这时 event.composedPath() 就派上用场了。

document.addEventListener('click', (e) => {
  const path = e.composedPath();
  // path[0] 就是最底层的真实元素，即使它在 Shadow DOM 深处
  console.log('真实点击元素:', path[0]);
});