Web Components 实战指南：构建框架无关的可复用组件

2026 年，前端框架大战仍在继续，但一个被低估的浏览器原生能力正在悄然成熟——Web Components。根据 HTTP Archive 的数据，全球排名前 100 万的网站中，有 12.3% 使用了至少一个 Custom Element，较 2023 年增长了 47%。YouTube、GitHub、Adobe Spectrum、Microsoft Fluent UI 等大型项目早已将 Web Components 作为核心基础设施。如果你还在纠结「React 组件还是 Vue 组件」，或许应该换个思路：构建一个框架无关的组件库，让技术选型不再绑架你的组件资产。

Web Components 不是要取代 React 或 Vue，而是在「跨框架复用」和「长期维护」这两个场景下，提供了一个浏览器原生的、零依赖的解决方案。对于需要在多个项目间共享 UI 组件的团队来说，这是一个非常有吸引力的选择。

📌 记住： Web Components 是浏览器原生标准，不需要任何框架或运行时。这意味着你的组件可以在任何环境下运行——无论是 React 项目、Vue 项目、甚至纯 HTML 页面。

🧩 一、三大核心 API 深度解析

Web Components 由三个独立的浏览器标准组成，理解它们各自的职责和边界是正确使用的关键。很多开发者在初次接触时容易混淆三者的定位，导致使用方式不当。

1.1 Custom Elements：自定义 HTML 标签

Custom Elements API 让你注册自己的 HTML 标签，并绑定生命周期回调。这是 Web Components 的入口，也是最基础的能力。通过 customElements.define() 方法，你可以将一个 JavaScript 类绑定到一个 HTML 标签名上。

// 定义一个自定义元素 <user-card>
class UserCard extends HTMLElement {
  // 监听的属性变化列表
  static get observedAttributes() {
    return ['name', 'avatar', 'role']
  }

  constructor() {
    super()
    // ⚠️ 注意：constructor 中不要访问 attributes，此时元素还未连接到 DOM
    this._name = ''
    this._avatar = ''
    this._role = ''
  }

  // 元素被插入 DOM 时触发 — 最常用的生命周期
  connectedCallback() {
    this.render()
  }

  // 属性变化时触发 — 实现响应式更新
  attributeChangedCallback(name, oldVal, newVal) {
    if (oldVal !== newVal) {
      this[`_${name}`] = newVal
      if (this.isConnected) {
        this.render()
      }
    }
  }

  // 元素从 DOM 移除时触发 — 清理资源
  disconnectedCallback() {
    console.log('user-card removed')
  }

  render() {
    this.innerHTML = `
      <div class="user-card">
        <img src="${this._avatar}" alt="${this._name}" />
        <h3>${this._name}</h3>
        <span>${this._role}</span>
      </div>
    `
  }
}

// 注册自定义元素 — 标签名必须包含连字符（kebab-case）
customElements.define('user-card', UserCard)

Custom Elements 的生命周期回调是理解组件行为的关键。connectedCallback 在元素插入 DOM 时触发，适合做初始化渲染和事件绑定。disconnectedCallback 在元素移除时触发，适合清理定时器和事件监听器。attributeChangedCallback 则在监听的属性变化时触发，是实现属性驱动更新的核心。

⚠️ 警告： 自定义元素的标签名必须包含连字符（如 user-card、my-button），这是为了避免与未来 HTML 标准标签冲突。使用纯单词如 card 会抛出 DOMException。另外，每个标签名只能注册一次，重复注册会报错。

注册后，可以直接在 HTML 中使用：

<!-- 直接在 HTML 中使用自定义元素 -->
<user-card
  name="张三"
  avatar="https://api.dicebear.com/7.x/avataaars/svg?seed=zhang"
  role="前端工程师"
></user-card>

1.2 Shadow DOM：真正的样式隔离

Shadow DOM 是 Web Components 最强大的特性——它提供了一个封闭的 DOM 子树，内部样式不会泄漏到外部，外部样式也不会侵入内部。这是 CSS-in-JS、CSS Modules 等方案梦寐以求的能力，而浏览器原生就支持。

