Shadow DOM 中原生事件的 event.target 会被重定向为宿主元素，导致外部监听无法获取内部真实目标；应使用 event.composedPath()[0] 或派发 composed: true 的自定义事件来解决。
为什么 document.addEventListener('click') 拿不到 Shadow DOM 里的 button 点击
不是监听器没绑上，是浏览器主动重定向了 event.target。Shadow DOM 的设计目标就是隔离，所以原生事件（如 click、input）穿过 Shadow Boundary 时，event.target 会被替换成宿主元素（比如 <my-button>），而不是内部真实的 <button>。
常见错误现象：
- 用
event.target === myButtonInner判断点击是否命中内部元素，永远为false - React ≤16 组件里绑了
onClick却不触发——因为 React 合成事件靠event.target分发，而它已被重定向 - 写了个通用点击埋点逻辑，结果在 Web Components 区域全部漏报
正确做法是放弃依赖 event.target，改用：
-
event.composedPath()[0]：始终返回最深的真实触发元素（哪怕嵌套多层 Shadow） - 在 Shadow 内部手动派发
composed: true的自定义事件，例如：element.dispatchEvent(new CustomEvent('ui-click', { bubbles: true, composed: true }))
如何安全地做 Shadow DOM 外部事件委托
不能靠 document.addEventListener('click', ...) 直接代理内部按钮，但可以绕过限制实现等效效果。关键不是“穿透原生事件”，而是用标准方式重建委托链。
立即学习“前端免费学习笔记（深入）”；
使用场景：
- 全局点击录制（如 AutoForm 录制用户操作）
- 第三方 SDK 注入 UI 后需监听其内部交互
- 不修改 Web Component 源码的前提下扩展行为
实操建议：
- 监听
document或容器节点的click，但处理逻辑必须基于event.composedPath()查找真实目标 - 避免遍历整个
composedPath()数组，通常只需取[0]或用.includes(myInternalElement)做存在判断 - 若需兼容 IE，此方案不可行（
composedPath不支持），只能退回到组件内部暴露事件或使用 MutationObserver 动态绑定 - 性能影响极小——
composedPath()是浏览器原生方法，Chrome 53+ / Firefox 63+ / Safari 10.1+ 均已优化
customEvent({ composed: true }) 是唯一可控的穿透方式
原生事件的 composed 属性是只读的，无法强行让 click 穿透。唯一可写的出口，是手动派发自定义事件，并显式设置 composed: true。
参数差异与陷阱：
-
bubbles: true必须同时设置，否则事件根本不会冒泡出 Shadow Root -
composed: true是关键开关，缺一则外部监听收不到 - 不要在宿主元素上直接写
onclick="..."——它拿到的是重定向后的 target，语义错乱 - 事件名别用
click、input等原生名，防止和原生事件混淆；推荐加前缀如my-click、form-submit
示例（Shadow 内部）：
const button = this.shadowRoot.querySelector('button');
button.addEventListener('click', () => {
this.dispatchEvent(new CustomEvent('my-button-click', {
bubbles: true,
composed: true,
detail: { value: 'confirmed' }
}));
});
外部监听完全无感：
document.addEventListener('my-button-click', e => {
console.log('真实触发来自 Shadow 内部:', e.detail.value);
});
React/Vue 项目里接入 Web Components 的注意事项
框架本身不感知 Shadow DOM 结构，所以不能指望 v-on:click 或 onClick 自动捕获内部元素事件。尤其旧版 React（≤16）会因 event.target 重定向彻底失效。
容易被忽略的细节：
- React 17+ 把事件代理从
document改到了 root 节点，缓解了问题，但若整个 React App 运行在 Shadow DOM 内（比如嵌在另一个 Web Component 中），仍需手动绑定 - Vue 3 的
v-on默认监听原生事件，对composed: true自定义事件也有效，但需确保事件名不被 Vue 编译器过滤（如带连字符的需用@['my-click']） - 如果 Web Component 是你维护的，优先在内部封装好语义化事件（如
change、submit），而不是暴露底层click细节 - 调试时别只看 DevTools 的 Elements 面板——
event.composedPath()返回的路径可能包含多个 Shadow Host，光看渲染树会误判
