HTML中怎样使用Web Components自定义元素

Web Components自定义元素需满足三前提：继承HTMLElement、调用customElements.define()注册、标签名含连字符（如my-button）；否则视为未知标签。

Web Components 自定义元素在 HTML 中能直接使用，但必须满足三个硬性前提：类已继承 HTMLElement、已调用 customElements.define() 注册、标签名含连字符（如 my-button）。缺一不可，否则元素会渲染为无行为的“未知标签”。

自定义标签名必须带连字符

浏览器靠连字符区分原生与自定义元素。写成 button-x 合法，buttonx 或 ButtonX 会被忽略，控制台报错 Failed to execute 'define' on 'CustomElementRegistry': The name must contain a hyphen。

• 注册时传入的字符串必须全小写 + 连字符，例如 customElements.define('user-profile-card', UserProfileCard)
• HTML 中使用也必须完全一致：<user-profile-card></user-profile-card>，大小写敏感
• 不能用保留字，如 class、for、slot 等，即使加了连字符也不行

注册必须在元素被解析前完成

如果 <my-counter></my-counter> 出现在 customElements.define() 调用之前，该元素会被当作“未定义元素”处理——它存在 DOM 中，但不会触发 constructor 或 connectedCallback，后续也无法补救。

• 最稳妥方式：把 define 放在 <script> 标签里，并置于所有自定义标签之前，或用 defer 属性确保执行顺序
• 动态插入场景（如 innerHTML）需格外注意：先 define，再插入字符串，否则新节点不会升级
• 模块化项目中，避免在组件内部单独 define；统一在入口处集中注册，防止重复定义报错 Failed to execute 'define': the name "x-foo" has already been used

属性变更需要显式声明才能响应

想让 attributeChangedCallback 捕获 disabled 或 size 的变化，光写方法不够，还必须通过 observedAttributes 静态属性声明监听列表。

立即学习“前端免费学习笔记（深入）”；

• 漏掉声明会导致属性设了也没反应，例如：<my-input size="large"></my-input> 不触发回调
• 声明方式只有两种：static observedAttributes = ['size', 'disabled'] 或 static get observedAttributes() { return ['size', 'disabled']; }
• 只监听已存在的属性名；拼写错误（如写成 'disableds'）或大小写不一致（'Disabled'）均无效
• attributeChangedCallback 不会在 constructor 中触发，首次属性值由 HTML 提供时，它会在 connectedCallback 之后立即调用一次

Shadow DOM 内容不能靠外部 CSS 选中

一旦调用 this.attachShadow({ mode: 'open' })，内部结构就与主文档样式隔离。写在页面 <style> 里的 .btn 规则对影子根内元素完全无效。

• 样式必须内联到影子根：用 shadowRoot.innerHTML = '<style>...</style><div class="btn">...</div>'，或用 document.createElement('style') 插入
• 想穿透样式？不行。但可用 :host 修饰自定义元素自身，:host(.active) 响应外部 class，:host-context(body.dark) 响应祖先上下文
• 若依赖外部字体、变量，得手动透传，比如读取 getComputedStyle(document.body).getPropertyValue('--primary-color') 再写进 shadow style

最容易被忽略的是生命周期时机：constructor 里不能操作 this.innerHTML、不能查 querySelector、不能监听事件——这些都得挪到 connectedCallback。DOM 挂载前的任何“想当然”的操作，都会变成静默失败。