Shadow DOM 解决了前端开发中最头疼的问题之一：CSS 全局作用域。在传统开发中，一个组件的样式可能意外影响到页面上的其他元素，尤其是类名冲突。Shadow DOM 通过创建一个独立的 DOM 子树，从根本上解决了这个问题。

// 使用 Shadow DOM 实现真正的样式隔离
class ToggleSwitch extends HTMLElement {
  constructor() {
    super()
    // 创建 Shadow Root — open 模式允许外部 JS 访问
    this.attachShadow({ mode: 'open' })
    this._checked = false
  }

  connectedCallback() {
    this.render()
    this.shadowRoot.querySelector('.toggle').addEventListener('click', () => {
      this._checked = !this._checked
      this.setAttribute('checked', this._checked ? 'true' : 'false')
      this.dispatchEvent(new CustomEvent('change', {
        detail: { checked: this._checked },
        bubbles: true,  // 允许事件冒泡到外部
        composed: true  // 允许事件穿透 Shadow DOM 边界
      }))
    })
  }

  render() {
    // 样式完全封装在 Shadow DOM 内部，不会影响外部
    this.shadowRoot.innerHTML = `
      <style>
        :host {
          display: inline-block;
          cursor: pointer;
          user-select: none;
        }
        .toggle {
          width: 48px;
          height: 24px;
          border-radius: 12px;
          background: #ccc;
          position: relative;
          transition: background 0.3s;
        }
        .toggle.active {
          background: #2563eb;
        }
        .toggle::after {
          content: '';
          width: 20px;
          height: 20px;
          border-radius: 50%;
          background: white;
          position: absolute;
          top: 2px;
          left: 2px;
          transition: transform 0.3s;
        }
        .toggle.active::after {
          transform: translateX(24px);
        }
      </style>
      <div class="toggle ${this._checked ? 'active' : ''}"></div>
    `
  }

  static get observedAttributes() { return ['checked'] }

  attributeChangedCallback(name, oldVal, newVal) {
    if (name === 'checked') {
      this._checked = newVal === 'true'
      if (this.isConnected) this.render()
    }
  }
}

customElements.define('toggle-switch', ToggleSwitch)

Shadow DOM 的样式隔离不是简单的命名空间隔离，而是真正的 DOM 树隔离。这意味着即使你使用了完全相同的类名，Shadow DOM 内部的样式和外部的样式也不会互相干扰。

Shadow DOM 提供了一组特殊的 CSS 伪类选择器，用于控制组件与外部环境的交互：

💡 提示： Shadow DOM 的样式隔离是「双向」的——组件内部的 CSS 不会影响外部页面，外部的全局样式（如 * { margin: 0 }）也不会穿透进组件。这意味着你可以放心地在组件中使用任意类名，无需担心冲突。同时，CSS Custom Properties（CSS 变量）是唯一可以穿透 Shadow DOM 边界的样式机制，这为外部主题定制提供了可能。

1.3 HTML Templates 与 Slots：内容分发机制

<template> 和 <slot> 提供了声明式的内容分发能力，类似于 Vue 的 <slot> 或 React 的 children。它们解决了组件内容灵活性的问题——允许使用者向组件内部插入自定义内容。

<template> 元素在被克隆之前不会渲染，这使得它非常适合作为组件的模板。而 <slot> 则定义了内容插入的占位符，分为默认插槽和具名插槽两种。

// 使用 <template> + <slot> 构建一个卡片组件
const cardTemplate = document.createElement('template')
cardTemplate.innerHTML = `
  <style>
    :host {
      display: block;
      border: 1px solid #e5e7eb;
      border-radius: 8px;
      overflow: hidden;
      font-family: system-ui, sans-serif;
    }
    .card-header {
      padding: 16px;
      border-bottom: 1px solid #e5e7eb;
      background: #f9fafb;
    }
    .card-body {
      padding: 16px;
    }
    .card-footer {
      padding: 12px 16px;
      border-top: 1px solid #e5e7eb;
      background: #f9fafb;
    }
    /* 具名 slot 样式 */
    ::slotted([slot="header"]) {
      margin: 0;
      font-size: 18px;
      font-weight: 600;
    }
  </style>
  <div class="card-header">
    <slot name="header">默认标题</slot>
  </div>
  <div class="card-body">
    <slot>默认内容</slot>
  </div>
  <div class="card-footer">
    <slot name="footer"></slot>
  </div>
`

