CustomEvent 的 detail 属性专为传递任意 JavaScript 值设计，支持对象、数组等复杂结构，要求可序列化且监听方直接解构使用；需避免字符串化、修改原对象或使用废弃 API，推荐 EventTarget 实现跨组件松耦合通信。
CustomEvent 的 detail 属性是专为传递自定义数据设计的，它天然支持任意 JavaScript 值（包括对象、数组、函数等），是解耦组件间通信的理想载体。关键在于：detail 必须是可序列化的值（通常就是普通 JSON 数据结构），且监听方无需知道触发方内部实现，只关心 detail 内容。
detail 只接受一个参数，但可以是任意复杂结构
创建 CustomEvent 时，detail 是构造选项中的一个字段，类型不限于字符串或数字——直接传入嵌套对象、数组、甚至带方法的对象（虽然序列化时方法会被忽略，但运行时传递没问题）：
- ✅ 正确用法：
new CustomEvent('user-login', { detail: { id: 123, name: 'Alice', roles: ['admin', 'editor'], settings: { theme: 'dark', notifications: true } } }) - ⚠ 注意：不要把整个对象“字符串化”再塞进 detail（如
JSON.stringify(obj)），那会让监听方多一层解析，违背 detail 的设计本意 - ? detail 中的值在事件派发后是只读的（规范要求），但 JS 引用类型仍可被监听方修改原对象——若需不可变，可在触发前用
structuredClone()或展开语法浅拷贝
监听方直接解构 detail，无需额外解析
监听事件时，从 event 对象中直接取 event.detail，它已经是解析好的 JS 值：
- 简洁写法：
element.addEventListener('data-updated', e => { const { items, timestamp } = e.detail; renderList(items); }); - 安全访问：建议用可选链
e.detail?.config?.apiUrl或默认值const { timeout = 5000 } = e.detail || {}; - 类型提示（TypeScript）：可为事件声明接口，让 detail 具备类型推导：
interface DataUpdateEvent extends CustomEvent { detail: { items: Product[]; total: number }; }
跨组件通信时，用事件总线或父级元素做中介
不依赖全局变量或直接引用，靠 DOM 事件冒泡或自定义调度器实现松耦合：
立即学习“Java免费学习笔记（深入）”；
- 父子组件：子组件 dispatch 事件，父组件在自身元素上监听（
this.dispatchEvent(new CustomEvent(...))+parent.addEventListener(...)） - 同级/远亲组件：通过共同祖先（如 body 或自定义事件总线元素）派发和监听：
document.dispatchEvent(...)/document.addEventListener(...) - 模块级总线（推荐）：
const bus = new EventTarget();，各组件用bus.dispatchEvent()和bus.addEventListener()，完全脱离 DOM 树
避免常见陷阱
细节决定能否稳定传递复杂数据：
- ❌ 不要修改 detail 原对象后再 dispatch（虽然能传过去，但违反事件不可变原则，易引发竞态）
- ❌ 不要用
event.initCustomEvent()（已废弃），必须用构造函数 + options 对象 - ✅ 大数据量？没问题——detail 本质是内存引用传递，不是序列化/反序列化，性能开销极小
- ✅ 支持异步场景：detail 可包含 Promise 或回调函数（只要接收方知道如何处理），但注意生命周期管理
