customElements.define()必须在DOM解析前同步执行，否则标签被当作HTMLUnknownElement处理；类须继承HTMLElement且constructor中调super()；attributeChangedCallback不触发初始属性，需在connectedCallback中手动读取。
customElements.define() 必须在 DOM 解析前调用
注册失败最常见原因不是写错类，而是执行时机不对。customElements.define() 必须在浏览器解析到对应自定义标签之前完成。否则该标签会被当作 HTMLUnknownElement 处理——它留在 DOM 里，但不触发 constructor、不调用 connectedCallback，后续也无法补救。
常见错误现象：
-
<my-button></my-button>渲染出来是空的，控制台无报错但无任何生命周期钩子执行痕迹 - 属性值读不到（
this.getAttribute('label')返回null），即使 HTML 中写了label="确定"
实操建议：
- 把
customElements.define()放在<script>标签内，并确保该<script>出现在所有自定义标签之前 - 或统一用
defer属性：<script defer src="components.js"></script>，让脚本在 DOM 构建完成后、但尚未开始解析自定义标签时执行 - 不要在
window.onload或DOMContentLoaded里注册——太晚了，DOM 已经解析完毕
继承 HTMLElement 是硬性前提，不能省略 super()
自定义元素类必须显式继承 HTMLElement（或其子类，如 HTMLButtonElement），且构造函数第一行必须调用 super()。漏掉任一环节，实例化时直接抛错：Failed to construct 'MyButton': Please use the 'new' operator。
立即学习“前端免费学习笔记（深入）”；
为什么必须这样？
-
super()是浏览器识别“这是合法自定义元素实例”的关键信号，不调用就无法接入 DOM 生命周期 - 不继承
HTMLElement，customElements.define()会拒绝注册，报NotSupportedError - 扩展现有元素（如
<button is="ds-button">）时，必须继承对应内置类，例如class DsButton extends HTMLButtonElement
错误写法示例：
class MyButton {
constructor() {
// ❌ 没继承、没 super()，注册直接失败
}
}
正确写法：
class MyButton extends HTMLElement {
constructor() {
super(); // ✅ 必须第一行
this.attachShadow({ mode: 'open' });
}
}
attributeChangedCallback 不响应初始属性值
即使你声明了 static get observedAttributes() 并实现了 attributeChangedCallback，它也不会在元素首次被 HTML 解析时触发——也就是说，<my-input value="hello"></my-input> 中的 value="hello" 不会进这个回调。
这导致一个典型问题：组件内部状态和初始属性不同步。
实操建议：
- 在
connectedCallback中手动读取初始属性并同步到内部状态：this._value = this.getAttribute('value') || '' - 只在
attributeChangedCallback中处理后续变更，避免重复赋值 - 注意：只有字符串属性会被观测；布尔属性（如
disabled）需用this.hasAttribute('disabled')判断
Shadow DOM 是样式隔离的唯一可靠方式
很多人以为加个 <style> 标签就能让自定义元素带样式，结果发现字体、颜色全丢了，或者外部 CSS 突然穿透进来。根本原因是：没有用 Shadow DOM。
浏览器对自定义元素默认不应用任何样式，也不继承页面全局样式——它是一张白纸。
实操要点：
-
this.attachShadow({ mode: 'open' })必须在constructor中调用，不能拖到connectedCallback - 样式必须注入 shadowRoot 内部：
shadowRoot.innerHTML = '<style>:host { display: inline-block; }</style>' - 想让外部控制主题？用 CSS 自定义属性：
:host([theme="dark"]) { --bg-color: #222; }，再在内部用var(--bg-color) - 别指望
<style>body { ... }</style>生效——body根本不在 shadow 里
复杂点在于：Shadow DOM 的 mode: 'closed' 会彻底屏蔽外部 JS 访问（比如测试工具或调试脚本拿不到 shadowRoot），而 'open' 虽方便调试，但业务方可能意外修改内部结构。选哪个，得看你的封装边界是否真需要物理级隔离。
