# Exploria UI

## 项目简介

🚀 下一代 Vue 3.6 + Vite UI 组件库，基于 OXC 工具链构建，采用 **Monorepo 架构**，提供丰富的组件、插件、工具和指令，满足各类业务场景需求。

### 核心特性

- **完整生态**：包含组件集、插件集、工具集和指令集四大核心模块
- **组件丰富**：覆盖多种业务场景，提供高质量 UI 组件
- **易用性强**：API 设计对齐 Element Plus，零学习成本
- **类型安全**：TypeScript 全量类型支持
- **性能优异**：基于 Vue 3.6 和 Vite 构建，加载速度快
- **现代工具链**：集成 OXC 工具链，提供极速的代码检查和格式化

### 架构说明

本项目采用 **Monorepo 架构**，通过 pnpm 工作区管理多个包，实现代码复用、统一构建和版本管理。核心代码位于 `packages/exploria-ui/` 目录，示例应用位于 `src/` 目录，便于组件库开发和演示。

### 主要开发者

**作者：liketype** - 本组件库的核心开发者，微信号：yywd479

## 技术栈

| 类别         | 技术栈             | 说明                                |
| ------------ | ------------------ | ----------------------------------- |
| **框架**     | Vue 3.6            | 最新 Composition API + 性能优化     |
| **构建工具** | Vite               | 极速的前端构建工具                  |
| **开发语言** | TypeScript         | 类型安全的 JavaScript 超集          |
| **样式方案** | SCSS + Animate.css | 强大的 CSS 预处理器 + 动画库        |
| **工具链**   | OXC                | Rust 编写的极速代码检查和格式化工具 |

## 核心架构

Exploria UI 组件库由五个核心部分构成，形成完整的 UI 解决方案：

### 1. 组件集

组件集是 Exploria UI 的核心，包含丰富的 UI 组件，按功能划分为多个模块：

- **基础组件**：按钮、图标、下划线、卡片、数字角标等基础 UI 元素
- **数据组件**：表格、列表、轮播图等数据展示组件
- **表单组件**：输入框、选择器、复选框等表单控件
- **反馈组件**：对话框、消息提示、通知等用户反馈组件
- **布局组件**：容器、分割线、滚动条等布局元素
- **导航组件**：标签页、下拉菜单等导航组件
- **高级组件**：虚拟列表、水印、滚动视差等高级功能组件
- **3D组件**：立方体等 3D 可视化组件

### 5. MCP Server

MCP (Model Context Protocol) Server 是 Exploria UI 组件库的 AI 辅助服务，允许 AI 工具访问组件库的文档和 API 信息，帮助开发者更好地使用组件库。

#### 功能特性

- **AI 辅助开发**：让 AI 工具能够获取最新的组件文档和 API 信息
- **实时文档访问**：AI 工具可以通过 MCP Server 实时获取组件库的最新文档
- **标准化 API**：提供统一的 API 接口，支持多种 AI 工具集成
- **简单易用**：配置简单，易于集成到各种开发环境

#### 快速开始

```bash
# 启动 MCP Server 开发模式
pnpm run mcp:dev

# 构建 MCP Server
pnpm run mcp:build

# 启动生产模式的 MCP Server
pnpm run mcp:start
```

#### 配置和使用

1. **启动 MCP Server**：使用上述命令启动 MCP Server
2. **访问配置页面**：在浏览器中打开文档网站，点击顶部导航栏的 "MCP Server" 选项
3. **配置服务器地址**：在配置页面中输入 MCP Server 地址（默认：http://localhost:3000）
4. **测试连接**：点击 "测试连接" 按钮，确保 MCP Server 运行正常
5. **保存配置**：点击 "保存配置" 按钮保存设置
6. **配置 AI 工具**：根据您使用的 AI 工具，添加 MCP Server 地址

#### API 端点

- **GET /health**：健康检查
- **POST /mcp/query**：处理 AI 工具的查询请求
- **GET /mcp/components**：获取组件列表
- **GET /mcp/components/:name**：获取单个组件详情

#### 示例提问

