自定义元素是解决组件复用、逻辑隔离和DOM污染的核心手段，而非替代div的语法糖；其有效前提为注册早于HTML解析、挂载时防重复初始化、动态插入后显式upgrade。
直接说结论：自定义元素不是用来替代 div 的“语法糖”，而是解决组件复用、逻辑隔离和 DOM 污染的核心手段；在大型项目里，它真正起效的前提是——注册时机早于 HTML 解析、挂载时防重复初始化、动态插入后显式 upgrade。
customElements.define 必须在 HTML 解析完成前执行
浏览器解析 HTML 时，遇到未注册的标签（比如 <product-card>）会立刻创建 HTMLUnknownElement 实例，之后再调用 customElements.define() 不会自动升级这些节点——它们永远不触发 connectedCallback，也不执行任何逻辑。
- 错误做法：把所有
customElements.define()放在window.onload、DOMContentLoaded或模块import()回调里 - 正确做法：用内联
<script>，或type="module" defer确保脚本在 HTML 解析流中提前执行 - 若无法控制 HTML 输出顺序（如 CMS 渲染），必须手动遍历并调用
customElements.upgrade(node)
动态插入含自定义标签的 HTML 后必须 upgrade
通过 innerHTML、insertAdjacentHTML 或框架的 v-html/dangerouslySetInnerHTML 插入的自定义标签，浏览器不会自动识别——它们仍是 HTMLUnknownElement，生命周期完全静默。
- 插入后立即调用
customElements.upgrade(el)，只作用于该节点及其子树 - 不要对整个容器反复调用
upgrade，避免重复工作；可结合MutationObserver监听新增节点，仅升级新增部分 -
upgrade是同步操作，节点量大时建议用queueMicrotask或requestIdleCallback分片执行
connectedCallback 里必须防重复初始化
connectedCallback 在元素每次被插入 active DOM 树时都会触发，包括 Vue/React 列表重渲染、display: none 切回、appendChild 多次调用等场景。把它当“构造函数”用，会导致 Shadow DOM 多次 attach、事件重复绑定、定时器叠加、fetch 请求发多次。
立即学习“前端免费学习笔记（深入）”；
- 用
WeakMap或私有字段（如#initialized = false）标记是否已初始化 - Shadow DOM 只 attach 一次，事件监听器用
once: true或先移除再添加 - 异步操作（如
fetch）加状态锁，避免并发请求
什么时候该用 autonomous，什么时候该用 customized built-in
独立自定义元素（autonomous）适合全新 UI 组件，如 <data-table>、<user-avatar>；自定义内置元素（customized built-in）适合增强标准语义，比如给 <p is="highlighted-paragraph"> 加高亮行为。
- autonomous 元素直接使用
<my-button>，无需额外属性，但完全脱离原生语义 - customized built-in 必须带
is属性，如<p is="my-paragraph">，保留原生语义与可访问性（如屏幕阅读器仍识别为段落） - 若需兼容旧版辅助技术或 SEO 强依赖语义（如正文段落），优先选 customized built-in
真正容易被忽略的是：自定义元素的性能瓶颈几乎从不在注册阶段，而在挂载后的初始化逻辑和 DOM 遍历；哪怕注册了 100 个元素，只要 connectedCallback 里没做防重、没控 upgrade 范围、没分片处理，页面一滚动或列表一刷新，就可能卡顿。
