customevent 的 detail 必须是 plain object，正确结构为 { type, payload, timestamp? }；dispatch 前需确保目标元素存在且作用域匹配，监听需注意注册时机、bubbles/composed 选项及事件名规范。
CustomEvent detail 必须是 plain object，不能是字符串或 null
编辑区域触发 editor:change 时如果只写 new CustomEvent('editor:change')，监听方拿到的 e.detail 是 undefined；若传 { detail: 'text' }，解构时会报 TypeError: Cannot destructure property 'operation' of e.detail as it is string。
正确做法是统一约定 detail 为结构化对象，至少包含 type 和 payload：
-
type字符串（如"insert"、"delete"），用于路由分发 -
payload对象，承载业务数据（如{ html: "<p>hello</p>", range: { start: 5 } }） - 可选
timestamp（Date.now()），便于日志排序与调试 - 禁止传 DOM 节点、
window、Map、Set或 class 实例——序列化失败，跨 iframe 时直接丢弃
dispatchEvent 前必须确保目标元素存在且是 EventTarget
常见错误是直接对 document.getElementById('console-log') 调用 dispatchEvent，但该元素可能尚未挂载，或被 Shadow DOM 封装后无法访问。
尤其在 Web Components 场景下：document.querySelector('#console-log') 返回的是 light DOM 元素，而日志面板实际渲染在 shadowRoot 内部。
安全写法分两种场景：
- Light DOM 日志区：
const logEl = document.getElementById('console-log'); if (logEl) logEl.dispatchEvent(evt); - Shadow DOM 日志区：必须明确绑定到组件实例的
shadowRoot，例如this.shadowRoot.dispatchEvent(evt)，而非this.dispatchEvent(evt)（后者发给组件自身，不自动冒泡进 shadow） - 通用兜底：把日志模块设计成单例，暴露
LogService.emit(evt)方法，内部用CustomEvent+document.dispatchEvent()全局广播，再由日志组件用document.addEventListener('log:entry', ...)监听
addEventListener 注册时机和作用域必须匹配 dispatchEvent 的冒泡路径
编辑区域触发事件后“日志没反应”，大概率是监听器注册太晚，或挂载位置不对。
典型问题包括：
- 在
connectedCallback里注册监听，但事件在constructor阶段就已触发 → 监听器错过首条日志 - 编辑器在
shadowRoot内dispatchEvent，却在document上监听，且未设bubbles: true→ 事件卡在 shadow boundary - 监听用了
once: true选项，只捕获第一次 → 后续所有编辑操作都不再记录 - 监听器挂载在父元素，但触发时未设置
composed: true（Web Components 中穿透 shadow 边界必需）
HTML 标签里写 onclack="..." 完全无效
浏览器只识别预定义事件对应的 on* 属性（如 onclick、onsubmit），对 onclack、ondataready 等自定义名称直接忽略——既不解析也不绑定。
想模拟类似 onclick 的行为，只能靠 JS 显式绑定：
- 原生写法：
el.addEventListener('clack', () => alert('clacked'))，再调用el.dispatchEvent(new CustomEvent('clack')) - jQuery 写法：
$("#clacker").on("clack", () => alert("clacked"))，再$("#clacker").trigger("clack") - 事件名必须全小写+连字符（如
data-loaded），避免与未来标准事件冲突 - 禁止读取
element.getAttribute('onclack')并执行——等同于eval()，有严重 XSS 风险
细节决定成败：漏掉 bubbles、错传 detail 类型、监听挂错位置、或者误信内联 on* 属性，都会让通信链路无声断裂。这些不是边缘 case，而是日常开发中最常卡住人的地方。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
