自定义元素注册失败主因是命名不合法或继承错误：名称必须含短横线且全小写（如my-button），禁用驼峰、下划线及原生标签名；类必须继承HTMLElement且构造函数调super()，否则触发Illegal constructor或DOMException。
自定义元素不是“又一个前端玩具”，而是让 HTML 本身获得可编程能力的底层升级——它把组件从框架 runtime 里解放出来，变成浏览器原生理解的一等公民。
customElements.define() 注册失败的常见原因
注册失败几乎都卡在命名或继承上，不是代码写错，是浏览器直接拒绝：
-
customElements.define()报错DOMException: The name "mybutton" is not a valid custom element name：名称必须含 ASCII 连字符且全小写，my-button合法，myButton、my_button、button全部非法 - 继承内置元素时漏传
{ extends: 'button' }配置，结果注册成 autonomous 元素，但 HTML 中写了<button is="loading-button"></button>—— 浏览器不识别is属性，当普通 button 渲染，行为完全丢失 - 类名与原生标签重名，比如尝试定义
div、slot、template，会立刻抛出同名冲突错误
constructor 和 connectedCallback 的分工陷阱
很多 bug 源于把 DOM 操作塞进 constructor：此时元素还没挂载，this.shadowRoot 是 null，this.getAttribute() 读不到初始属性，事件监听也白绑。
-
constructor只做三件事：调用super()、创建 shadow root（this.attachShadow({ mode: 'open' })）、初始化私有字段（如this._isLoading = false） - 所有 DOM 查询（
this.querySelector）、属性读取（this.getAttribute('size')）、事件绑定（this.addEventListener）、内容渲染（shadowRoot.innerHTML = ...）必须放在connectedCallback里 - 注意：
attributeChangedCallback不会触发初始属性值变更，首次渲染仍得在connectedCallback中手动读取
样式隔离失效的典型场景
Shadow DOM 的样式隔离不是自动生效的魔法，它依赖显式注入和作用域控制：
立即学习“前端免费学习笔记（深入）”；
- 把
<link rel="stylesheet" href="style.css">放进自定义元素内部或试图用@import加载外部 CSS，基本无效——Shadow DOM 不解析外部 link 标签 - 最稳妥方式是在
connectedCallback中拼接<style>...字符串并插入shadowRoot；复杂样式建议预编译为字符串常量，避免运行时重复解析 - Safari 对
:host-context()和穿透样式支持有限，若需兼容，优先用:host+ 显式 class 控制，少依赖上下文选择器
无障碍与 SEO 的隐性成本
没注册的 <product-grid> 在爬虫和屏幕阅读器眼里就是个空 <div>，语义完全丢失：
- 必须手动补全
role和aria-属性，比如<collapsible-section role="region" aria-expanded="false">，且状态要随交互同步更新 - 服务端渲染时若未预执行
customElements.define()，老版 SSR 工具可能直接丢弃未识别标签（尤其 X5 内核微信浏览器） - SEO 爬虫对自定义标签的语义理解仍弱于标准标签，关键内容建议保留在 light DOM 或通过
slot投影暴露语义结构
真正难的不是写一个能跑的 my-card，而是让它在 Safari 里正确读出 ARIA 状态、在微信里不被 SSR 丢弃、在 Lighthouse 里无障碍评分不掉分——这些细节不写进文档，但决定了它能不能进生产环境。
