CustomEvent 是浏览器原生事件构造器，用于在任意 DOM 节点触发带数据的自定义事件，支持松耦合通信；需通过 detail 传可结构化克隆的数据，配合 bubbles/composed 实现跨 Shadow DOM 通信，并注意框架中手动监听与清理。
CustomEvent 是浏览器原生提供的事件构造器，可用于在任意 DOM 节点（包括自定义元素、Shadow DOM、甚至 window）上触发带数据的自定义事件，实现松耦合的跨组件通信。它不依赖框架，轻量、标准、可序列化，适合微前端、Web Components 或纯 JS 组件体系中的事件驱动协作。
创建并派发带负载的 CustomEvent
使用 new CustomEvent(type, options) 构造事件，其中 detail 字段是唯一被规范允许携带任意结构化数据的位置（支持对象、数组、字符串、数字、布尔、null，但不可传函数或 DOM 节点）。派发时调用 dispatchEvent()：
- 确保 detail 值是可结构化克隆（structured clone）的对象——避免循环引用、RegExp、Date 等非序列化类型（若需传 Date，可转为 ISO 字符串）
- 推荐将 detail 设计为 plain object，含 type、payload、meta 等字段，便于监听方统一解析
- 派发目标应明确：可选 document、window、某个父容器、或组件根节点；避免全局 dispatch 到 window 造成污染
示例：
const event = new CustomEvent('user-login', {detail: { id: 123, name: 'Alice', roles: ['admin'] },
bubbles: true,
cancelable: false
});
document.getElementById('app-root').dispatchEvent(event);
在目标组件中监听与响应事件
监听使用 addEventListener(type, handler)，handler 接收 Event 对象，其 event.detail 即为传递的数据。注意：
- 监听节点必须是派发路径上的祖先节点（若 bubbles: true），或直接目标节点（若 bubbles: false）
- 建议在组件挂载时添加监听，卸载时用 removeEventListener 清理，防止内存泄漏
- 可在 handler 中做数据校验（如检查 detail 是否存在、字段是否符合预期），再执行业务逻辑
示例：
const handler = (e) => {if (!e.detail || typeof e.detail !== 'object') return;
console.log('收到登录事件:', e.detail);
updateUI(e.detail.name);
};
document.getElementById('header').addEventListener('user-login', handler);
// 卸载时：
// document.getElementById('header').removeEventListener('user-login', handler);
跨 Shadow DOM 边界通信（可选进阶）
若组件使用 Shadow DOM（如 Web Components），默认事件不会穿透 shadow boundary。要让 CustomEvent 透出，需设置 bubbles: true 和 composed: true：
- composed: true 允许事件穿过 shadow root 进入 light DOM，被外部普通节点监听到
- 仅当目标监听器位于 shadow root 外部（如 document.body）且希望响应内部事件时才启用 composed
- 注意：composed 事件无法被同一 shadow tree 内的其他 slot 或子组件捕获（除非它们显式监听该节点）
示例（组件内部派发）：
this.shadowRoot.dispatchEvent(new CustomEvent('item-selected', {detail: { itemId: 'abc' },
bubbles: true,
composed: true
}));
与框架集成的注意事项
在 React/Vue/Svelte 等框架中使用 CustomEvent 需留意生命周期和事件机制差异：
- React 不自动代理原生 CustomEvent，需手动 addEventListener；useEffect 中注册 + 清理是安全做法
- Vue 3 的 setup() 中可用 onMounted/onUnmounted 控制监听时机；避免在模板中用 v-on 监听 CustomEvent（v-on 只响应 Vue 自定义事件）
- 不要用 CustomEvent 替代框架自身的响应式更新（如 useState/setState），它只负责“通知”，状态更新仍需由监听方主动触发
本质是桥接层：CustomEvent 负责跨边界“喊话”，数据落地仍靠各组件自己决定如何消费。
