自定义元素规模化应用的核心是管好生命周期、防样式泄漏、避注册冲突；需确保customElements.define()在DOM就绪后同步执行、SSR时判window、Shadow DOM选open模式、observedAttributes与attributeChangedCallback配对、扩展内置元素必用is属性并正确继承。
自定义元素不是“写完就能用”的玩具，它天然需要模块化管理机制——否则注册冲突、样式泄漏、属性不响应、SSR 失败等问题会立刻浮现。
customElements.define 必须在 DOM 就绪后执行
很多团队把 customElements.define() 放在 <script> 标签里直接写死，结果页面偶尔白屏或组件不渲染。这是因为浏览器解析 HTML 是流式进行的，<my-button> 标签出现在 define 之前时，该元素会被当作 HTMLUnknownElement 初始化，后续再注册也无效。
- 必须确保注册发生在
DOMContentLoaded之后，或使用defer属性让脚本在 HTML 解析完成后执行 - 不要在多个入口文件里重复调用
customElements.define('my-button', MyButton)，否则报错Failed to execute 'define': the element type is already defined - 推荐做法：统一注册入口（如
components/index.js），导出一个initComponents()函数，由主应用按需调用
属性只能传字符串或布尔值
写 <data-table config="{ rows: 10 }"> 看似方便，实际会导致 SSR 渲染失败、属性读取为 "{ rows: 10 }" 字符串而非对象，且 attributeChangedCallback 无法自动深监听。
- 所有 HTML 属性本质是字符串，
this.getAttribute('config')永远返回字符串，哪怕你写了config={...} - 复杂配置应显式解析：
JSON.parse(this.getAttribute('config') || '{}')，并加 try/catch - 布尔属性用
hasAttribute('loading')判断，而不是getAttribute('loading') === 'true' - 禁止通过属性传函数、DOM 节点、Promise 等非序列化值——它们在服务端或跨 iframe 场景下直接失效
Shadow DOM 内部样式必须显式注入
写了 this.attachShadow({ mode: 'open' }) 却发现字体、行高、颜色全丢了？这不是 bug，是 Shadow DOM 的设计前提：它默认不继承任何外部样式，也不向外泄漏内部样式。
立即学习“前端免费学习笔记（深入）”；
-
<style>标签必须插入到shadowRoot中，不能靠外部 CSS 文件“穿透”进来 - 想支持主题定制？暴露
--my-button-bg这类 CSS 自定义属性，并在 :host 中使用：:host { background-color: var(--my-button-bg, #007bff); } - 避免滥用
::slotted(*)或:host(:not([disabled])) ::slotted(button)—— 嵌套层级一深就难以调试，建议只对明确 slot 名做样式控制 - 不要在 shadow 内写
body { color: red }，shadow 中没有body元素，这类选择器永远不生效
attributeChangedCallback 不触发初始值
<my-input value="hello"> 渲染后，value 属性值确实是 "hello"，但 attributeChangedCallback 一次都不调用——这是规范行为，不是遗漏。
-
attributeChangedCallback只响应 DOM 属性的**变更**，不处理初始值；首次渲染时属性已存在，属于“静态设置” - 必须在
connectedCallback中手动同步初始值：this.value = this.getAttribute('value') || '' - 若依赖属性初始化 UI，务必同时覆盖
constructor（初始化字段）、connectedCallback（读属性+渲染）、attributeChangedCallback（响应变更）三处逻辑 - 忘记手动同步，就会出现“HTML 里写了 value，但输入框空着”这种典型问题
真正难的不是写出一个能跑的自定义元素，而是让它在 SSR、多版本共存、跨团队复用、主题切换、无障碍访问等真实工程场景中不出错——这些细节不在 API 文档里，但在每天的构建失败和线上 bug 中反复出现。
