customElements.define() 仅注册元素，不自动绑定事件或响应属性变化；所有交互需在 connectedCallback() 中手动绑定，状态变更需显式重渲染，第三方库需绕过 Shadow DOM 限制，CSS 变量需主动读取注入。
customElements.define() 只注册，不自动绑定事件
注册自定义元素后，customElements.define() 本身不做任何交互初始化——它只是让浏览器认识这个新标签。你写 <my-accordion>，浏览器会解析成元素，但里面按钮点不动、属性改了没反应、状态变了界面不更新，全是正常现象。
常见错误是直接在 Shadow DOM 里写 <button onclick="handleToggle()">，或试图用外部 JS 绑定 document.querySelector('my-accordion button').addEventListener(...)。前者因作用域隔离失效，后者因 Shadow DOM 内部节点不可见而查不到。
- 所有事件监听必须在
connectedCallback()中，通过this.shadowRoot.querySelector()获取内部节点后调用addEventListener() - 不要在
constructor()里绑事件：此时shadowRoot已存在，但 DOM 尚未挂载，querySelector返回null - 若需响应属性变化（如
expanded或disabled），必须显式声明static get observedAttributes()并实现attributeChangedCallback()
Shadow DOM 隔离导致第三方库失败
Chart.js、Leaflet、Mapbox GL 等库默认依赖父容器的 CSS 尺寸、定位上下文和全局样式链。把 <canvas> 或 <div id="map"> 放进 attachShadow() 后，它们大概率报错或渲染空白——这不是 bug，是 Shadow DOM 的设计使然。
典型报错包括：TypeError: Cannot read property 'clientWidth' of null（Canvas 宽高读不到）、Map container not found（找不到目标 DOM 节点）。
立即学习“前端免费学习笔记（深入）”；
- 首选方案：放弃 Shadow DOM，改用 light DOM + 命名空间类（如
.my-chart__canvas），靠 CSS 作用域隔离 - 若坚持用 Shadow DOM，需显式传入渲染目标：比如提供
target属性，让用户指定页面中一个已存在的<div>，再把第三方实例挂到那里 -
disconnectedCallback()中必须手动销毁第三方实例（this._chart.destroy()）、清除定时器、解绑观察者，否则内存泄漏
属性变更 ≠ 自动重渲染
HTML 自定义元素没有内置响应式系统。设 <my-form loading="true">，光在 attributeChangedCallback() 里更新 this.loading = true 是不够的——DOM 不会自动同步，按钮不会变灰，加载动画不会出现。
你需要自己维护状态、触发重绘，并确保 UI 和属性一致。例如，用户点击折叠面板后，既要更新 this.expanded = !this.expanded，也要调用 this.render() 更新 shadowRoot 内容，还要同步设置 this.setAttribute('expanded', this.expanded) 以保持属性与状态对齐。
- 避免每次属性变更都全量重写
shadowRoot.innerHTML；推荐用innerHTML初始化后，仅操作关键节点（如el.classList.toggle('open')） - 若用 JSON 字符串传配置（如
data-config='{"title":"xxx"}'），应在attributeChangedCallback()中JSON.parse()并缓存为对象属性，而非每次都解析 - 复杂状态建议封装为
this.state = { expanded: false, loading: false }，并在状态变更后统一触发this.updateUI()
CSS 变量无法穿透 Shadow DOM 边界
你在根 HTML 上设了 style="--primary-color: #007bff"，然后在 Shadow DOM 的 <style> 里写 color: var(--primary-color)，结果颜色始终 fallback 到初始值——因为 var() 查找范围仅限于当前 Shadow Root，不会向上穿透。
直接写死颜色或用内联 style 是临时解法，但主题切换时就失效了。真正可维护的方式，是主动从 light DOM 拿变量值，再注入到内部元素。
- 在
connectedCallback()或attributeChangedCallback()中调用getComputedStyle(this).getPropertyValue('--primary-color') - 把获取到的值赋给内部元素的
style.color，或拼成style="color: #007bff"设置到对应节点上 - 不要在每次
render()里重复调用getComputedStyle；可缓存值，或只在attributeChangedCallback()监听到主题相关属性变更时更新
封装复杂交互的核心难点不在语法，而在责任边界：Web Components 不替你管事件、不替你同步状态、不替你清理资源、也不替你桥接 CSS 上下文。每一步都得你亲手写清楚——漏掉任何一个，组件就卡在“看起来像，但动不了”的状态。