class AppCard extends HTMLElement {
  constructor() {
    super()
    this.attachShadow({ mode: 'open' })
    this.shadowRoot.appendChild(cardTemplate.content.cloneNode(true))
  }
}

customElements.define('app-card', AppCard)

使用时通过 slot 属性分发内容。这种模式非常灵活，使用者可以自由决定插入哪些内容：

<!-- 具名插槽分发内容 -->
<app-card>
  <h2 slot="header">用户信息</h2>
  <p>姓名：张三</p>
  <p>职位：高级前端工程师</p>
  <div slot="footer">
    <button>编辑</button>
    <button>删除</button>
  </div>
</app-card>

⚡ 二、生产级组件实战

理解了基础 API 后，我们来构建几个有实际价值的组件，覆盖常见的 UI 模式。这些组件不仅仅是演示，而是可以直接在生产环境中使用的实现。

2.1 可排序数据表格组件

数据表格是后台系统最常用的组件。我们用 Web Components 实现一个支持排序、分页的轻量表格，展示如何组合多个 API 来构建复杂组件。

// 可排序数据表格组件
class DataTable extends HTMLElement {
  static get observedAttributes() { return ['page-size'] }

  constructor() {
    super()
    this.attachShadow({ mode: 'open' })
    this._columns = []
    this._data = []
    this._sortKey = ''
    this._sortDir = 'asc'
    this._currentPage = 1
    this._pageSize = 10
  }

  // 外部 API：设置列定义
  set columns(cols) {
    this._columns = cols
    this._render()
  }

  // 外部 API：设置数据
  set data(rows) {
    this._data = rows
    this._currentPage = 1
    this._render()
  }

  connectedCallback() {
    // 使用事件委托处理排序点击
    this.shadowRoot.addEventListener('click', (e) => {
      const th = e.target.closest('th[data-sort]')
      if (th) {
        const key = th.dataset.sort
        if (this._sortKey === key) {
          this._sortDir = this._sortDir === 'asc' ? 'desc' : 'asc'
        } else {
          this._sortKey = key
          this._sortDir = 'asc'
        }
        this._render()
      }
    })
  }

  _getSortedData() {
    if (!this._sortKey) return this._data
    return [...this._data].sort((a, b) => {
      const va = a[this._sortKey] ?? ''
      const vb = b[this._sortKey] ?? ''
      const cmp = typeof va === 'number' ? va - vb : String(va).localeCompare(String(vb))
      return this._sortDir === 'asc' ? cmp : -cmp
    })
  }

  _getPageData() {
    const sorted = this._getSortedData()
    const start = (this._currentPage - 1) * this._pageSize
    return sorted.slice(start, start + this._pageSize)
  }

  _render() {
    const pageData = this._getPageData()
    const totalPages = Math.ceil(this._data.length / this._pageSize)

    this.shadowRoot.innerHTML = `
      <style>
        :host { display: block; font-family: system-ui, sans-serif; }
        table { width: 100%; border-collapse: collapse; font-size: 14px; }
        th, td { padding: 10px 12px; text-align: left; border-bottom: 1px solid #e5e7eb; }
        th { background: #f8fafc; cursor: pointer; user-select: none; white-space: nowrap; }
        th:hover { background: #e2e8f0; }
        .sort-icon { margin-left: 4px; opacity: 0.3; }
        .sort-icon.active { opacity: 1; }
        tr:hover td { background: #f1f5f9; }
        .pagination { display: flex; gap: 8px; justify-content: center; padding: 12px; }
        button { padding: 4px 12px; border: 1px solid #d1d5db; border-radius: 4px;
                 background: white; cursor: pointer; }
        button:disabled { opacity: 0.5; cursor: default; }
        button.active { background: #2563eb; color: white; border-color: #2563eb; }
      </style>
      <table>
        <thead>
          <tr>
            ${this._columns.map(col => `
              <th data-sort="${col.key}">
                ${col.label}
                <span class="sort-icon ${this._sortKey === col.key ? 'active' : ''}">
                  ${this._sortKey === col.key
                    ? (this._sortDir === 'asc' ? '↑' : '↓')
                    : '↕'}
                </span>
              </th>
            `).join('')}
          </tr>
        </thead>
        <tbody>
          ${pageData.map(row => `
            <tr>
              ${this._columns.map(col => `<td>${row[col.key] ?? ''}</td>`).join('')}
            </tr>
          `).join('')}
        </tbody>
      </table>
      <div class="pagination">
        <button ${this._currentPage <= 1 ? 'disabled' : ''}
                onclick="this.getRootNode().host._goPage(${this._currentPage - 1})">上一页</button>
        ${Array.from({ length: totalPages }, (_, i) => `
          <button class="${i + 1 === this._currentPage ? 'active' : ''}"
                  onclick="this.getRootNode().host._goPage(${i + 1})">${i + 1}</button>
        `).join('')}
        <button ${this._currentPage >= totalPages ? 'disabled' : ''}
                onclick="this.getRootNode().host._goPage(${this._currentPage + 1})">下一页</button>
      </div>
    `
  }

