Web Components 封装实战：打造可复用的跨框架组件

在 React、Vue、Angular 三分天下的今天，组件化开发早已深入人心。但你是否遇到过这样的场景：公司内部既有 Vue2/3 项目，也有 React 项目，还需要维护一些 jQuery 老系统。为了保持 UI 风格统一，难道要为每个框架都写一套组件库吗？

Web Components 提供了一种标准化的解决方案：它允许你创建可重用的自定义元素，这些元素在任何框架中都能像原生 HTML 标签一样工作。本文将带你从零实现一个 Web Component，并探讨其在微前端与跨框架场景下的应用。

TL;DR

核心三剑客：Custom Elements（自定义标签）、Shadow DOM（样式隔离）、HTML Templates（结构复用）。

生命周期：connectedCallback（挂载）、disconnectedCallback（卸载）、attributeChangedCallback（属性变化）。

跨框架：在 Vue 中直接用 <my-btn>，在 React 中需处理自定义事件的兼容性。

最佳实践：推荐使用 Lit 等轻量库简化开发，而非裸写原生 API。

1. 原生实现：手写一个 UserCard 组件

我们来实现一个 <user-card> 组件，支持 avatar 和 name 属性，且样式不被外部污染。

使用方式

无论是在 React、Vue 还是纯 HTML 中，都可以直接这样用：

2. 核心技术深度解析

Shadow DOM：真正的样式隔离

在 Web Components 之前，为了防止样式冲突，我们不得不使用 BEM 命名规范或 CSS Modules。Shadow DOM 从浏览器层面解决了这个问题：

• 外部进不去：全局 CSS 无法影响 Shadow Root 内部（除了 CSS 变量）。

• 内部出不来：组件内的样式也不会污染全局。

Slot 插槽机制

Web Components 的插槽机制与 Vue 非常相似（事实上 Vue 的插槽设计灵感正来源于此）：

• <slot>：默认插槽。

• <slot name="xxx">：具名插槽。

3. 进阶：使用 Lit 简化开发

裸写原生 API 比较繁琐（如手动 diff 更新 DOM）。Google 推出的 Lit 库（前身是 Polymer）极大地简化了这一过程，它基于 lit-html 渲染引擎，体积极小。

4. 框架集成指南

Vue (2.x / 3.x)

Vue 对 Web Components 的支持非常完美。

• 配置：在 Vite/Webpack 中配置 compilerOptions.isCustomElement，告诉 Vue 编译器哪些标签是自定义元素，不要报错。

• 绑定：

React (16/17/18)

React 在 19 之前对 Web Components 的支持略显尴尬，主要在于事件系统和属性传递。

• 属性：React 会将所有 props 当作 HTML Attribute（字符串）传递，无法传递复杂对象（数组/对象）。需使用 ref 手动赋值。

• 事件：React 的合成事件系统无法监听 Web Component 的自定义事件。需使用 useRef + addEventListener。

• React 19+：已全面改善对 Web Components 的支持，上述问题基本解决。

5. 适用场景与局限性

适用场景

• 跨技术栈组件库：公司内部有多种技术栈，需要统一的 UI 基础组件（Button, Icon, Input）。

• 微前端：在微前端架构中，子应用可能使用不同框架，Web Components 是天然的隔离边界。

• 嵌入式微件：如聊天窗口、反馈按钮，可直接嵌入任意第三方网站。

• 局限性

• SSR 支持：Shadow DOM 的服务端渲染（SSR）目前仍处于实验阶段（Declarative Shadow DOM）。

• 样式定制：由于强隔离，外部很难通过 CSS 覆盖内部样式，通常需要组件暴露大量的 CSS Variables 供外部调整。

• 无障碍性 (A11y)：需要手动处理 Shadow DOM 内部的焦点管理和 ARIA 属性。

6. 总结

Web Components 不是为了取代 React/Vue，而是为了补充组件互操作性的缺失。在构建设计系统（Design System）或跨框架微前端应用时，它是一个极具前瞻性的选择。