HTML不定义事件payload结构，data-属性是唯一合规载体，CustomEvent.detail承载载荷，监听时须校验event.detail存在性及结构一致性。
HTML 本身不定义事件有效负载（payload）结构——它没这个能力，也不该承担这个职责。所谓“HTML 标注 payload”，实际是开发者在 HTML 中通过属性（如 data-）手动携带数据，再由 JavaScript 主动读取、组装、触发自定义事件。混淆这点，会导致事件逻辑散落、调试困难、类型不可靠。
为什么 data- 属性是唯一靠谱的 HTML 载荷载体
HTML 标准只允许自定义 data- 属性用于存储页面元素的私有数据。浏览器会忽略它们，但 JavaScript 可通过 element.dataset 或 getAttribute() 安全读取。其他方式（比如往 id 里塞 JSON、用注释节点存数据）都违反语义、不可靠、难维护。
-
data-属性值始终是字符串，JSON 需要JSON.parse()手动解析，别忘了加try/catch - 属性名自动转驼峰：
data-user-id→dataset.userId，大小写敏感，别拼错 - 不要存复杂对象或函数——序列化后丢失引用、无法还原行为，只放扁平字段
dispatchEvent() 触发时 payload 必须走 CustomEvent 构造器
原生 DOM 事件（如 click）没有 payload 概念；只有 CustomEvent 支持传入 detail 字段作为载荷。直接 new Event('my-event') 不带 detail，JS 端拿到的就是空对象。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 必须用
new CustomEvent('my-event', { detail: { id: 123, status: 'done' } }) -
detail是只读属性，后续修改无效；需要新数据就得发新事件 - 避免在
detail中传 DOM 节点（内存泄漏风险）、File对象（序列化失败）、或循环引用对象（JSON.stringify报错）
示例：
const btn = document.querySelector('#save-btn');
btn.addEventListener('click', () => {
const payload = {
formId: btn.dataset.formId,
timestamp: Date.now()
};
btn.dispatchEvent(new CustomEvent('form:submit', { detail: payload }));
});
监听端解包 payload 的三个常见翻车点
很多人监听到事件后直接访问 event.detail，却没考虑兼容性、存在性和结构一致性。
立即学习“前端免费学习笔记（深入）”；
-
event.detail在非CustomEvent中是undefined，务必先if ('detail' in event)或event instanceof CustomEvent - 服务端返回的 JSON 字段名可能和前端约定不一致（比如后端用
user_id，前端代码写event.detail.userId），建议统一用event.detail['user_id']或做映射层 - 多个模块监听同一事件时，一个模块修改了
event.detail（虽然不推荐），其他监听器会看到被改过的值——detail不是深拷贝
真正麻烦的不是怎么塞数据，而是当 data-action="delete" 和 data-payload='{"id":42}' 同时存在时，没人记得清哪个字段优先、谁负责校验格式、错误时要不要 fallback 到默认值。这些边界，HTML 压根不管。
