customElements.define() 必须在第三方库加载完成后调用，否则会报错或无法渲染；属性变更需映射到第三方实例的 update/setOptions 方法；Shadow DOM 会隔离样式和 DOM 查询，需改用 light DOM、slot 或显式传入渲染目标；disconnectedCallback 中必须显式销毁第三方实例及定时器、观察者等资源。
customElements.define() 必须在第三方库加载完成后调用
直接在 script 标签里写 customElements.define('my-chart', ChartComponent) 却发现浏览器报错 Failed to execute 'define' on 'CustomElementRegistry': the name "my-chart" has already been used 或根本没渲染——大概率是第三方库（比如 Chart.js、Leaflet）还没加载完，你就急着注册了自定义元素。
正确做法是等库的全局变量就位再注册。例如 Chart.js 提供 window.Chart，可用以下方式兜底：
- 用
document.readyState === 'complete'+setTimeout轮询检查window.Chart是否存在 - 监听
load事件后对script标签做onload回调，在回调里注册组件 - 若用 ES 模块动态导入，改用
import('chart.js').then(() => customElements.define(...))
属性变更必须映射到第三方实例的 update / setOptions 方法
自定义元素通过 observedAttributes 监听 data-config、data-series 这类属性，但不能只靠 attributeChangedCallback 重新渲染 DOM —— 第三方库的实例（如 this._chart）需要主动调用其更新接口，否则界面不会响应。
常见错误是把配置 JSON 字符串直接塞进 innerHTML，或仅重绘容器却忘了调用 this._chart.update() 或 this._map.setView(...)。
立即学习“前端免费学习笔记（深入）”；
-
data-config建议存为对象属性（this._config = JSON.parse(val)），避免每次解析 - 首次初始化时用
new Chart(ctx, config)；后续变更优先走.data.datasets = ...; .update() - Leaflet 地图类需手动清理旧图层（
this._map.remove()）再重建，否则内存泄漏
Shadow DOM 会隔离第三方库依赖的 DOM 结构和样式
如果你在 this.attachShadow({ mode: 'open' }) 里插入 <canvas></canvas> 或 <div id="map"></div>，Chart.js 和 Leaflet 默认会失败——它们依赖父级容器的 CSS 尺寸、定位上下文，甚至某些库（如 Mapbox GL）明确禁止在 Shadow DOM 中渲染。
这不是 bug，是 Shadow DOM 的设计使然：它切断了样式继承和部分 DOM 查询链（document.querySelector 找不到 shadow 内部节点）。
- 绕过方式一：不用 Shadow DOM，改用
light DOM+ 命名空间 CSS 类（如.my-chart-wrapper） - 绕过方式二：用
slot把 canvas/div 暴露到 light DOM，自定义元素只负责逻辑控制 - 绕过方式三：对支持 Shadow DOM 的库（如某些新版 D3 封装），显式传入
shadowRoot.querySelector('canvas')作为渲染目标
生命周期中必须显式销毁第三方实例
disconnectedCallback 不是可选的。像地图、图表、音频播放器这类资源密集型第三方实例，如果不在元素从 DOM 移除时清理，就会持续占用内存、触发定时器、监听事件，最终拖慢页面。
你不能指望用户手动调用 myChart.destroy() 或 map.remove() —— 自定义元素得自己扛起这个责任。
- Chart.js 实例：必须调用
this._chart.destroy()，否则 canvas 缓存不释放 - Leaflet：调用
this._map.remove()，并清空所有on('click', ...)绑定 - 若用了
setInterval或requestAnimationFrame，记得在disconnectedCallback里clearInterval或取消帧请求
最易被忽略的是第三方库内部创建的 EventTarget 或 ResizeObserver 实例，它们不会随元素自动销毁，必须手动 .disconnect() 或 .unobserve()。
