Web Components 自定义事件需从组件实例触发并设 bubbles: true 和 composed: true 才能穿透 Shadow DOM；应解耦属性变更与事件派发，使用语义化事件名和稳定 detail 结构。
Web Components 中的自定义事件流设计，核心在于明确“谁发、谁收、怎么传、怎么穿”。它不是简单套用 dispatchEvent，而是结合 Shadow DOM 封装性、事件冒泡规则和组件通信契约来构建可预测、可维护的交互链。
事件必须从 Custom Element 实例上触发
自定义事件只能 dispatch 到一个具体的 EventTarget 上——对 Web Components 来说，这个目标通常是组件自身（this），而不是 Shadow DOM 内部节点（除非有意暴露内部细节）。外部监听也必须绑定在该元素实例上：
- ✅ 正确：在
connectedCallback或用户操作中调用this.dispatchEvent(new CustomEvent('submit', { detail: { value } })) - ❌ 错误：在 shadowRoot 内部节点上调用
button.dispatchEvent(...)后，期望外部直接监听到——默认不冒泡出 Shadow DOM 边界
使用 CustomEvent 并设置 bubbles/composed 确保穿透性
原生事件（如 click）能自然穿透 Shadow DOM 是因为它们默认带 bubbles: true 和 composed: true。自定义事件需显式声明才能获得同等能力：
-
composed: true是关键：允许事件跨过 Shadow DOM 边界，被 light DOM 中的父级监听到 -
bubbles: true让事件支持向上冒泡，便于在祖先节点统一处理（例如表单级 submit 汇总） - 推荐写法：
new CustomEvent('change', { bubbles: true, composed: true, detail: { value } })
属性变更与事件触发要解耦，避免重复或遗漏
不要把 attributeChangedCallback 当作唯一事件源。它只响应 HTML 属性字符串变化，而 JS 属性赋值（如 el.value = 123）不会触发它。合理做法是：
立即学习“Java免费学习笔记（深入）”；
- 在 setter 中同步更新 attribute，并手动 dispatch 事件（保持行为一致）
- 在
attributeChangedCallback中只做状态同步，事件由统一入口（如_notifyChange()）发出 - 避免在 connectedCallback 里重复 dispatch 初始化事件——除非业务明确需要“挂载即通知”
对外暴露语义化事件名，不暴露实现细节
事件名应反映用户意图或业务动作，而非 DOM 行为或内部状态：
- ✅ 推荐：
'submit'、'item-added'、'search-canceled' - ❌ 避免：
'click-inside-button'、'shadow-root-updated'、'value-changed'（太泛，易与原生 change 冲突） - detail 数据结构保持稳定，建议用 plain object，避免传递函数或 DOM 节点（破坏封装）
不复杂但容易忽略：事件名大小写敏感，且不能含空格或特殊字符；监听时用 addEventListener('my-event')，触发时也必须用完全相同的字符串 —— 多一个连字符或大小写错误，事件就静默失效。
