如何使用 Web Components 构建一套与框架无关的跨项目 UI 组件库？

使用 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 = `
<button>
${label}
</button>
`;
}
}
customElements.define('my-button', MyButton);

之后即可在任意项目中使用：<my-button label="提交"&gt;</my-button&gt;

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

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

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

connectedCallback() {
this.shadowRoot.innerHTML = `
<style>
:host {
display: inline-block;
}
button {
padding: 8px 16px;
background: var(--btn-bg, #007bff);
color: white;
border: none;
border-radius: 4px;
cursor: pointer;
}
button:hover {
opacity: 0.9;
}
</style>
<button><slot&gt;</slot></button>
`;
}

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

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

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

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

LuckyCola工具库

LuckyCola工具库是您工作学习的智能助手，提供一系列AI驱动的工具，旨在为您的生活带来便利与高效。

19

查看详情

this.shadowRoot.innerHTML = `
<button>
<slot name="prefix"></slot>
<slot&gt;</slot>
</button>
`;

使用方式：

<my-button>
<span slot="prefix">▶</span>
开始播放
</my-button>

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';
// 之后即可使用 <my-button>、<my-input> 等标签

5. 跨框架兼容性处理

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

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

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