customElements.define()注册失败主因是标签名不合规，须含短横线、全小写、非原生名；attachShadow()仅能在constructor中super()后调用；属性监听需声明observedAttributes；Shadow DOM需内联样式且用:host继承样式。
customElements.define() 报 DOMException: "xxx" is not a valid custom element name
标签名不合规是注册失败最常见原因，不是代码没执行，而是浏览器直接拒绝注册。
必须同时满足三条硬性规则：
- 名字里至少含一个短横线
-（不能是下划线_或驼峰） - 全小写（
MyButton❌，my-button✅） - 不能是原生标签名或保留前缀（
div、html、x-foo、html-test都被拒）
错误示例：customElements.define('mybutton', MyButton) → 报错；customElements.define('MyButton', MyButton) → 同样报错。合法写法只有像 my-button、date-picker、nav-menu 这类。
constructor 里调用 attachShadow() 报 Failed to execute 'attachShadow' on 'Element'
这个错说明你把 attachShadow() 放错了地方 —— 它只能在 constructor 中调用，且必须紧随 super() 之后。
立即学习“前端免费学习笔记（深入）”；
常见踩坑点：
- 在
connectedCallback里调用this.attachShadow()→ 报错，因为此时 light DOM 已有子节点（比如 HTML 中写的文本或<slot></slot>） -
constructor里漏掉super()→ 实例化时直接抛Illegal constructor - 用了匿名类：
customElements.define('my-btn', class extends HTMLElement { ... })→ 不被接受，必须传命名类
正确写法只有一种模式：
class MyButton extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
}
}
HTML 里写了 size="large"，但组件内部没响应
属性变更不触发回调，不是监听失效，而是压根没声明要监听。
attributeChangedCallback 不会自动响应任意属性 —— 必须显式告诉浏览器哪些属性值得观察：
- 在类中定义静态 getter：
static get observedAttributes() { return ['size', 'disabled', 'label']; } - 属性值始终是字符串，
size="24"传进来就是"24"，需手动转：parseInt(newValue) -
attributeChangedCallback不处理初始值（即 HTML 中首次写的size="large"），得在connectedCallback里手动读一次：this.getAttribute('size')
漏掉 observedAttributes，等于关掉了属性监听开关，改再多次也没用。
样式完全不生效，字体颜色全丢了
不是 CSS 写错了，是 Shadow DOM 天然隔离样式 —— 外部样式进不来，内部样式也出不去。
必须把样式显式注入 shadow root：
- 不能靠外部
<style></style>或全局 class 控制组件内部外观 - 要在
constructor或connectedCallback中插入 style 节点，例如：shadowRoot.innerHTML = '<style>button{color:red}</style>...'; - 想让外部控制宿主样式，用
:host和:host([size="large"])，而不是直接选button
最容易忽略的是：连最基本的字体继承都要手动写 :host { font: inherit; }，否则 shadow 里文字默认用浏览器 UA 样式，和页面脱节。
