HTML前端工程化：自定义元素在组件库中的地位-html教程-PHP中文网

customelements.define() 是组件库交付的最终接口，必须通过它注册自定义元素才能使标签生效；注册需符合命名规范、提前执行、幂等保护；:defined 仅指示注册状态而非样式开关；shadow dom 是样式隔离的物理防线；独立与内置元素选型取决于语义约束力；所有组件须支持无障碍属性且契约稳定。

html前端工程化：自定义元素在组件库中的地位

customElements.define() 是组件库交付的最终接口

设计系统不是一堆 SCSS 文件加文档链接，而是必须能 import 并执行 customElements.define() 的模块。这个调用是让组件“活”进浏览器的唯一路径——没它，<ds-button></ds-button> 就只是个 HTMLUnknownElement，样式不生效、事件不响应、无障碍属性被忽略。

常见错误现象：Uncaught NotSupportedError: Failed to execute 'define' on 'CustomElementRegistry': The name provided ('dsbutton') is not a valid custom element name —— 标签名缺连字符；Uncaught DOMException: Failed to execute 'define' on 'CustomElementRegistry': the element name is not valid —— 名称含大写字母或开头数字。

注册必须在渲染前完成，否则首次渲染降级为未知元素
同一个标签名只能注册一次，重复调用会抛错，包内需做幂等保护（比如先 customElements.get('ds-button') 判断）
推荐把注册逻辑放在模块入口的顶层同步执行，避免 defer 或 DOMContentLoaded 延迟导致样式闪动

:defined 伪类不是样式开关，而是注册状态指示器

:defined 不是“只要写了标签就生效”的样式钩子，它只在 customElements.define() 成功执行且浏览器完成元素升级后才匹配。它本质是浏览器对自定义元素生命周期的公开反馈，不是开发者可控的 CSS 开关。

典型误用：用 my-card:defined { opacity: 1; } 配合 my-card:not(:defined) { opacity: 0; } 做渐显动画——一旦 JS 加载慢或注册失败，页面永远白屏或卡在骨架态。

Wechat HTML Publisher

直接上传HTML富文本到微信公众号草稿箱。支持完整的HTML格式,无需Markdown转换。

下载

开发阶段可用 console.log(customElements.get('my-card')) 直接验证是否已注册成功
不要依赖 :defined 实现样式隔离，它不阻止外部 CSS 继承（如 body { color: red; } 仍会影响内部文字）
大规模项目（>50 个组件）慎用大量 :not(:defined)，频繁节点插入/移除时可能触发 layout thrashing

Shadow DOM 不是可选项，而是样式污染的物理防线

没有 Shadow DOM 的自定义元素，跟带命名空间的 class 名（如 .c-button）没有本质区别——都挡不住 h2 { font-size: 2rem !important; } 这种全局规则穿透。只有 this.attachShadow({ mode: 'closed' }) 才提供浏览器级封装：内部 <style></style> 完全脱离全局级联，外部选择器无法命中任何子节点。

插槽（<slot></slot>）是唯一受控的内容注入点。业务方传入的 HTML 片段只会被分配到指定 slot，不会意外破坏组件结构，也不受外部样式继承干扰。

即使是最简单的 <ds-badge></ds-badge>，只要涉及内嵌文本或图标组合，就必须用 Shadow DOM 隔离
mode: 'closed' 比 'open' 更安全，防止业务方通过 element.shadowRoot 直接篡改内部结构
别为了“方便调试”而默认用 'open'，生产环境应统一设为 'closed'

独立自定义元素 vs 自定义内置元素：选型取决于语义约束力

要不要继承原生元素，关键看组件是否需要承担对应语义责任。<ds-button></ds-button> 必须是独立自定义元素，因为它要完全控制 focus、form submission、键盘交互逻辑；而 <p is="ds-paragraph"></p> 这类扩展，则适合用自定义内置元素——复用 HTMLParagraphElement 的语义和默认行为，只叠加额外样式或文案处理。

注意：自定义内置元素必须显式声明 is 属性，且不能省略原生标签名。写成 <ds-paragraph></ds-paragraph> 会直接报错，浏览器根本不识别。