HTML自定义事件机制在解耦DOM操作中的应用规范-html教程-PHP中文网

customevent 的 detail 必须是 plain object，禁止传字符串、null、dom 节点、函数、map、set 或 class 实例；监听端需先判空再解构；dispatch 前须确认目标元素存在且可访问，shadow dom 中需明确指向 shadowroot；事件注册时机与作用域必须匹配冒泡路径；data-* 属性命名须全小写连字符，js 中须用 setattribute 写入，dataset 值恒为字符串。

html自定义事件机制在解耦dom操作中的应用规范

CustomEvent 的 detail 必须是 plain object

传字符串、null 或 DOM 节点到 detail，监听方解构时大概率报错：TypeError: Cannot destructure property 'type' of e.detail as it is string。浏览器不校验，但你的代码会崩在第一行。

错误写法：new CustomEvent('editor:change', { detail: 'text' })、{ detail: null }、{ detail: document.body }
正确结构至少含 type 和 payload：{ type: 'insert', payload: { html: '<p>ok</p>' } }
禁止传函数、Map、Set、class 实例——跨 iframe 会序列化失败，且无法被 JSON 安全克隆
监听端必须先判空再解构：if (e.detail && typeof e.detail === 'object') { const { type, payload } = e.detail; }

dispatchEvent 前必须确认目标元素存在且可访问

常见错误是直接对 document.getElementById('console-log') 调用 dispatchEvent，结果元素还没挂载，或藏在 Shadow DOM 里，调用直接静默失败。

html-ppt-to-pdf

将使用 `

` 约定的 HTML 幻灯片转换为高保真、矢量文本 PDF（使用 Playwright + Chromium 原生 PDF 功能）。

下载

Light DOM 场景：先查再发，加空值判断：const el = document.getElementById('console-log'); if (el) el.dispatchEvent(evt);
Shadow DOM 场景：不能用 this.dispatchEvent(evt)（发给自定义元素自身），得明确指向 this.shadowRoot.dispatchEvent(evt)
更稳妥的兜底方案：用全局事件总线，document.dispatchEvent(evt) 广播，再由日志组件在 document.addEventListener('log:entry', ...) 监听

addEventListener 注册时机和作用域必须匹配事件冒泡路径

“事件发了，但监听没响应”——八成是注册时机或作用域错位。

监听器注册太晚：比如在 connectedCallback 里加监听，但编辑器初始化阶段已触发首条 editor:change，这条就丢了
冒泡路径断裂：编辑器在 shadowRoot 内 dispatch，却在 document 上监听，且没设 bubbles: true → 事件卡在 shadow boundary
误用 once: true：只捕获第一次，后续所有变更都失效
监听位置要和 dispatch 目标一致：发给 #console-log，就得在它身上监听；发给 document，就得在 document 上监听

data-* 属性命名与读写必须严格遵循规范

看似只是拼写问题，实际会导致 dataset 读不到、状态不一致、JSON 解析崩溃。

HTML 中命名必须全小写 + 连字符：data-user-id ✅，data-userId ❌（element.dataset.userId 返回 undefined）
JS 中写入必须用 setAttribute：el.setAttribute('data-status', 'loading')；el.dataset.status = 'loading' 只改代理副本，不更新真实 DOM 属性
dataset 值永远是字符串：el.dataset.count + 1 得到 "421"，不是 43；数值运算前务必 Number(el.dataset.count)
存 JSON 字符串必须手动 JSON.parse，且加 try/catch；服务端输出前需 HTML 实体编码，否则 &、' 会让 JSON.parse() 报错