  _goPage(page) {
    const totalPages = Math.ceil(this._data.length / this._pageSize)
    this._currentPage = Math.max(1, Math.min(page, totalPages))
    this._render()
  }
}

customElements.define('data-table', DataTable)

使用示例——只需几行代码就能渲染一个功能完整的数据表格：

// 使用 data-table 组件
const table = document.querySelector('data-table')
table.columns = [
  { key: 'name', label: '姓名' },
  { key: 'dept', label: '部门' },
  { key: 'salary', label: '薪资' },
]
table.data = [
  { name: '张三', dept: '技术部', salary: 25000 },
  { name: '李四', dept: '产品部', salary: 22000 },
  { name: '王五', dept: '设计部', salary: 20000 },
  { name: '赵六', dept: '技术部', salary: 28000 },
  { name: '钱七', dept: '市场部', salary: 18000 },
]

⚡ 关键结论： this.getRootNode().host 是在 Shadow DOM 内部访问宿主元素的标准方式。这比 document.querySelector 更安全，因为它不会意外访问到其他组件的 Shadow DOM。在 Shadow DOM 内部，所有 DOM 查询都被限制在当前组件范围内。

2.2 主题感知的 Toast 通知

Toast 通知是另一个高频需求。我们实现一个支持主题继承、自动消失、堆叠排列的 Toast 组件。这个组件展示了如何用单例模式管理全局 UI 状态。

// 全局 Toast 管理器（单例模式）
class ToastContainer extends HTMLElement {
  constructor() {
    super()
    this.attachShadow({ mode: 'open' })
    this.shadowRoot.innerHTML = `
      <style>
        :host {
          position: fixed;
          top: 16px;
          right: 16px;
          z-index: 99999;
          display: flex;
          flex-direction: column;
          gap: 8px;
          pointer-events: none;
        }
        .toast {
          padding: 12px 20px;
          border-radius: 8px;
          color: white;
          font-family: system-ui, sans-serif;
          font-size: 14px;
          box-shadow: 0 4px 12px rgba(0,0,0,0.15);
          pointer-events: auto;
          animation: slideIn 0.3s ease;
          max-width: 360px;
          word-break: break-word;
        }
        .toast.info { background: #3b82f6; }
        .toast.success { background: #10b981; }
        .toast.error { background: #ef4444; }
        .toast.hiding { animation: fadeOut 0.3s ease forwards; }
        @keyframes slideIn {
          from { transform: translateX(100%); opacity: 0; }
          to { transform: translateX(0); opacity: 1; }
        }
        @keyframes fadeOut {
          to { transform: translateX(100%); opacity: 0; }
        }
      </style>
    `
  }
}

customElements.define('toast-container', ToastContainer)

// 静态工具方法 —— 全局单例
const Toast = {
  _container: null,

  _ensure() {
    if (!this._container) {
      this._container = document.createElement('toast-container')
      document.body.appendChild(this._container)
    }
    return this._container
  },

  show(message, type = 'info', duration = 3000) {
    const container = this._ensure()
    const el = document.createElement('div')
    el.className = `toast ${type}`
    el.textContent = message
    container.shadowRoot.appendChild(el)

    setTimeout(() => {
      el.classList.add('hiding')
      el.addEventListener('animationend', () => el.remove())
    }, duration)
  },

  success(msg) { this.show(msg, 'success') },
  error(msg) { this.show(msg, 'error', 5000) },
  info(msg) { this.show(msg, 'info') },
}

