浏览器与 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() 的返回值决定是否继续提交。
<!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 件商品”后,页面日志依次显示:
容器收到事件,数量: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()代替业务取消。前者只影响监听器接收范围,后者才表达“不要继续执行默认业务动作”。