Web Components自定义元素与Shadow DOM封装实战

Web Components技术栈与浏览器原生支持现状

前端开发中，组件封装一直是核心诉求。Web Components是W3C标准化的浏览器原生组件方案，包含Custom Elements、Shadow DOM、HTML Templates三个核心规范。与React/Vue等框架组件不同，Web Components不依赖任何框架运行时，直接由浏览器渲染引擎支持，可跨框架使用。

截至2026年，Chrome、Edge、Firefox、Safari均完整支持Web Components三件套。CSS层面的:host、::slotted、::part伪元素在各浏览器行为一致，CSS Shadow Parts规范也已全面落地。可以说Web Components已从”实验特性”进入”生产可用”阶段。

Web Components的适用场景：设计系统基础组件（按钮、输入框、卡片等跨团队共享组件）、微前端架构中的跨应用隔离组件、第三方嵌入式组件（支付表单、评论框等需样式隔离的场景）。不适合替代React/Vue的完整应用开发，更适合作为框架无关的底层组件方案。

Custom Elements自定义元素注册与生命周期

自定义元素通过customElements.define()注册，命名必须包含连字符（如my-button），避免与HTML原生元素冲突。生命周期回调包括connectedCallback、disconnectedCallback、attributeChangedCallback、adoptedCallback。

class MyTooltip extends HTMLElement {
  static get observedAttributes() {
    return ['content', 'position'];
  }

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this._visible = false;
  }

  connectedCallback() {
    this.render();
    this._target = this.previousElementSibling || this.parentElement;
    this._target.addEventListener('mouseenter', () => this.show());
    this._target.addEventListener('mouseleave', () => this.hide());
  }

  attributeChangedCallback(name, oldVal, newVal) {
    if (oldVal !== newVal && this.isConnected) {
      this.render();
    }
  }

  disconnectedCallback() {
    this._target?.removeEventListener('mouseenter', this._showHandler);
    this._target?.removeEventListener('mouseleave', this._hideHandler);
  }

  get content() { return this.getAttribute('content') || ''; }
  set content(val) { this.setAttribute('content', val); }

  show() {
    this._visible = true;
    this.shadowRoot.querySelector('.tooltip').classList.add('visible');
  }

  hide() {
    this._visible = false;
    this.shadowRoot.querySelector('.tooltip')?.classList.remove('visible');
  }

  render() {
    const pos = this.getAttribute('position') || 'top';
    this.shadowRoot.innerHTML = `
      <style>
        :host { position: relative; display: inline-block; }
        .tooltip {
          position: absolute;
          bottom: ${pos === 'top' ? '100%' : 'auto'};
          top: ${pos === 'bottom' ? '100%' : 'auto'};
          left: 50%;
          transform: translateX(-50%);
          padding: 6px 12px;
          background: #1a1a2e;
          color: #fff;
          font-size: 13px;
          border-radius: 4px;
          white-space: nowrap;
          opacity: 0;
          transition: opacity 0.2s;
          pointer-events: none;
        }
        .tooltip.visible { opacity: 1; }
      </style>
      <div class="tooltip">${this.content}</div>
    `;
  }
}

customElements.define('my-tooltip', MyTooltip);

关键细节：observedAttributes静态方法必须显式声明需要监听的属性列表，否则attributeChangedCallback不会触发。connectedCallback可能被多次调用（元素被DOM移动时），初始化逻辑需做幂等保护。所有DOM操作应在Shadow Root内完成，避免污染外部document。

Shadow DOM样式隔离与穿透机制

Shadow DOM是Web Components样式隔离的核心机制。Shadow Root内的CSS不会泄漏到外部，外部样式也无法穿透进Shadow Root（:host伪类除外）。这解决了组件库开发中样式冲突的根本问题。

样式穿透的三种机制：

1. :host选择器：从Shadow内部选中宿主元素本身，可接收外部传入的CSS自定义属性。

2. ::slotted()选择器：选中通过slot投射进Shadow DOM的轻量DOM节点，但只能设置直接子元素的样式，无法穿透到子元素内部。

3. CSS Shadow Parts（::part）：在Shadow DOM内部为元素标记part属性，外部通过::part()选择器精准覆盖指定部分的样式，是最灵活的样式定制机制。

// 组件内部定义
this.shadowRoot.innerHTML = `
  <style>
    :host {
      --btn-bg: #4f46e5;
      --btn-radius: 6px;
      display: inline-block;
    }
    .btn {
      background: var(--btn-bg);
      color: #fff;
      padding: 8px 16px;
      border: none;
      border-radius: var(--btn-radius);
      cursor: pointer;
    }
    .btn:focus-visible {
      outline: 2px solid var(--btn-bg);
      outline-offset: 2px;
    }
    .icon { padding-right: 4px; }
  </style>
  <button class="btn" part="button">
    <span class="icon" part="icon"><slot name="icon"></slot></span>
    <slot></slot>
  </button>
`;

// 外部使用时覆盖样式
// my-button::part(button) { background: #dc2626; }
// my-button { --btn-radius: 12px; }

表单组件与ElementInternals API

Web Components参与表单提交一直是个痛点，ElementInternals API解决了这个问题。通过attachInternals()获取表单关联能力，自定义元素可以像原生input一样被form序列化和校验。

class MyRating extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this._internals = this.attachInternals();
    this._value = 0;
  }

  connectedCallback() {
    this.render();
    this._internals.setFormValue(this._value);
    this._internals.setValidity(
      { customError: this._value === 0 },
      this._value === 0 ? '请选择评分' : ''
    );
  }

  render() {
    const stars = [1,2,3,4,5].map(i => {
      const cls = i <= this._value ? 'star active' : 'star';
      return '<span class="' + cls + '" data-value="' + i + '">★</span>';
    }).join('');
    this.shadowRoot.innerHTML = `
      <style>
        :host { display: inline-flex; gap: 4px; cursor: pointer; }
        .star { font-size: 24px; color: #d1d5db; transition: color 0.15s; }
        .star.active { color: #f59e0b; }
      </style>
      ${stars}
    `;
    this.shadowRoot.querySelectorAll('.star').forEach(star => {
      star.addEventListener('click', (e) => {
        this._value = parseInt(e.target.dataset.value);
        this._internals.setFormValue(this._value);
        this._internals.setValidity({});
        this.render();
      });
    });
  }
}

customElements.define('my-rating', MyRating);

ElementInternals的setFormValue()让自定义组件的值随form提交发送，setValidity()实现自定义校验逻辑。form属性指向关联的form元素，name属性用于表单序列化的字段名。这使Web Components能完整参与表单工作流，填补了此前最大的功能缺口。

与框架集成及性能优化建议

Web Components在React中使用需注意：React 18及之前版本无法直接将HTML属性传给自定义元素的事件监听器，需封装一层wrapper组件。Vue 3通过v-model和@event天然支持自定义元素属性和事件绑定，集成体验更好。

性能优化方面：避免在attributeChangedCallback中做重量级DOM重建，改用差量更新；大量列表渲染时使用DocumentFragment批量插入；Shadow DOM内的模板如果不会变化，可通过template元素预定义后cloneNode复用，减少innerHTML解析开销。