浏览器与 Web API / 系统课时

自定义事件的冒泡与取消

自定义事件的冒泡与取消

自定义事件不仅能携带业务数据,还能像原生事件一样沿 DOM 传播、穿过 Shadow DOM 边界,并让上层监听器否决后续动作。本课将用一个可运行示例串起 bubbles、cancelable、composed 与取消检测。

学习目标

  • 理解 bubbles、cancelable 和 composed 各自控制的行为。
  • 能派发可取消事件,并通过 dispatchEvent() 判断处理结果。
  • 区分取消默认动作、停止传播与跨 Shadow DOM 边界。

三个配置项决定什么

CustomEvent 的第二个参数用于配置事件行为。bubbles 决定事件是否从目标节点向祖先节点冒泡;cancelable 决定监听器调用 preventDefault() 是否有效;composed 决定事件能否越过 Shadow DOM 的封装边界。

这三个选项默认都是 false。普通 DOM 树中通常只需关注 bubbles 和 cancelable;事件从 Shadow DOM 内部发出并需要让外部组件感知时,才需要显式考虑 composed。

需要特别区分:preventDefault() 只表示“请求取消后续默认动作”,不会停止事件继续传播;stopPropagation() 只阻断传播,也不会把事件标记为已取消。

主示例:派发可取消事件

下面的自定义元素在 Shadow DOM 内部派发 order:before-submit。外层容器在数量大于 5 时取消事件,派发方再根据 dispatchEvent() 的返回值决定是否继续提交。

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>自定义事件取消示例</title>
</head>
<body>
  <div id="order-zone">
    <order-button></order-button>
  </div>
  <pre id="log"></pre>

  <script>
    const logElement = document.querySelector("#log");

    function log(message) {
      logElement.textContent += `${message}\n`;
    }

    class OrderButton extends HTMLElement {
      constructor() {
        super();
        const shadow = this.attachShadow({ mode: "open" });
        shadow.innerHTML = `
          <button type="button">提交 6 件商品</button>
          <p id="status">等待操作</p>
        `;

        const button = shadow.querySelector("button");
        const status = shadow.querySelector("#status");

        button.addEventListener("click", () => {
          const event = new CustomEvent("order:before-submit", {
            detail: { quantity: 6 },
            bubbles: true,
            cancelable: true,
            composed: true
          });

          // 返回 false 表示某个监听器成功取消了该事件
          const accepted = button.dispatchEvent(event);
          status.textContent = accepted ? "订单继续提交" : "订单已被取消";
          log(`dispatchEvent 返回 ${accepted}`);
        });
      }
    }

    customElements.define("order-button", OrderButton);

    document.querySelector("#order-zone").addEventListener(
      "order:before-submit",
      (event) => {
        log(`容器收到事件,数量:${event.detail.quantity}`);

        if (event.detail.quantity > 5) {
          event.preventDefault();
          log("容器调用 preventDefault()");
        }
      }
    );

    document.addEventListener("order:before-submit", (event) => {
      log(`document 收到事件,defaultPrevented=${event.defaultPrevented}`);
    });
  </script>
</body>
</html>

预期结果。点击“提交 6 件商品”后,页面日志依次显示:

text
容器收到事件,数量:6
容器调用 preventDefault()
document 收到事件,defaultPrevented=true
dispatchEvent 返回 false

按钮下方状态变为“订单已被取消”。由于事件允许取消,preventDefault() 会令 defaultPrevented 变为 true,并让 dispatchEvent() 返回 false。

冒泡、跨边界与取消流程

事件先从 Shadow DOM 内部按钮发出。bubbles: true 允许它沿祖先链传播,composed: true 允许它离开 Shadow DOM;外层监听器调用 preventDefault() 后,事件仍会继续到达 document,但取消状态会保留。

自定义事件的传播、跨边界与取消流程

composed 只有在 Shadow DOM 场景中才会产生明显差异。若事件需要像普通冒泡事件一样到达外部祖先,通常同时设置 bubbles: true 和 composed: true。外层监听器看到的 event.target 可能被重定向为宿主元素,需要完整路径时可读取 event.composedPath()。

自定义事件本身不会自动执行浏览器默认动作。所谓“取消”,本质上是派发方与监听方之间的协议:监听方调用 preventDefault() 表示否决,派发方检查返回值或 defaultPrevented,再决定是否继续保存、提交或跳转。

关键边界与常见错误

  • cancelable: false 时调用 preventDefault() 不会生效,defaultPrevented 仍为 false。
  • composed: true 不会自动开启冒泡;是否向祖先传播仍由 bubbles 决定。
  • 不要用 stopPropagation() 代替业务取消。前者只影响监听器接收范围,后者才表达“不要继续执行默认业务动作”。
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

自定义事件的冒泡与取消

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

登录哪都通