// 全局使用 —— 无需手动创建 DOM 元素
Toast.success('保存成功！')
Toast.error('网络连接失败，请重试')
Toast.info('正在加载数据...')

🔗 三、框架集成与工程化

Web Components 最大的价值在于「写一次，到处用」。但它与主流框架的集成有一些需要注意的坑，处理不当会导致数据传递失败或事件丢失。

3.1 与 React 集成

React 对 Web Components 的支持有一个老问题：React 不会自动将 props 传递为 HTML attributes，它默认传递的是 JS properties。对于基本类型字符串，这通常没问题；但对于对象和数组，必须通过 ref 手动设置。

// React 中使用 Web Components 的正确方式
import { useRef, useEffect } from 'react'

function UserList() {
  const tableRef = useRef(null)

  // ✅ 正确做法：通过 ref 设置 JS properties（复杂数据必须这样做）
  useEffect(() => {
    if (tableRef.current) {
      tableRef.current.columns = [
        { key: 'name', label: '姓名' },
        { key: 'email', label: '邮箱' },
      ]
      tableRef.current.data = [
        { name: '张三', email: 'zhang@example.com' },
        { name: '李四', email: 'li@example.com' },
      ]
    }
  }, [])

  // ❌ 错误写法：React 不会把对象类型的 prop 设为 attribute
  // <data-table columns={columns} data={data} />

  // ✅ 正确写法：基本类型用 attribute，复杂类型用 ref
  return (
    <div>
      <data-table ref={tableRef} page-size="10" />
      <button onClick={() => Toast.success('来自 React 的消息')}>
        显示 Toast
      </button>
    </div>
  )
}

⚠️ 警告： React 18 对 Custom Elements 的事件监听支持不完善。CustomEvent 的 detail 属性不会自动映射，需要在 useEffect 中手动 addEventListener。React 19 改善了这一问题，但仍建议优先使用 ref 方式来传递复杂数据。

3.2 与 Vue 集成

Vue 3 对 Web Components 的支持非常好，只需要在 Vite 配置中告诉编译器哪些标签是自定义元素即可。Vue 会自动处理属性绑定和事件监听。

// vite.config.js — Vue 3 中使用 Web Components
import vue from '@vitejs/plugin-vue'

export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // 告诉 Vue 编译器将 data-table 视为自定义元素，不做组件解析
          isCustomElement: (tag) => tag.includes('-')
        }
      }
    })
  ]
}

配置后可以直接在 Vue 模板中使用，Vue 会自动将 v-bind 绑定的属性设置为 HTML attributes：

<!-- Vue 3 模板中直接使用 -->
<template>
  <div>
    <toggle-switch
      :checked="isEnabled"
      @change="handleChange"
    />
    <data-table
      ref="tableRef"
      page-size="5"
    />
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'

const tableRef = ref(null)
const isEnabled = ref(false)

// Vue 可以直接监听 CustomEvent
const handleChange = (e) => {
  isEnabled.value = e.detail.checked
}

onMounted(() => {
  // 通过 ref 设置复杂数据
  tableRef.value.columns = [
    { key: 'id', label: 'ID' },
    { key: 'name', label: '名称' },
  ]
  tableRef.value.data = [
    { id: 1, name: '项目 A' },
    { id: 2, name: '项目 B' },
  ]
})
</script>

3.3 性能对比：Web Components vs 框架组件

以下是基于 Chrome DevTools 的性能测试数据，对比不同方案渲染 1000 个列表项的开销。测试环境为 Chrome 125，M1 MacBook Pro：

从数据可以看出，Web Components 在包大小和内存占用上有明显优势，因为它不需要任何运行时。但要注意，由于没有虚拟 DOM 和事件代理机制，在需要频繁更新大量节点的场景下性能可能不如框架组件。

💡 提示： Web Components 的包大小优势来自于「零运行时依赖」。建议在低频更新、高复用性的组件场景中使用 Web Components，而对于需要复杂状态管理和高频更新的页面级逻辑，仍然推荐使用框架。