```
# 向 AI 工具提问
"Exploria UI 的 EButton 组件有哪些属性？"
"如何使用 Exploria UI 的 EDialog 组件？"
"Exploria UI 的表单组件有哪些？"
```

#### 样式系统

组件集内置完整的样式系统，分为主题系统和尺寸系统两大核心子系统：

##### 主题系统（状态系统）

主题系统定义了组件库的视觉风格和色彩方案，主要包含：

- **主色调**：primaryColor
- **次要色**：secondaryColor
- **背景色**：backgroundColor
- **文字色**：textColor
- **边框色**：borderColor
- **状态色**：successColor、warningColor、errorColor

##### 尺寸系统

尺寸系统定义了组件库的空间关系和视觉层次，主要包含：

- **字体大小**：基础字体大小、小字体、大字体
- **间距系统**：基础间距、小间距、大间距
- **圆角系统**：基础圆角、小圆角、大圆角
- **阴影系统**：基础阴影、浅阴影、深阴影

##### 样式文件组织

基础样式文件位于 `components/style/base/` 目录下，包含：
`colors.scss`、`background-colors.scss`、`border-colors.scss`、`font-sizes.scss` 等。

组件样式采用 SCSS 编写，使用 BEM 命名规范，通过 var 变量形式与基础样式的变量进行关联，确保样式的一致性和可维护性。

组件样式文件位于 `components/style/components/` 目录下，每个组件对应一个独立的样式文件，如：
`e-button.scss`、`e-input.scss`、`e-dialog.scss` 等。

### 2. 主题定制功能

Exploria UI 提供了强大的主题定制功能，支持实时调整主题变量并预览效果。主题定制功能位于 `src/views/ThemeCustomization/` 目录下，包含以下特性：

- **实时预览**：修改主题变量后实时更新预览效果
- **双系统设计**：清晰分离主题系统和尺寸系统，便于管理和定制
- **完整的变量覆盖**：支持自定义所有核心主题和尺寸变量
- **一键重置**：快速恢复默认主题配置

#### 主题定制使用方法

1. 进入主题定制页面：在示例应用中导航到「主题定制」页面
2. 调整主题变量：在左侧表单中修改主题系统或尺寸系统的变量值
3. 实时预览效果：右侧实时显示修改后的组件样式
4. 重置主题：点击「重置主题」按钮恢复默认配置

#### 主题变量示例

```typescript
// 主题系统示例
primaryColor: '#409eff',      // 主色调
secondaryColor: '#6c757d',    // 次要色
backgroundColor: '#ffffff',   // 背景色
textColor: '#303133',         // 文字色

// 尺寸系统示例
fontSizeBase: '14px',         // 基础字体大小
spacingBase: '16px',          // 基础间距
borderRadiusBase: '4px',      // 基础圆角
boxShadowBase: '0 2px 12px 0 rgba(0, 0, 0, 0.1)',  // 基础阴影
```

### 3. 插件集

插件集提供可扩展的功能模块，用于增强组件库的能力：

- **SVG 精灵构建器**：自动构建 SVG 精灵图，优化图标加载
- **图片预加载构建器**：预加载图片资源，提升用户体验
- **SVG 兼容修复**：解决 SVG 在不同浏览器的兼容问题

### 4. 工具集

工具集包含各类实用工具函数，简化开发流程：

- **DOM 操作工具**：便捷的 DOM 操作方法
- **动画工具**：基于 Animate.css 的动画封装
- **图表工具**：ECharts 图表的封装和扩展
- **事件总线**：全局事件管理
- **本地存储工具**：增强的 localStorage 操作
- **时间工具**：日期时间格式化和计算
- **UUID 工具**：生成唯一标识符
- **图片工具**：图片处理和优化
- **Three.js 工具**：3D 渲染相关工具

### 5. 指令集

指令集提供实用的 Vue 自定义指令，扩展 Vue 的能力：

- **拖拽指令**：实现元素拖拽功能
- **尺寸观察指令**：监听元素尺寸变化
- **滑入动画指令**：元素进入视口时的动画效果

## 快速开始

### 前置要求

- **Node.js**: `>= 20.x`
- **pnpm**: `>= 10.x`

### 安装依赖

