js CustomEvent自定义事件

2026-05-10 04:00:31 974阅读 0评论

跳出回调泥潭：用原生 CustomEvent 重构前端通信逻辑

做前端开发久了，难免会遇到这种场景：一个深埋在子组件里的按钮点击后，不仅要更新本地状态，还得通知两三个完全无关的兄弟组件刷新数据，甚至触发全局 Loading 状态。为了传这个信号，你可能层层传递回调函数，或者引入一个重型的全局状态管理库来处理简单的“广播”。这时候，原生 JavaScript 里的 CustomEvent 往往是个被低估的利器。

很多开发者对事件的理解还停留在 click 或 keyup 上。其实，浏览器允许我们像发送普通邮件一样，向 DOM 树中的任何节点投递“自定义信件”。它的核心能力在于解耦——让发送者不需要知道接收者是谁，只要对方订阅了这条消息就行。

核心用法：不仅仅是触发

创建自定义事件非常简单，但细节决定成败。不要只写 new CustomEvent('my-event')，配置选项才是关键。

const event = new CustomEvent('user-login-success', {
  bubbles: true,          // 是否冒泡，跨层级通知常设为 true
  cancelable: false,      // 是否可被阻止
  composed: true,         // 能否跨越 Shadow DOM 边界
  detail: {               // 👉 最关键的部分，携带业务数据
    userId: 1001,
    token: 'xyz...',
    timestamp: Date.now()
  }
});
element.dispatchEvent(event);

看到 detail 属性了吗？这是它与传统事件的本质区别。传统事件只能告诉你“发生了什么”，而 CustomEvent 能告诉你“发生的具体内容是什么”。在业务中，你经常需要把对象、数组甚至函数作为参数传递，直接用 detail 包裹即可，监听方通过 event.detail 解构使用，干净利落。

适用场景：比 Store 更轻量

并不是所有通信都要上 Redux 或 Pinia。在一个中小型项目，或者模块间存在强隔离需求的场景下（比如微前端子应用之间，或者 iframe 内部），CustomEvent 是天然的桥梁。

假设你有一个登录模块和一个侧边栏模块，两者无父子关系。侧边栏需要监听登录状态变化以显示用户信息。登录模块只需在成功时调用一次：

window.dispatchEvent(new CustomEvent('app-auth-changed', { detail: userObj }));

侧边栏独立初始化时注册监听：

window.addEventListener('app-auth-changed', handleUserUpdate);

这种方式避免了将侧边栏的渲染逻辑强耦合进登录模块，真正做到了松耦合。

避坑指南：命名与清理

用得好是神器，用不好就是隐患。新手最容易犯的两个错误是命名冲突和内存泄漏。

为了避免全局命名污染，建议在事件名前加前缀或包名，比如 project-name/login-update，而不是直接叫 login-update。想象一下，如果引入的第三方插件也有个同名事件，你的页面行为就会变得不可控。

更大的问题是内存泄漏。如果在组件销毁（如 Vue 的 unmounted 或 React 的 useEffect cleanup）时没有移除监听器，这些挂载在 window 或文档上的事件句柄会一直驻留内存。务必养成习惯：在哪里添加监听，就在哪里移除。

// 正确的清理姿势
const handler = (e) => console.log(e.detail);
window.addEventListener('my-event', handler);
// ... 某些时候 ...
window.removeEventListener('my-event', handler);