浏览器与 Web API / 系统课时

创建和派发自定义事件

创建和派发自定义事件

本课把组件内部的按钮操作转换为可监听的业务事件,完整演示事件命名、detail 数据、冒泡、同步派发以及可取消操作的实现方式。

学习目标

  • 能创建包含业务数据的 CustomEvent
  • 能用 dispatchEvent() 同步派发并接收事件
  • 能利用 bubbles、cancelable 和返回值控制事件边界

自定义事件由四部分组成

CustomEvent 适合表达“订单状态已变化”这类业务事实。事件名描述发生了什么,detail 携带业务数据,派发目标决定事件从哪里开始,监听器则决定谁响应它。

自定义事件默认不会冒泡,也不能取消。需要跨组件向祖先传递时,应设置 bubbles: true;需要让监听器阻止后续默认操作时,还要设置 cancelable: true。dispatchEvent() 会同步执行监听器,不会自动排入异步任务队列。

CustomEvent 创建、派发与取消时序

完整示例:状态通知与删除拦截

将下面内容保存为 index.html 后打开。订单组件负责派发事件,页面级监听器负责记录状态;删除前事件允许外部规则阻止操作。

html
<!doctype html>
<html lang='zh-CN'>
<head>
  <meta charset='UTF-8'>
  <title>CustomEvent 示例</title>
  <style>
    body { font-family: sans-serif; padding: 24px; }
    #order-card { max-width: 520px; padding: 16px; border: 1px solid #cbd5e1; }
    button { margin-right: 8px; }
    #log { margin-top: 16px; padding: 12px; background: #f1f5f9; }
  </style>
</head>
<body>
  <section id='order-card' data-order-id='ORDER-1001'>
    <p>订单:<strong>ORDER-1001</strong></p>
    <p>状态:<span id='status'>pending</span></p>
    <button data-status='completed'>标记完成</button>
    <button id='delete-order'>删除订单</button>
  </section>
  <pre id='log'>等待操作</pre>
  <script>
    const orderCard = document.querySelector('#order-card');
    const statusText = document.querySelector('#status');
    const log = document.querySelector('#log');
    function emitStatusChange(status) {
      const event = new CustomEvent('order:status-change', {
        bubbles: true,
        detail: {
          orderId: orderCard.dataset.orderId,
          status,
          changedAt: new Date().toISOString()
        }
      });
      orderCard.dispatchEvent(event);
    }
    document.addEventListener('order:status-change', (event) => {
      const { orderId, status, changedAt } = event.detail;
      statusText.textContent = status;
      log.textContent = `${event.type} | ${orderId} | ${status} | ${changedAt}`;
    });
    document.addEventListener('order:before-delete', (event) => {
      if (event.detail.orderId === 'ORDER-1001') {
        event.preventDefault();
      }
    });
    orderCard.addEventListener('click', (event) => {
      const statusButton = event.target.closest('[data-status]');
      if (statusButton) {
        emitStatusChange(statusButton.dataset.status);
      }
    });
    document.querySelector('#delete-order').addEventListener('click', () => {
      const event = new CustomEvent('order:before-delete', {
        bubbles: true,
        cancelable: true,
        detail: { orderId: orderCard.dataset.orderId }
      });
      const canDelete = orderCard.dispatchEvent(event);
      if (canDelete) {
        orderCard.remove();
        log.textContent = '订单已删除';
      } else {
        log.textContent = '删除已被监听器阻止';
      }
    });
  </script>
</body>
</html>

预期结果:

text
点击“标记完成”:
页面状态变为 completed。
日志显示 order:status-change | ORDER-1001 | completed | <TIME>。

点击“删除订单”:
order:before-delete 监听器调用 preventDefault()。
dispatchEvent() 返回 false,订单卡片保留,日志显示“删除已被监听器阻止”。
<TIME> 为浏览器生成的实际 ISO 时间。

同步派发与数据边界

dispatchEvent() 返回后,本次事件的所有同步监听器已经执行完毕。若监听器内部启动 fetch() 或定时器,异步工作仍会在之后完成,派发方不能把 dispatchEvent() 当作异步结果等待器。

detail 可以保存任意 JavaScript 值,并且对象按引用传递。为了降低耦合,建议传递只描述事实的普通对象,不要把可变 DOM 节点、组件实例或控制函数塞入 detail。

事件名应体现业务语义,例如 order:status-change,不要使用宽泛的 update。冒号不是语法要求,但能形成清晰命名空间,避免不同模块意外使用同名事件。

可取消事件的适用范围

只有在创建事件时设置 cancelable: true,监听器调用 preventDefault() 才会让 dispatchEvent() 返回 false。这个返回值适合表达“是否继续默认业务操作”,不适合返回复杂数据。

跨 Shadow DOM 边界时还要考虑 composed。普通页面组件通常保持默认值即可;Web Components 需要让事件离开影子树时,再明确设置 composed: true,并审查是否会暴露不必要的数据。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建和派发自定义事件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通