mirror of
https://github.com/jackqqq123/luban_ui_internal.git
synced 2025-11-15 13:48:24 +08:00
147 lines
6.0 KiB
Markdown
147 lines
6.0 KiB
Markdown
---
|
||
applyTo: '**'
|
||
---
|
||
- 说中文
|
||
- 这是一个基于Avalonia的项目管理工程，目标是让非程序员也能轻松使用luban管理配置表。
|
||
- 命令行是PowerShell使用分号作为命令分隔符
|
||
|
||
## 架构说明
|
||
|
||
### 🏗️ LubanHub.Core 核心能力库
|
||
LubanHub.Core 提供了项目的底层核心能力，**优先使用这些服务**来实现功能，避免重复造轮子：
|
||
|
||
#### 📥 下载服务 (ICoreDownloadService)
|
||
- **默认下载目录**: 系统用户数据目录的LubanHub子目录 (`%AppData%\LubanHub\Downloads`)
|
||
- **目录管理**: 获取/设置下载目录
|
||
- **进度追踪**: 实时下载进度、速度、文件名显示
|
||
- **取消支持**: 支持CancellationToken取消下载
|
||
- **使用场景**: Luban版本下载、模板下载、资源文件下载
|
||
|
||
#### 📁 文件管理服务 (ICoreFileService)
|
||
- **文件操作**: 创建、删除、复制、移动文件
|
||
- **目录操作**: 创建、删除、遍历目录
|
||
- **异步读写**: ReadAllTextAsync/WriteAllTextAsync
|
||
- **信息获取**: FileInfo/DirectoryInfo
|
||
- **使用场景**: 配置文件操作、项目文件管理、模板文件处理
|
||
|
||
#### ⚙️ 进程调用服务 (ICoreProcessService)
|
||
- **同步执行**: 等待进程完成并获取输出
|
||
- **异步执行**: 实时获取stdout/stderr输出
|
||
- **后台进程**: 启动但不等待的进程
|
||
- **进程管理**: 检查进程状态、杀死进程
|
||
- **使用场景**: 调用Luban命令行、Git操作、外部工具集成
|
||
|
||
#### 🗜️ 解压缩服务 (ICoreCompressionService)
|
||
- **ZIP支持**: 完整的ZIP解压缩功能
|
||
- **进度追踪**: 解压进度回调
|
||
- **格式检测**: 自动识别压缩格式
|
||
- **扩展支持**: 预留RAR/7Z接口（需第三方库）
|
||
- **使用场景**: Luban安装包解压、模板包解压、资源包处理
|
||
|
||
#### 🔧 依赖注入集成
|
||
```csharp
|
||
// 在App.axaml.cs中已配置
|
||
services.AddCoreServices(); // 自动注册所有Core服务
|
||
```
|
||
|
||
#### ⚠️ 扩展原则
|
||
- **优先使用**: 实现新功能时，首先检查Core是否已提供相关服务
|
||
- **必要扩展**: 只有在Core无法满足需求时，才考虑扩展Core
|
||
- **接口设计**: 新增Core功能需要定义接口，保持架构一致性
|
||
- **日志集成**: 所有Core服务已集成Microsoft.Extensions.Logging
|
||
|
||
## UI设计规范
|
||
|
||
### 🎨 主题兼容性
|
||
- **深色模式支持**: 所有UI元素必须在深色主题下清晰可见，具有足够的对比度
|
||
- **浅色模式支持**: 所有UI元素必须在浅色主题下保持良好的可读性和视觉效果
|
||
- **动态主题切换**: 使用DynamicResource绑定，支持运行时主题切换
|
||
- **颜色资源化**: 避免硬编码颜色值，统一使用主题资源字典中的颜色定义
|
||
|
||
### 🎯 交互状态设计
|
||
- **主要操作按钮**: 使用主题蓝色系，在两种模式下都要突出显示
|
||
- **成功/确认状态**: 使用绿色系，表示积极操作
|
||
- **警告状态**: 使用黄色系，提醒用户注意
|
||
- **错误/删除状态**: 使用红色系，表示危险操作
|
||
- **悬停和按下状态**: 提供清晰的视觉反馈，确保在两种主题下都有足够的对比度
|
||
|
||
### 📝 文字层级
|
||
- **主要文字**: 使用主题的主要文字颜色，确保最佳可读性
|
||
- **次要文字**: 使用稍浅的颜色，但仍保持良好的可读性
|
||
- **占位符文字**: 使用更浅的颜色，明确区分占位符和实际内容
|
||
- **禁用文字**: 使用最浅的颜色，明确表示不可用状态
|
||
|
||
### 🔘 圆角规范
|
||
- **按钮圆角**: `4px`
|
||
- **输入框圆角**: `4px`
|
||
- **卡片圆角**: `5px`
|
||
- **列表项圆角**: `3px`
|
||
|
||
### 📏 间距规范
|
||
- **小间距**: `5px`
|
||
- **标准间距**: `10px`
|
||
- **中等间距**: `15px`
|
||
- **大间距**: `20px`
|
||
- **页面边距**: `20px`
|
||
- **按钮内边距**: 水平`15px` 垂直`8px`
|
||
- **导航按钮内边距**: 水平`20px` 垂直`15px`
|
||
|
||
### 🎭 动画规范
|
||
- **过渡时间**: `0.2s` (200ms)
|
||
- **缓动函数**: `ease-out`
|
||
- **支持的过渡**: 背景色、前景色、透明度
|
||
|
||
### 📱 组件规范
|
||
- **导航栏宽度**: `200px`
|
||
- **最小窗口尺寸**: 宽度`1000px` 高度`600px`
|
||
- **设计尺寸**: 宽度`1200px` 高度`800px`
|
||
- **按钮最小高度**: `36px`
|
||
- **输入框最小高度**: `32px`
|
||
|
||
### 🎪 图标使用
|
||
- 使用Emoji作为图标: 📚📁📦📱⚙️🎮📊🔧🤖➕🔄📂🌐等
|
||
- 图标大小: 导航按钮中正常大小，卡片中`40px`
|
||
|
||
### 🖱️ 交互反馈
|
||
- 所有可点击元素必须有悬停状态
|
||
- 按钮支持按下状态反馈
|
||
- 输入框支持焦点状态
|
||
- 列表项支持选中和悬停状态
|
||
- 过渡动画让交互更流畅
|
||
|
||
## 开发指导
|
||
|
||
### 📋 功能实现流程
|
||
1. **需求分析**: 明确功能需求和用户场景
|
||
2. **Core检查**: 检查LubanHub.Core是否已提供相关服务
|
||
3. **服务利用**: 优先使用Core服务实现功能逻辑
|
||
4. **UI设计**: 按照设计规范创建用户界面
|
||
5. **进度显示**: 长时间操作使用底部进度条显示状态
|
||
6. **错误处理**: 合理的异常处理和用户提示
|
||
|
||
### 🎯 常见场景示例
|
||
- **文件下载**: 使用ICoreDownloadService，进度显示在底部
|
||
- **Luban调用**: 使用ICoreProcessService执行命令行
|
||
- **配置管理**: 使用ICoreFileService读写配置文件
|
||
- **安装包处理**: 使用ICoreCompressionService解压
|
||
- **目录选择**: 集成系统文件对话框（需要时扩展Core）
|
||
|
||
### 🔄 服务扩展指南
|
||
当需要新功能且Core无法满足时：
|
||
1. 在`LubanHub.Core/Interfaces`添加接口定义
|
||
2. 在`LubanHub.Core/Services`添加实现类
|
||
3. 在`ServiceCollectionExtensions`中注册服务
|
||
4. 更新本文档说明新增能力
|
||
5. 在App层通过依赖注入使用新服务
|
||
|
||
### 📊 UI状态管理
|
||
- **ViewModelBase**: 所有ViewModel继承此基类
|
||
- **属性绑定**: 使用SetProperty方法通知UI更新
|
||
- **命令模式**: 使用RelayCommand处理用户交互
|
||
- **进度显示**: 使用DownloadProgressViewModel显示长时间操作
|
||
|
||
### 🎨 主题和样式
|
||
- **主题切换**: 使用ThemeManager管理深色/浅色主题
|
||
- **资源绑定**: 所有颜色使用DynamicResource绑定
|
||
- **样式复用**: 在Styles.axaml中定义通用样式
|
||
- **响应式**: 支持运行时主题切换 |