CustomEvent 允许在 DOM 元素上触发和监听自定义事件，通过 new CustomEvent() 创建、dispatchEvent() 分发、addEventListener() 监听，支持 detail 传参、bubbles 冒泡及 cancelable 控制，适用于组件通信与状态通知。
JavaScript 中的 CustomEvent 让你能在 DOM 元素上触发和响应自定义事件，不依赖内置事件类型，适合组件通信、状态通知等场景。关键在于正确创建、分发和监听，且注意事件冒泡与细节控制。
创建并分发 CustomEvent
用 new CustomEvent() 构造事件对象，第一个参数是事件名（字符串），第二个参数是配置对象，可指定 detail（携带数据）、bubbles（是否冒泡）、cancelable（是否可取消）：
-
detail可传任意值（对象、数组、字符串等），是自定义事件传递数据的主要方式 -
bubbles: true时，事件会向上冒泡到父元素；默认为false - 调用
element.dispatchEvent(event)才真正触发事件，不是自动发生
示例：
const event = new CustomEvent('user-login', {detail: { userId: 123, token: 'abc' },
bubbles: true
});
document.body.dispatchEvent(event);
使用 addEventListener 监听自定义事件
监听方式和原生事件完全一致，事件名必须与分发时一致（区分大小写），回调函数中通过 event.detail 获取传递的数据：
立即学习“Java免费学习笔记（深入）”；
- 监听目标需是实际分发事件的那个元素，或其祖先（若设置了
bubbles: true） - 回调函数参数是标准
Event对象，event.type是事件名，event.detail是你传入的数据 - 支持捕获阶段监听（第三个参数设为
true），但通常用冒泡阶段更直观
示例：
document.body.addEventListener('user-login', (e) => {console.log('登录成功：', e.detail.userId); // 输出 123
});
在自定义元素或组件中合理使用
自定义事件特别适合封装可复用的 Web Component 或框架无关组件：
- 组件内部逻辑完成时（如表单提交成功、加载结束），派发自定义事件通知外部
- 避免直接操作外部状态，保持解耦；外部只需监听，无需了解组件内部实现
- 建议事件名采用 kebab-case（如
data-loaded）或加命名空间（如myapp:save-success），减少冲突风险
注意事项与常见陷阱
几个容易出错的地方需留意：
-
dispatchEvent()返回布尔值：true表示事件未被取消，false表示被preventDefault()阻止（仅当cancelable: true且监听器调用了preventDefault()） - 事件名不能包含空格或特殊字符，且不能以数字开头
- 如果监听器在事件分发之后才注册，将收不到该次事件——确保监听先于分发，或在合适生命周期钩子中绑定（如
connectedCallback） -
CustomEvent本身不提供“事件总线”功能；如需跨组件全局通信，需自行维护一个中心派发器（如基于EventTarget的实例）