🛠️ 四、避坑指南与最佳实践

在实际项目中使用 Web Components，有一些常见的坑需要避免，同时也有一些经过验证的最佳实践值得遵循。

❌ 常见错误

• ❌ 在 constructor 中访问 attributes：元素还未连接到 DOM，getAttribute() 返回 null，应该在 connectedCallback 中读取
• ❌ 忘记设置 composed: true：CustomEvent 无法穿透 Shadow DOM 边界，外部事件监听器收不到
• ❌ 在 Shadow DOM 中使用 document.querySelector：永远查不到内部元素，应该用 this.shadowRoot.querySelector
• ❌ 注册前就使用标签：浏览器会当作未知元素处理，确保 customElements.define() 在使用前调用
• ❌ 在 attributeChangedCallback 中做复杂操作：这个回调可能被频繁触发，应该做防抖处理

✅ 最佳实践清单

• ✅ 使用 <template> 而非 innerHTML 拼接，性能更好且更安全
• ✅ 通过 CSS Custom Properties（--var）实现有限的外部主题定制
• ✅ 使用 delegatesFocus: true 让 Shadow DOM 支持焦点管理
• ✅ 用 formAssociated 让自定义元素参与原生表单提交
• ✅ 用 ::part() 暴露可控的样式钩子，让用户有限度地自定义样式

// formAssociated：让自定义元素参与原生表单提交
class MyInput extends HTMLElement {
  static formAssociated = true  // 声明关联表单

  constructor() {
    super()
    this.internals = this.attachInternals()  // 获取 ElementInternals
    this.attachShadow({ mode: 'open' })
  }

  connectedCallback() {
    this.shadowRoot.innerHTML = `
      <style>
        :host { display: inline-block; }
        input { padding: 8px 12px; border: 1px solid #d1d5db; border-radius: 6px;
                font-size: 14px; outline: none; }
        input:focus { border-color: #2563eb; box-shadow: 0 0 0 3px rgba(37,99,235,0.1); }
      </style>
      <input type="text" />
    `
    this.shadowRoot.querySelector('input').addEventListener('input', (e) => {
      // 使用 ElementInternals 设置表单值
      this.internals.setFormValue(e.target.value)
    })
  }
}

customElements.define('my-input', MyInput)

<!-- 像普通表单元素一样使用，参与原生表单提交 -->
<form id="myForm">
  <my-input name="username"></my-input>
  <button type="submit">提交</button>
</form>

<script>
document.getElementById('myForm').addEventListener('submit', (e) => {
  e.preventDefault()
  const formData = new FormData(e.target)
  console.log(formData.get('username')) // ✅ 可以正常获取值
})
</script>

📌 总结

Web Components 在 2026 年已经不再是「实验性技术」，而是一个经过大规模生产验证的浏览器标准。它最适合以下场景：

• ✅ 跨框架组件库：一套组件同时服务于 React、Vue、Svelte 项目，技术选型变化时无需重写
• ✅ 微前端架构：各子应用独立技术栈，通过 Web Components 共享 UI 组件
• ✅ 嵌入式组件：第三方嵌入场景（如支付组件、评论系统、客服聊天窗口）
• ✅ 设计系统基础层：底层用 Web Components 构建原子组件，上层为各框架封装适配层

不适合的场景：❌ 需要频繁大量 DOM 更新的高性能交互（如虚拟滚动列表）、❌ 深度依赖框架特定能力（如 React Suspense、Vue TransitionGroup）。

⚡ 关键结论： 不要把 Web Components 和框架对立起来。最务实的方案是：用 Web Components 构建基础 UI 原子组件（按钮、输入框、弹窗），用框架构建页面级业务逻辑。这样既能享受框架的开发效率，又能保护组件资产不被框架绑定。

相关资源推荐：

• Lit — Google 出品的 Web Components 轻量框架，推荐用于构建组件库
• Stencil — Ionic 团队出品，支持自动生成 React/Vue/Angular 适配层
• Shoelace — 基于 Web Components 的高质量 UI 组件库
• Open Web Components — Web Components 开发最佳实践集合
• Web Components MDN 文档 — 权威参考文档