报错最常见原因是标签名不合规范：必须小写、含且仅含一个连字符、不以连字符开头或结尾，如my-button合法，mybutton、-my-button、my-button-均非法；其次类未继承htmlelement或constructor中未调用super()也会导致注册失败。
原生 HTML 组件化不是“加个 class 就完事”，而是用 customElements.define() 让浏览器真正认识你的标签；不注册，<product-grid></product-grid> 就只是个无语义的 <div>，连屏幕阅读器都跳过它。
<h3>为什么 <code><my-button></my-button> 会报错：Failed to execute 'define' on 'CustomElementRegistry'
最常见原因是标签名不合规范。浏览器靠连字符区分原生与自定义元素，mybutton、MyButton、button-my 全部非法——必须是小写 + 至少一个连字符，且不能以连字符开头或结尾。
-
my-button✅ -
loading-indicator✅ -
data-table✅ -
myButton❌（缺连字符） -
-my-button❌（开头是连字符） -
my-button-❌（结尾是连字符）
另一个高频错误是类没继承 HTMLElement，或忘了在 constructor 里调 super() —— 这会导致原型链断裂，浏览器直接拒绝实例化。
connectedCallback 和 constructor 到底该放什么逻辑
constructor 只做三件事：调 super()、初始化属性、调 this.attachShadow()。DOM 操作、事件绑定、获取父节点、读取 innerHTML 全部禁止——此时元素还没插入文档，this.parentNode 是 null，this.innerHTML 为空字符串。
所有依赖 DOM 存在的逻辑，必须挪到 connectedCallback：
- 绑定点击/输入事件
- 读取初始属性值并同步到 shadow 内部（比如
this.getAttribute('size')） - 触发首次渲染补全（因为
attributeChangedCallback不会响应初始属性） - 请求数据或启动轮询（避免在未挂载时浪费资源）
顺带一提：disconnectedCallback 不是可选项——定时器、addEventListener、ResizeObserver 都得在这儿清理，否则内存泄漏肉眼可见。
Shadow DOM 里样式怎么写才不被外部污染，又能让用户定制
Shadow DOM 默认隔离样式，但很多人误以为把 <style></style> 塞进 shadow.innerHTML 就万事大吉。其实有三个关键点：
- 样式必须内联注入，
<link rel="stylesheet">在 shadow 中无效 - 用
:host控制组件自身样式，比如:host([disabled]) { opacity: 0.5; } - 暴露 CSS 自定义属性（
--my-button-bg）供外部覆盖，比硬编码颜色更灵活 - 慎用
/deep/或::slotted穿透，它们破坏封装性，也难调试
例如，一个按钮组件想让用户改背景色，别写死 background: #007bff，而是在 <style></style> 里写 button { background: var(--my-button-bg, #007bff); }，然后由使用者通过 style="--my-button-bg: #ff6b6b;" 覆盖。
IE 和微信 X5 内核到底能不能用自定义元素
不能。IE 完全不支持 customElements.define()，哪怕加了 webcomponents.js polyfill，也只勉强撑到 IE11，且首屏解析明显变慢。微信内置浏览器（X5 内核）要看版本：≥ 0.4.8.90（对应 Chromium 71+）才支持基本 Custom Elements v1；低于这个版本，<loading-button is="button"></loading-button> 这种 is 扩展语法直接失效，只能退回到 autonomous 元素（如 <loading-button></loading-button>）+ 手动模拟语义和行为。
更现实的问题是 SSR：服务端若未提前执行 customElements.define()，老版解析器可能直接丢弃未识别标签；现代框架如 Lit 或 Shoelace 已内置预定义处理，但纯原生方案得自己在服务端注入注册脚本或降级为 <div is="loading-button"> 这类兼容写法。
<p>真正容易被忽略的，是可访问性必须随组件一起封装——<code><collapsible-section></collapsible-section> 不光要展开动画，还得默认带 role="region"、同步 aria-expanded、响应 Enter 和 Space 键。漏掉这一条，再漂亮的组件对残障用户也是黑盒。
