customelements.define() 仅注册元素，不自动绑定事件或响应属性变化；需在 connectedcallback 中手动添加事件监听、在 observedattributes 中声明监听属性、透传 css 变量，并谨慎处理第三方库兼容性。
customElements.define() 只注册，不自动绑定事件
注册自定义元素后，customElements.define() 本身不注入任何交互逻辑——点击、输入、属性变更都不会自动响应。常见错误是给 shadow 内部写个 <button onclick="handleClick()"></button>，结果点击毫无反应：Shadow DOM 隔离了作用域，onclick 属性在 shadow 中无效，且外部绑定的事件监听器也触达不到内部节点。
必须在 connectedCallback() 中显式获取 this.shadowRoot，再用 querySelector() 找到目标元素并调用 addEventListener()：
connectedCallback() {
if (this.shadowRoot) {
const btn = this.shadowRoot.querySelector('button');
btn?.addEventListener('click', () => this._handleClick());
}
}
- 别在
constructor()里绑定事件：此时this.shadowRoot已存在，但 DOM 尚未挂载，querySelector()返回null - 若组件支持多次挂载/卸载（如被
innerHTML替换），需在disconnectedCallback()中移除监听器，避免内存泄漏 - 事件处理器中修改状态后，必须主动调用渲染方法（如
this._render()），否则 UI 不更新
attributeChangedCallback 不会自动触发，必须声明 observedAttributes
改了自定义元素的属性（比如 <my-panel open></my-panel> → <my-panel></my-panel>），组件不会感知——除非你提前告诉浏览器“我要盯这个属性”。attributeChangedCallback() 是个空壳，只有配合静态 getter observedAttributes 才生效。
正确写法：
static get observedAttributes() {
return ['open', 'disabled', 'loading'];
}
attributeChangedCallback(attrName, oldValue, newValue) {
if (oldValue === newValue) return;
switch (attrName) {
case 'open':
this._isOpen = newValue !== null;
this._render(); // 必须手动刷新 UI
break;
}
}
-
observedAttributes返回的是字符串数组，不是正则或通配符；漏写某个属性名，变更就静默丢失 - 布尔属性（如
open）在 DOM 中存在即为true，不存在即为false，newValue在移除时为null，不能直接用== true判断 - 若属性值是对象或数组，建议转成 JSON 字符串存为 attribute（如
data-config='{"size":"large"}'），否则取出来是[object Object]
Shadow DOM 隔离 CSS 变量，得手动透传
在 shadow 内写 color: var(--primary-color)，结果颜色始终 fallback 到初始值——因为 --primary-color 定义在 light DOM，而 Shadow DOM 不继承 CSS 自定义属性。这不是 bug，是设计如此。
正确做法是在 connectedCallback() 或 attributeChangedCallback() 中主动读取并应用：
const themeColor = getComputedStyle(this).getPropertyValue('--primary-color').trim();
this.shadowRoot.querySelector('.header')?.style.color = themeColor;
- 别在每次
_render()里重复调用getComputedStyle()，性能差；可缓存值，或只在属性变更时更新 - 如果组件支持主题切换（如用户改了根变量），需监听
document.documentElement的style变更，或依赖外部通知机制 - 避免用
!important强覆盖 shadow 内样式——它会破坏主题一致性，且难以调试
封装第三方库时，Shadow DOM 常导致渲染失败
Chart.js、Leaflet、Mapbox GL 等库默认无法在 Shadow DOM 中正常工作：它们依赖父容器的 CSS 尺寸计算、全局样式上下文，甚至某些库（如 Mapbox）明确禁止在 shadow 内初始化。
绕过方式只有两个，没有第三条路：
- 放弃 Shadow DOM，用 light DOM + 命名空间类（如
.my-chart-wrapper），靠 CSS 作用域隔离 - 保留 Shadow DOM，但把渲染目标（
<canvas></canvas>或<div id="map">）放在 light DOM，通过 <code>slot或data-target属性传入 ID，让第三方库操作外部节点 - 务必在
disconnectedCallback()中调用this._chart.destroy()或this._map.remove()，否则实例残留、内存泄漏、地图重叠
最关键的细节：所有第三方库的初始化（new Chart(...)）和配置更新（.update()）都必须发生在 connectedCallback() 之后，并确保库已加载完成——customElements.define() 要等 window.Chart 存在才执行。
