HTML中如何使用Web Components自定义元素

HTML中如何使用Web Components自定义元素

想在HTML里直接使用Web Components自定义元素？当然可以，但得先满足三个硬性前提，缺一不可：你的类必须继承自HTMLElement、必须调用customElements.define()完成注册，并且标签名里必须包含一个连字符（比如my-button）。如果其中任何一条没做到，浏览器就会把它当作一个没有行为的“未知标签”来处理，你的组件也就白写了。

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

这是浏览器区分原生元素和自定义元素的硬性规则。写成button-x是合法的，但写成buttonx或者ButtonX，浏览器会直接忽略，并在控制台报错：Failed to execute 'define' on 'CustomElementRegistry': The name must contain a hyphen。

• 注册格式：传给define方法的字符串必须全小写且包含连字符，例如customElements.define('user-profile-card', UserProfileCard)。
• 使用一致：在HTML中使用时，标签名必须和注册时完全一致，比如，这里大小写是敏感的。
• 避开保留字：像class、for、slot这类保留字，即使加上连字符也不能用。

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

这里有个常见的“坑”：如果这个标签在HTML中被解析时，对应的customElements.define()还没执行，那么这个元素就会被标记为“未定义”。它虽然会出现在DOM树里，但不会触发constructor或connectedCallback等生命周期回调，而且事后也无法补救。

• 稳妥的做法：将包含define的标签放在所有自定义元素标签之前。或者使用defer属性，确保脚本在文档解析完毕后、DOMContentLoaded事件触发前按顺序执行。
• 动态插入需警惕：在使用innerHTML或类似方式动态插入HTML字符串时，务必确保组件已经注册（先define），再插入字符串，否则新创建的节点不会“升级”为自定义元素。
• 模块化项目的建议：避免在各个组件文件内部单独调用define。最好在应用入口处统一集中注册，这样可以有效防止因重复定义而报错：Failed to execute 'define': the name "x-foo" has already been used。

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

想让你的组件响应disabled或size这类属性的变化？光实现attributeChangedCallback方法还不够。你必须通过静态属性observedAttributes明确告诉浏览器：“请帮我监听这几个属性。”

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

• 声明是必须的：如果漏掉声明，即使设置了，attributeChangedCallback也不会被触发。
• 两种声明方式：可以直接定义静态属性static observedAttributes = ['size', 'disabled'];，或者使用静态getter方法static get observedAttributes() { return ['size', 'disabled']; }。
• 细节决定成败：只监听已声明的属性名。拼写错误（如'disableds'）或大小写不一致（如'Disabled'）都会导致监听无效。
• 触发时机：attributeChangedCallback不会在构造函数constructor中触发。如果元素的初始属性值是在HTML中提供的，那么该回调会在connectedCallback执行之后立即被调用一次。

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

一旦调用了this.attachShadow({ mode: 'open' })，你就创建了一个样式隔离区。写在主文档标签或外部CSS文件里的.btn规则，对影子根（Shadow Root）内部的元素完全不起作用。

• 样式必须内置：组件的样式需要直接内联到影子根内部。可以通过shadowRoot.innerHTML = '
  ...
  '的方式，或者用document.createElement('style')动态创建并插入。
• 样式穿透？有替代方案：外部CSS选择器无法直接穿透Shadow DOM。但你可以使用:host伪类来为自定义元素本身定义样式，用:host(.active)来响应外部添加的类，用:host-context(body.dark)来根据祖先元素（如body有dark类）的上下文条件应用样式。
• 如何利用外部设计系统：如果组件想使用文档中定义的CSS变量（如--primary-color），需要手动读取并传入。例如：getComputedStyle(document.body).getPropertyValue('--primary-color')，然后将获取的值写入影子根内部的样式里。

最后，还有一个最容易被忽略的关键点：生命周期的执行顺序。在constructor构造函数里，你不能操作this.innerHTML，不能使用querySelector查询子元素，也不能添加事件监听器——这些操作都应该挪到connectedCallback方法中进行。在DOM真正挂载之前，任何“想当然”的操作都会静默失败，这是很多初学者踩坑的地方。