前言
在前端技术栈百花齐放的今天，我们经常面临一个痛点：组件复用难。React 组件无法直接在 Vue 项目中使用，Vue 2 的组件难以平滑迁移到 Vue 3。
Web Components 的出现正是为了解决这个问题。它是一套 W3C 标准，允许开发者创建可重用、封装良好且独立于框架的 UI 组件。无论你的主应用是 Vue、React 还是纯原生 JS，Web Components 都能完美运行。
一、技术全景：什么是 Web Components？
Web Components 并非单一技术，而是由四项核心技术组成的规范集合，旨在实现组件的高内聚与低耦合。
1.1 核心组成体系
我们可以通过下图理解其运作机制：
graph TD WC[Web Components] --> CE[Custom Elements]
WC --> SD[Shadow DOM]
WC --> HT[HTML Templates]
WC --> ES[ES Modules]
subgraph "逻辑层：Custom Elements"
CE --> CER[CustomElementRegistry]
CE --> LC[生命周期回调]
LC --> C1[connectedCallback <br/>(挂载)]
LC --> C2[disconnectedCallback <br/>(卸载)]
LC --> C3[attributeChangedCallback <br/>(属性变更)]
end
subgraph "视图层：Shadow DOM"
SD --> SR[ShadowRoot]
SD --> DOMI[DOM 隔离]
SD --> CSSI[样式 隔离]
end
- Custom Elements：通过 CustomElementRegistry 定义浏览器直接识别的新标签（如
<chat-root>）。 - Shadow DOM：这是组件化的灵魂。它将组件内的 HTML 和 CSS 隐藏在
#shadow-root中，完全隔离于外部文档。外部的 CSS 无法影响组件，组件的样式也不会污染外部。 - HTML Templates：使用
<template>标签定义结构。 - ES Modules：标准的模块化加载方案。
二、方案选型：为什么选择 Vue 3？
虽然原生 API 可以编写 Web Components，但通过 HTMLElement 手写繁琐的 DOM 操作和状态管理效率极低。
Vue 3 提供了 defineCustomElement API，让我们能用熟悉的 SFC (单文件组件) 语法开发，最后编译成标准的 Custom Element。
2.1 转换原理
Vue 编译器将组件转换为 Web Component 的流程如下：
graph TD VueSFC[Vue 单文件组件 (.vue)] -->|编译 | VueCE[defineCustomElement]
VueCE -->|封装 | CE[HTMLElement 类]
subgraph "运行时行为"
CE -->|Props 映射 | Atts[HTML Attributes]
CE -->|Emits 映射 | Events[Custom Events]
CE -->|挂载 | SR[Shadow Root]
end
SR -->|注入 | Styles[CSS (Inline)]
SR -->|渲染 | Template[DOM 结构]
三、工程化架构
为了满足企业级开发需求（TypeScript、Pinia 状态管理、多环境构建），我们需要设计合理的目录结构。
3.1 项目结构 (vite-shadow-dom)
vite-shadow-dom/
├── demo/ # 调试/演示应用（模拟真实使用场景）
│ ├── main.ts
│ └── index.html
├── src/ # 组件库源码
│ ├── components/
│ │ └── ChatRoot.vue # 核心业务组件
│ ├── styles/
│ ├── entry.ts
│ └── vite-env.d.ts
├── scripts/
├── vite.config.ts
├── vite.compat.config.ts
└── package.json
