Web Components 实战：从原生 API 到跨框架复用

使用时就很朴素，哪个框架里都能塞进去：

<user-card
  avatar="https://api.uomg.com/api/rand.avatar"
  name="Fruge"
>
  <p slot="desc">Senior Frontend Developer</p>
</user-card>

Shadow DOM 为什么重要

Web Components 最容易被提到的就是 Shadow DOM。它的作用不复杂：把组件内部的 DOM 和样式隔开。

• 外部样式默认进不来，组件内部不会轻易被全局 CSS 影响。
• 组件内部的样式也不会往外扩散，减少命名冲突。

以前为了避免样式打架，常见做法是 BEM、CSS Modules，或者把命名写得很长很绕。Shadow DOM 是从浏览器层面解决这件事，省掉了很多约定成本。不过它也不是完全'无脑更好'，因为隔离太强，后面做主题定制时往往要额外暴露 CSS 变量。

Slot 的用法很像你熟悉的插槽

Web Components 里的 <slot> 负责内容分发，和 Vue 的插槽思路很接近。

• <slot> 是默认插槽。
• <slot name="xxx"> 是具名插槽。

这部分上手基本没有门槛，真正需要适应的是：组件边界一旦清晰了，外部就别想再随便改内部结构，这和很多人平时在框架里'直接改子组件 DOM'的习惯不太一样。

裸写原生 API 能做，但不算轻松

如果只写一个演示组件，原生 API 没什么问题。可一旦组件复杂起来，手动维护 DOM 更新、事件派发、属性同步，代码会很快变碎。Lit 这类轻量库的意义就在这里：它不替你发明一套新组件模型，只是把原生 Web Components 写起来顺手一点。

import { LitElement, html, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';

@customElement('simple-counter')
export class SimpleCounter extends LitElement {
  static styles = css`
    button {
      color: blue;
    }
  `;

  @property({ type: Number }) count = 0;

  render() {
    return html`
      <p>Count: ${this.count}</p>
      <button @click="${this._increment}">+</button>
    `;
  }

  private _increment() {
    this.count++;
    // 触发自定义事件
    this.dispatchEvent(
      new CustomEvent('count-changed', {
        detail: this.count,
        bubbles: true,
        composed: true // 允许穿透 Shadow DOM
      })
    );
  }
}

这段代码的关键点不是 Lit 本身有多神，而是它保留了 Web Components 的标准能力，同时把模板渲染、属性更新这些麻烦事收拢了。对于实际项目，我一般会更倾向这种写法，而不是从头手搓原生 API——不是因为原生不行，而是维护成本会更快暴露出来。

跟框架集成时，差异主要在事件和属性

Vue 2 / 3

Vue 对自定义元素的兼容性比较顺手。只要在构建配置里把 compilerOptions.isCustomElement 设好，编译器就不会把它当成未知标签报错。

<simple-counter :count="count" @count-changed="handleCount" />

Vue 的问题通常不在'能不能用'，而在'你想怎么把事件和响应式状态接起来'。这部分只要把自定义事件名设计得清楚，基本没什么额外成本。

React 16 / 17 / 18

React 这边就更别扭一点，主要卡在两处。

• 属性传递：React 会倾向把 props 当成 HTML attribute 处理，复杂对象不太好直接传。
• 事件监听：React 的合成事件系统不会天然接住 Web Component 的自定义事件。

所以常见做法是用 ref 去拿实例，再手动设置属性、绑定事件。写法不算优雅，但能工作。React 19 之后这一块改善了不少，实际使用时会轻松很多。

什么时候适合用 Web Components

如果只是单一技术栈里的普通业务组件，直接用框架自带方案通常更省事。Web Components 更适合这几类场景：

• 跨技术栈组件库，需要在不同前端项目里复用同一套基础 UI。
• 微前端，子应用框架不统一，但希望有一层稳定的共享组件边界。
• 嵌入式组件，比如聊天窗口、反馈按钮、活动浮层，部署到第三方站点时不想被宿主框架绑死。

它的边界也很明显。SSR 这块还没有完全成熟，Declarative Shadow DOM 只能算是往前走了一步；样式定制需要提前设计好变量和主题接口；无障碍支持也不能指望浏览器帮你兜底，焦点管理和 ARIA 还得自己补。

结尾

Web Components 的定位其实很清楚：它不是来和 React、Vue 抢饭碗的，而是给'跨框架复用'这件事提供一个真正标准化的出口。做设计系统、做微前端、做可嵌入式组件时，它比单纯依赖框架更稳一些。代价也有，开发体验没有框架那么顺手，样式和交互边界要设计得更仔细，但这些都属于能提前算清楚的成本。