根本原因是未处理第三方库加载时机、实例生命周期和DOM渲染上下文三件事：需确保Chart.js等全局变量就位后再调用customElements.define()，attributeChangedCallback中必须调用update()而非仅更新配置，且Shadow DOM会破坏Canvas/Map渲染，应改用light DOM或外部容器。
直接用 customElements.define() 注册封装了 Chart.js 或 Canvas 绘图逻辑的自定义元素，但图表不渲染、控制台报错或反复重绘卡顿——根本原因不是代码写得不对，而是没处理好第三方库加载时机、实例生命周期和 DOM 渲染上下文这三件事。
customElements.define() 必须等第三方库全局变量就位再调用
常见错误是把 customElements.define('my-chart', ChartComponent) 写在 <script> 标签里，而 Chart.js 还没加载完。浏览器报 Failed to execute 'define' on 'CustomElementRegistry': the name "my-chart" has already been used 或静默失败，图表容器空着不动。
- 确认第三方库是否已暴露全局变量（如
window.Chart、window.L），而不是靠 ES 模块默认导出 - 用
document.readyState === 'complete'+setTimeout轮询检查window.Chart是否存在，最多试 10 次，每次间隔 50ms - 更稳妥的做法：给
<script src="chart.js"></script>加onload回调，在回调里注册组件 - 若用动态导入（
import('chart.js')），必须等then()执行完再调customElements.define()
attributeChangedCallback 里必须调第三方实例的 update 方法，不能只改配置对象
监听 data-config 属性变更后，只做 this._config = JSON.parse(val)，却不调 this._chart.update()，图表界面不会响应变化。这是最常被忽略的一步。
-
static get observedAttributes()必须显式列出要监听的属性，比如['data-config', 'data-series']，漏掉就收不到变更 - 首次初始化用
new Chart(ctx, config)；后续变更优先走this._chart.data.datasets = [...]+this._chart.update()，而不是销毁重建 - Leaflet 地图类更敏感：必须先
this._map.remove()清掉旧实例，再new L.Map(...)，否则内存泄漏且地图错位 - 避免在
attributeChangedCallback中重复解析 JSON 字符串，应在constructor或首次connectedCallback里缓存为对象
Shadow DOM 会破坏 Canvas 和 Map 渲染上下文，必须改用 light DOM 或显式传入容器
在 this.attachShadow({ mode: 'open' }) 里插入 <canvas></canvas>，Chart.js 报 Canvas is not accessible；Leaflet 显示空白或定位异常——这不是 bug，是 Shadow DOM 切断了 CSS 尺寸继承和 DOM 查询链。
立即学习“前端免费学习笔记（深入）”；
- Mapbox GL、Three.js 等库明确禁止在 Shadow DOM 中渲染，文档里直接写 “not supported in shadow DOM”
- 绕过方案一：放弃 Shadow DOM，用 light DOM + 命名空间 CSS 类（如
.my-chart-wrapper canvas），靠 class 隔离样式 - 绕过方案二：保留 Shadow DOM，但把渲染目标设为外部容器，例如通过
data-target="#my-canvas"让组件查到 light DOM 中的<canvas id="my-canvas"></canvas> - 如果坚持用 Shadow DOM，必须手动透传 CSS 变量（如
:host { --chart-width: 100%; }）并确保父容器有明确宽高，否则 Canvas 默认 300×150 像素无法拉伸
真正卡性能的地方往往不在绘图本身，而在反复创建/销毁第三方实例、没清理定时器或观察者、以及在 attributeChangedCallback 里全量重写 shadowRoot.innerHTML 导致 slot 内容丢失——这些细节不处理，封装出来的组件越用越慢。
