浏览器与 Web API / 系统课时
创建和派发自定义事件
创建和派发自定义事件
本课把组件内部的按钮操作转换为可监听的业务事件,完整演示事件命名、detail 数据、冒泡、同步派发以及可取消操作的实现方式。
学习目标
- 能创建包含业务数据的
CustomEvent - 能用
dispatchEvent()同步派发并接收事件 - 能利用
bubbles、cancelable和返回值控制事件边界
自定义事件由四部分组成
CustomEvent 适合表达“订单状态已变化”这类业务事实。事件名描述发生了什么,detail 携带业务数据,派发目标决定事件从哪里开始,监听器则决定谁响应它。
自定义事件默认不会冒泡,也不能取消。需要跨组件向祖先传递时,应设置 bubbles: true;需要让监听器阻止后续默认操作时,还要设置 cancelable: true。dispatchEvent() 会同步执行监听器,不会自动排入异步任务队列。

完整示例:状态通知与删除拦截
将下面内容保存为 index.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>预期结果:
点击“标记完成”:
页面状态变为 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,并审查是否会暴露不必要的数据。