```bash
pnpm install
```

### 开发模式

```bash
pnpm run dev
```

访问 `http://localhost:5173` 查看应用。

### 生产构建

```bash
# 构建生产版本
pnpm run build

# 预览生产构建
pnpm run preview
```

### 代码质量

```bash
# 代码检查
pnpm run lint

# 代码格式化
pnpm run format
```

## 测试

### 测试框架

项目使用 [Vitest](https://vitest.dev/) 作为测试框架，提供极速的单元测试体验。

### 测试命令

#### 运行所有测试

```bash
pnpm test
```

#### 监视模式运行测试

```bash
pnpm test:watch
```

### 测试文件结构

测试文件采用以下命名规范和目录结构：

```
└── components/
    └── basic/
        └── EButton/
            ├── EButton.other          # 组件文件
            └── __tests__/            # 测试目录（双下划线包裹，符合行业标准）
                └── EButton.spec.ts   # 测试文件（.spec.ts 后缀）
```

### 测试执行前置条件

1. **安装依赖**：确保已执行 `pnpm install` 安装所有依赖
2. **环境要求**：Node.js >= 20.x，pnpm >= 10.x
3. **组件结构**：被测试组件需按照标准目录结构组织

### 测试结果解读

运行测试后，你会看到类似以下的输出：

```
 RUN  v4.0.18 C:/Users/.../exploria-ui-document

 ✓ packages/exploria-ui/src/components/basic/EButton/__tests__/EButton.spec.ts (4 tests) 39ms
 ✓ packages/exploria-ui/src/components/basic/ESvgIcon/__tests__/ESvgIcon.spec.ts (3 tests) 29ms
 ↓ packages/exploria-ui/src/components/advanced/EWatermark/__tests__/EWatermark.spec.ts (3 tests | 3 skipped) 10ms

 Test Files  7 passed | 1 skipped (8)
      Tests  27 passed | 3 skipped (30)
   Start at  23:25:17
   Duration  2.26s
```

#### 结果说明

- **Test Files**：测试文件数量，包括通过和跳过的文件
- **Tests**：测试用例数量，包括通过和跳过的用例
- **Duration**：测试执行总时长
- **✓**：测试通过
- **×**：测试失败
- **↓**：测试跳过（通常是因为环境限制，如 Canvas API 不可用）

### 常见测试问题排查

#### 1. 测试文件未被发现

**问题**：运行测试时显示 "No test files found"

**排查步骤**：

- 检查测试文件是否位于 `__tests__` 目录下
- 检查测试文件是否以 `.spec.ts` 或 `.test.ts` 结尾
- 检查 `vitest.config.ts` 中的 `include` 配置是否正确

#### 2. 组件依赖缺失

**问题**：测试运行时出现 "Module not found" 错误

**排查步骤**：

- 确保已执行 `pnpm install` 安装所有依赖
- 检查组件导入路径是否正确
- 检查是否缺少必要的 peer dependencies

#### 3. DOM API 不可用

**问题**：测试运行时出现 "Cannot read properties of null" 或 DOM API 相关错误

**排查步骤**：

- 检查测试环境是否配置了 `jsdom`（已在 vitest.config.ts 中配置）
- 对于 Canvas API 相关错误，考虑在测试中跳过或模拟 Canvas API

#### 4. 测试用例失败

**问题**：测试用例执行失败

**排查步骤**：

- 查看测试失败的详细错误信息
- 检查组件实现是否符合预期
- 检查测试用例的断言是否正确
- 考虑使用 `console.log` 调试测试用例

### 编写测试用例

测试用例应遵循以下原则：

1. **测试命名清晰**：测试用例名称应能准确描述测试内容
2. **测试覆盖全面**：覆盖组件的主要功能和边界情况
3. **测试独立运行**：每个测试用例应能独立运行，不依赖其他测试
4. **测试断言明确**：使用清晰的断言语句，便于理解测试意图

#### 测试用例示例

```typescript
import { mount } from '@other/test-index';
import EButton from '../EButton.other';

describe('EButton', () => {
    it('should render correctly', () => {
        const wrapper = mount(EButton, {
            slots: {
                default: 'Button',
            },
        });
        expect(wrapper.text()).toBe('Button');
    });

    it('should handle click event', async () => {
        const handleClick = vi.fn();
        const wrapper = mount(EButton, {
            slots: {
                default: 'Button',
            },
            props: {
                onClick: handleClick,
            },
        });
        await wrapper.trigger('click');
        expect(handleClick).toHaveBeenCalled();
    });
});
```

### 测试最佳实践

1. **优先测试公共 API**：测试组件的公共接口，而非内部实现细节
2. **使用快照测试**：对于 UI 组件，考虑使用快照测试确保 UI 一致性
3. **模拟外部依赖**：对于外部依赖（如 API 调用），使用模拟（mock）避免测试依赖外部服务
4. **保持测试简洁**：每个测试用例应只测试一个功能点
5. **定期运行测试**：在开发过程中定期运行测试，确保代码质量

## 项目结构

### 根目录结构

**Monorepo 架构**的核心结构如下：

```
exploria-ui-document/
├── .cursor/                    # Cursor 编辑器配置
├── .idea/                      # IDE 配置文件
├── .trae/                      # Trae AI 相关配置
│   ├── rules/                  # 项目规则配置
│   └── skills/                 # 设计技巧和最佳实践集合
│       ├── logicflow-instance/ # LogicFlow 实例设计技巧
│       └── logicflow-node-resize/ # LogicFlow 节点缩放技巧
├── dist/                       # 示例应用构建输出目录
├── node_modules/               # 项目依赖包
├── packages/                   # 【Monorepo核心】包目录，管理多个子包
│   └── exploria-ui/            # Exploria UI 组件库核心包
├── public/                     # 静态资源目录
├── src/                        # 示例应用源码，用于组件库演示
├── 设计稿件/                     # 设计稿目录
├── .gitignore                  # Git 忽略配置
├── index.html                  # 示例应用入口文件
├── LICENSE                     # 项目许可证
├── oxfmtrc.json                # OXC 格式化配置
├── oxlintrc.json               # OXC 代码检查配置
├── package.json                # 根项目配置
├── pnpm-lock.yaml              # pnpm 依赖锁定文件
├── pnpm-workspace.yaml         # 【Monorepo核心】pnpm 工作区配置文件
├── README.md                   # 项目主文档
├── tsconfig.json               # TypeScript 配置
├── vite.config.ts              # Vite 配置
├── vitest.config.ts            # Vitest 测试配置
└── 一键更新网站.bat              # 网站更新脚本
```

### 核心目录说明

#### 1. packages/exploria-ui/（组件库核心）

```
packages/exploria-ui/
├── dist/                       # 组件库构建输出目录
│   ├── components/             # 组件构建输出
│   ├── directives/             # 指令构建输出
│   ├── plugins/                # 插件构建输出
│   ├── utils/                  # 工具构建输出
│   └── index.css               # 样式输出
├── scripts/                    # 构建脚本目录
├── src/                        # 组件库源代码
│   ├── components/             # 组件集
│   ├── directives/             # 指令集
│   ├── plugins/                # 插件集
│   └── utils/                  # 工具集
├── package.json                # 组件库配置
├── README.md                   # 组件库文档
├── tsconfig.json               # 组件库 TypeScript 配置
└── vite.config.ts              # 组件库 Vite 配置
```

#### 2. src/（示例应用）

示例应用用于演示组件库的使用，包含各种组件的示例代码和文档。

#### 3. .trae/skills/（设计技巧）

该目录包含项目的设计技巧和最佳实践，每个技巧以独立目录形式存在，包含详细的使用说明和示例代码。

##### 现有技巧

- **logicflow-instance**：LogicFlow 实例设计技巧，涵盖实例创建、数据管理、渲染优化等内容
- **logicflow-node-resize**：LogicFlow 节点缩放技巧，提供可复用的节点缩放配置和实现方案，支持矩形、椭圆、菱形和HTML节点的缩放功能

##### 技巧格式

每个技巧目录包含一个 `SKILL.md` 文件，内容包括：

- 功能介绍
- 触发条件
- 核心概念
- 使用方法
- 设计技巧
- 注意事项
- 扩展建议
- 最佳实践
- 常见问题与解决方案

### 组件库构建输出结构

组件库构建后生成的 `dist` 目录结构如下：

```
dist/
├── components/                 # 组件集
│   ├── advanced/              # 高级组件（虚拟列表、水印等）
│   ├── basic/                 # 基础组件（按钮、图标等）
│   ├── data/                  # 数据组件（表格、轮播图等）
│   ├── feedback/              # 反馈组件（对话框、消息提示等）
│   ├── form/                  # 表单组件（输入框、选择器等）
│   ├── geometry/              # 几何组件
│   ├── hooks/                 # 组件钩子函数
│   ├── layout/                # 布局组件
│   └── navigation/            # 导航组件（标签页等）
├── directives/                # 指令集
├── plugins/                   # 插件集
├── utils/                     # 工具集
└── index.css                  # 全局样式
```

## 组件库开发

### 进入组件库目录

```bash
cd packages/exploria-ui
```

### 构建组件库

```bash
# 带监听模式构建组件库（包含组件、指令、工具函数）
pnpm run build:watch

# 带监听模式构建插件
pnpm run build:plugins:watch

# 类型检查
pnpm run type-check
```

### 发布组件库

```bash
pnpm run pub
```

## 配置说明

### OXC 配置

- **oxfmtrc.json**：OXC 代码格式化配置，用于统一代码风格
- **oxlintrc.json**：OXC 代码检查配置，用于保证代码质量

### TypeScript 配置

- **tsconfig.json**：项目 TypeScript 配置，支持 Vue 3 组件类型检查

### Vite 配置

- **vite.config.ts**：Vite 构建配置，包含组件库构建和示例应用构建配置

## CSS 命名规范

本项目采用 BEM (Block, Element, Modifier) 命名规范来组织 CSS 代码，特别是选择题相关组件。BEM 命名规范可以使 CSS 代码更加结构化、可维护和可扩展。

### BEM 命名格式

```css
/* Block */
.e-<component-name>

/* Element */
.e-<component-name>__<element-name>

/* Modifier */
.e-<component-name>--<modifier-name>
.e-<component-name>__<element-name>--<modifier-name>
```

### SCSS 语法规范

在 SCSS 环境下，BEM 修饰符必须使用全写形式，禁止使用嵌套的 `&--modifier` 写法。这种写法有利于代码定位和维护。

#### 禁止的写法

```scss
// 禁止：嵌套的BEM修饰符
.e-checkbox {
    &--checked {
        /* 选中状态样式 */
    }
}
```

#### 推荐的写法

```scss
// 推荐：全写的BEM选择器
.e-checkbox {
    /* 根元素样式 */
}

/* 复选框选中状态 */
.e-checkbox--checked {
    /* 选中状态样式 */
}
```

### 选择题组件 BEM 命名示例

- **复选框组件**：`.e-checkbox`
- **复选框图标**：`.e-checkbox__icon`
- **复选框标签**：`.e-checkbox__label`
- **复选框选中状态**：`.e-checkbox--checked`
- **复选框禁用状态**：`.e-checkbox--disabled`
- **单选框组件**：`.e-radio`
- **单选框图标**：`.e-radio__icon`
- **单选框标签**：`.e-radio__label`
- **单选框选中状态**：`.e-radio--checked`

## 浏览器支持

| 浏览器  | 最低版本 |
| ------- | -------- |
| Chrome  | 90+      |
| Firefox | 88+      |
| Safari  | 15+      |
| Edge    | 90+      |

## 贡献指南

欢迎提交 Issue 和 Pull Request！请遵循以下规范：

1. **代码规范**：遵循 OXC 配置
2. **提交信息**：使用 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/)
3. **组件开发**：参考现有组件的目录结构
4. **文档更新**：同步更新相关文档

## 许可证

本项目基于 [MIT License](LICENSE) 开源。

## 联系方式

- **作者：liketype** - 微信号：yywd479
- 项目地址：<https://gitee.com/exploria-team/exploria-ui-example.git>

---

Built with ❤️ using Vue 3.6 + Vite + OXC
