CustomEvent 必须绑定到真实 DOM 节点才能生效，本质属于 DOM 事件系统；需确保派发与监听目标一致，推荐统一用 document 或共同父容器；bubbles 和 composed 参数决定冒泡与 Shadow DOM 穿透能力；detail 须为可结构化克隆对象；监听器必须手动清理以防内存泄漏。
CustomEvent 必须绑定到真实 DOM 节点才能生效
原生 CustomEvent 不是“发出去就自动被听见”的消息总线，它本质是 DOM 事件系统的一部分。如果你在 Vue/React 组件逻辑里直接写 dispatchEvent(new CustomEvent('xxx'))，但没指定目标节点（比如 document、某个 div 或自定义元素），事件根本不会进入事件流——监听器自然收不到。
常见错误现象：addEventListener('data-update', handler) 一直不触发，十有八九是派发和监听没对齐目标。比如监听加在 document，但事件却调用了 someRef.current.dispatchEvent(...)，而 someRef.current 又没挂载或不是有效节点。
- 统一用
document作中转站最稳妥：所有组件都通过document.dispatchEvent()发，用document.addEventListener()收 - 若需精确控制传播范围，选一个共同父容器（如
#app-root）作为目标，避免污染全局 - Web Components 内部可用
this.dispatchEvent()，前提是this是已挂载的自定义元素实例
bubbles 和 composed 参数决定能否穿透 Shadow DOM 和嵌套层级
默认情况下，CustomEvent 不冒泡，也不穿透 Shadow DOM 边界。这意味着：子组件在 Shadow DOM 里派发的事件，父组件若只监听 document，大概率收不到；兄弟组件之间也因 DOM 层级隔离而无法直连。
关键参数作用：
立即学习“前端免费学习笔记（深入）”；
-
bubbles: true→ 事件沿普通 DOM 树向上冒泡，允许祖先节点监听（如父容器监听子组件事件） -
composed: true→ 允许事件穿透 Shadow DOM 边界，是 Web Components 跨封装通信的必要开关 - 二者常一起用：
{ bubbles: true, composed: true }才能真正实现“跨层级 + 跨封装”
示例：new CustomEvent('form-submit', { detail: { values: {} }, bubbles: true, composed: true }) —— 这样，即使表单组件包裹在 Shadow DOM 中，外层布局组件也能捕获到。
detail 必须是可结构化克隆的对象，否则跨 iframe 或序列化会失败
detail 是 CustomEvent 唯一被规范允许携带数据的字段，但它有硬性限制：值必须能被浏览器的 structured clone algorithm 处理。传函数、Date、RegExp、Map、Set 或带循环引用的对象，都会静默失败或抛错。
- 安全做法：只传 plain object、array、string、number、boolean、null
- 需要传时间？用
new Date().toISOString()字符串代替Date实例 - 需要传 Blob 或 File？先转成 base64 或 URL（注意大小限制）
- Vue/React 中从响应式对象取值时，记得用
toRaw()或解构，避免传入 proxy 对象
监听器必须手动清理，否则组件卸载后仍响应事件
DOM 事件监听器不会随组件销毁自动移除。如果在组件挂载时加了 document.addEventListener('xxx', handler)，但没在卸载时调用 removeEventListener()，就会导致内存泄漏，甚至出现“旧组件逻辑被新数据触发”的诡异行为。
- Vue 2/3：在
beforeDestroy或onBeforeUnmount里清理 - React：在
useEffect的 cleanup 函数中移除，且确保 handler 是稳定引用（避免每次渲染生成新函数） - 纯 JS Web Component：在
disconnectedCallback中清理 - 别用匿名函数监听：
document.addEventListener('x', () => {...})→ 无法remove，必须用具名或变量引用的函数
复杂点在于：多个组件可能监听同一事件类型，但各自处理逻辑不同；一旦漏清一个，就可能干扰其他组件。这件事容易被忽略，但后果直接体现在稳定性上。
