用WebComponents做跨框架组件库技巧

使用 Web Components 构建一套与框架无关的跨项目 UI 组件库，核心在于利用浏览器原生支持的自定义元素（Custom Elements）、影子 DOM（Shadow DOM）和 HTML 模板（HTML Templates）能力。这些技术组合让组件具备封装性、可复用性和框架兼容性，可在 React、Vue、Angular 或纯 HTML 项目中直接使用。

1. 使用 Custom Elements 定义组件

每个 Web Component 都是一个自定义 HTML 标签，通过 customElements.define() 注册。命名需包含短横线（-），避免与原生标签冲突。

例如，创建一个按钮组件：

class MyButton extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    const label = this.getAttribute('label') || '按钮';
    this.shadowRoot.innerHTML = `
      
        ${label}
      
    `;
  }
}

customElements.define('my-button', MyButton);

之后即可在任意项目中使用：

2. 利用 Shadow DOM 实现样式隔离

Shadow DOM 确保组件内部样式不会影响外部页面，也防止外部 CSS 污染组件。这是实现封装的关键。

建议将样式单独提取，提升可维护性：

connectedCallback() {
  this.shadowRoot.innerHTML = `
    
    
  `;
}

通过 CSS 变量（如 --btn-bg）暴露主题定制能力，外部可通过宿主设置样式变量进行主题适配。

3. 支持插槽（Slot）实现内容分发

使用 允许用户传入自定义内容，提升组件灵活性。

比如支持图标或复杂文本：

this.shadowRoot.innerHTML = `
  
    
    
  
`;

使用方式：

  ▶
  开始播放

4. 封装组件库并发布为 NPM 包

将多个组件组织成库结构：

• components/button.js
• components/input.js
• index.js —— 统一导出所有组件

在 index.js 中批量注册：

import './button.js';
import './input.js';

// 可选：提供一个初始化函数
export function defineComponents() {
  // 可在此添加逻辑，如前缀控制
}

然后打包发布到 NPM：

• 配置 package.json 的 "main" 和 "module"
• 使用 Rollup 或 Vite 打包为 ES Module
• 发布后，其他项目可通过 npm 安装并导入注册

使用示例：

import 'my-ui-library';
// 之后即可使用 、 等标签

5. 跨框架兼容性处理

Web Components 原生兼容所有框架，但需注意：

• React 不自动监听自定义事件，需用 on-click 替代 onClick，或通过 ref 手动绑定
• 属性传递时，布尔值需转字符串或通过 JS 设置
• 建议提供各主流框架的使用说明文档

基本上就这些。只要遵循标准规范，合理设计 API 和样式接口，就能构建出真正通用、易维护、长期稳定的跨项目 UI 库。