CustomEvent 是 HTML5 中派发携带任意结构化数据的自定义事件的标准方式，核心是通过 detail 属性封装业务数据，并在监听时安全提取和校验。
在 HTML5 中，CustomEvent 是定义和派发携带任意结构化数据（如对象、数组、日期、甚至函数）的自定义事件的标准方式。关键在于正确使用 detail 属性封装业务数据，并确保监听方能安全访问。
创建 CustomEvent 并传入复杂数据
CustomEvent 构造函数接受两个参数：事件类型名（字符串）和一个配置对象。其中 detail 字段用于承载任意 JS 值——这是传递业务数据的核心位置。
示例：派发一个含用户信息、操作上下文和时间戳的事件：
const userData = {
id: 1001,
name: "张三",
roles: ["editor", "reviewer"],
lastLogin: new Date("2024-06-15T09:30:00Z"),
preferences: { theme: "dark", notifications: true }
};
const event = new CustomEvent("userProfileUpdated", {
detail: userData,
bubbles: true, // 可选：是否冒泡
cancelable: false // 可选：是否可取消（通常业务事件无需取消）
});
// 派发到某个元素（如 document 或特定 DOM 节点）
document.dispatchEvent(event);
监听并安全提取 detail 中的业务数据
监听时通过事件对象的 detail 属性直接读取原始数据。注意：该值是深拷贝传递的（实际是引用传递，但浏览器不深克隆；若需隔离，需手动结构化克隆或序列化）。
立即学习“前端免费学习笔记（深入）”；
建议监听逻辑中做基本存在性与类型校验：
document.addEventListener("userProfileUpdated", (e) => {
// ✅ 安全访问
if (e.detail && typeof e.detail === "object") {
const { id, name, roles } = e.detail;
console.log(`用户 ${name}（ID: ${id}）已更新，角色：${roles.join(", ")}`);
// 可直接使用嵌套结构、Date 对象等
console.log("上次登录时间：", e.detail.lastLogin.toLocaleString());
}
});
处理跨 iframe 或序列化限制场景
若事件需跨 iframe 通信，或需通过 postMessage 间接传递，detail 中的函数、Symbol、undefined、Date、RegExp 等无法自动序列化。此时应：
- 预先将 Date 转为 ISO 字符串：
lastLogin: new Date().toISOString() - 避免在
detail中传函数或 DOM 节点（会报错或丢失） - 如需强隔离，用
structuredClone()（现代浏览器支持）浅层复制后再派发 - 对老环境，可手动 JSON 序列化 + 解析，但会丢失类型（如 Date 变成字符串）
封装成可复用的事件工具函数
为提升可维护性，可封装常用事件的创建与派发逻辑：
function dispatchUserEvent(type, data) {
const event = new CustomEvent(`app:${type}`, {
detail: { ...data, timestamp: Date.now() },
bubbles: true
});
document.dispatchEvent(event);
}
// 使用
dispatchUserEvent("loginSuccess", { userId: 123, token: "abc..." });
dispatchUserEvent("formSubmitted", { formId: "contact", values: { email: "x@y.z" } });
