customElements.define报错“Failed to execute 'define'”几乎全是标签名不合规所致：必须含短横线、全小写、不能开头/结尾/连续，如my-button合法，mybutton、-my-btn、MyButton均非法。
customElements.define 必须在类定义后立即调用，且标签名不带短横线会直接报错——这不是警告，是浏览器拒绝执行的硬性拦截。
自定义元素名为什么总报 Failed to execute 'define' on 'CustomElementRegistry'
这个错误几乎全是命名问题。浏览器强制要求自定义标签名必须含且仅含小写字母、数字和短横线（-），且短横线不能在开头或结尾，也不能连续出现。
-
my-button✅ 合法：全小写 + 一个短横线 -
data-input-field✅ 合法：多个短横线，但不连用 -
mybutton❌ 报错：缺短横线 -
-my-btn❌ 报错：短横线开头 -
my-btn-❌ 报错：短横线结尾 -
MyButton❌ 报错：含大写字母
注意：customElements.define('my-button', MyButton) 中的字符串参数和类名本身无关，只校验字符串格式；哪怕类叫 MyButton，只要注册名是 'my-button' 就合法。
constructor 里该做什么，不该做什么
这是最容易写出“看似运行、实则失效”代码的地方。constructor 是唯一能安全调用 this.attachShadow() 的时机，但其他操作极易翻车。
立即学习“前端免费学习笔记（深入）”；
- ✅ 必须做：调用
super()、执行this.attachShadow({ mode: 'open' })、初始化私有字段（如this._value = null） - ❌ 绝对禁止：读取
this.innerHTML或this.getAttribute('xxx')—— 此时属性尚未解析，返回null或空字符串 - ❌ 禁止往
this.shadowRoot写内容：此时shadowRoot虽已存在，但 DOM 尚未挂载，innerHTML可能被静默丢弃 - ⚠️ 次要但关键：不要在 constructor 里调用
setAttribute—— 即使写了，attributeChangedCallback也不会触发，因为元素还没连接到文档
真正渲染模板的逻辑，应挪到 connectedCallback 里。
attributeChangedCallback 为什么没反应
它不是监听器，而是一个受控回调：只响应 observedAttributes 白名单里的属性，且仅对 HTML 层变更生效（setAttribute、removeAttribute、初始标签内声明），JS 属性赋值（如 el.disabled = true）完全不触发。
- 确认
static get observedAttributes()返回的是字符串数组：return ['loading', 'disabled']，不是对象或单个字符串 - 属性名大小写必须完全一致：
'disabled'≠'Disabled' - 初始属性（如
<my-toggle checked></my-toggle>）会在首次连接时触发一次，但oldValue是null，别直接用===判断 - 如果需要同步 JS 属性变更，得手动补逻辑，比如在 setter 里调用
this.setAttribute('loading', String(value))
Shadow DOM 内样式为何不起作用
Shadow DOM 天然隔离样式，外部 CSS 文件、<style> 块、甚至全局选择器都进不去。想让按钮变色，不能指望页面里写了 button { background: blue }。
- ✅ 正确做法：把
<style>标签直接写进shadowRoot.innerHTML，或创建style元素并 append 进去 - ❌ 错误做法：在外部
<link rel="stylesheet">里定义规则，或试图用element.style.backgroundColor = 'blue'设置 shadow 内部子节点 - ⚠️ 注意：CSS 变量（
--my-color）可穿透 Shadow DOM 边界，适合主题定制，但普通类名和标签选择器不行
最常被忽略的一点：没写 <slot>，外部传入的内容就彻底消失——它不是可选语法糖，而是内容分发的唯一通道。
