CustomEvent 的 detail 属性需传递不可变、结构清晰的纯数据，发送方用 Object.freeze 封装并校验类型，接收方必须主动校验字段存在性与类型，配合命名规范和文档约束以避免隐式耦合与数据污染。
CustomEvent 的 detail 属性是浏览器原生支持的、轻量且语义明确的跨组件通信方式，但“安全传递状态”的关键不在于能否传，而在于如何避免隐式耦合、数据污染和类型失控。核心原则是：只传必要、不可变、结构清晰的数据，且接收方必须主动校验。
只传递纯数据对象，禁止传函数、DOM 节点或 this 引用
detail 本质是序列化后通过事件系统分发的值，浏览器会尝试克隆它（使用 structured clone 算法）。函数、Promise、Window、Node 等无法被克隆的对象会被静默丢弃，导致接收方拿到空或不完整数据，甚至报错。
✅ 正确做法：
- 始终用 plain object、array、string、number、boolean、null 或嵌套组合
- 例如：
{ userId: 123, status: "loaded", items: [{ id: 1, name: "a" }] } - 发送前可简单校验：
if (typeof detail === 'object' && detail !== null && !detail.constructor) { /* 安全 */ }
用 const 声明 detail，配合 Object.freeze 防止意外修改
虽然事件对象本身不可写，但 detail 内部对象仍可被接收方修改，造成状态污染——尤其在多个监听器共用同一事件时。
✅ 推荐写法：
- 发送端：用
Object.freeze封装深层结构（浅冻结即可，structured clone 已保证副本独立） const detail = Object.freeze({ count: 42, mode: "edit" });- 接收端：不直接修改
event.detail，如需衍生状态，应解构或展开创建新对象：const { count, mode } = event.detail;
约定 key 名与类型，用 TypeScript 或 JSDoc 显式标注
没有类型约束时，detail 容易变成“魔法对象”，增加维护成本。即使不用 TS，也应通过文档或命名降低歧义。
✅ 实践建议：
- key 名带业务前缀，如
authToken、filterConfig，避免泛用data、payload - 在事件 dispatch 处加 JSDoc：
/** @type {{ userId: number; avatarUrl?: string }} */<br>const detail = { userId: 101 }; - 若用 TypeScript，定义
interface并在CustomEvent<T>中显式声明：new CustomEvent('user-login', { detail: user })，其中user类型为UserDetail
监听端必须做存在性与类型校验，不信任任何 detail 字段
事件可能被误触发、detail 可能为空、字段可能缺失——依赖未校验的 event.detail.xxx 是常见崩溃源头。
✅ 必须检查：
- 是否存在：
if (!event.detail) return; - 关键字段是否符合预期类型：
if (typeof event.detail.id !== 'number') return; - 可选字段用逻辑判断代替直接访问：
const avatar = event.detail.avatarUrl ?? '/default.png'; - 复杂结构用
in或hasOwnProperty判断字段存在性，而非仅靠!= null
不复杂但容易忽略：安全不是靠一次封装实现的，而是发送方克制、结构清晰，接收方谨慎验证、不假设输入。CustomEvent 本身不提供安全性，安全来自团队对 detail 达成的轻量契约。
