chuan
c4a9b8d8d4
- 完成三层颜色架构实现（Primitives → Semantic → Component） - 新增暗色主题支持，包含完整的 Apple HIG Dark Mode 色值 - 重构颜色系统为六类别架构（Background, Foreground, Border, Accent, State, Surface） - 完善颜色演示页面，按类别分组展示所有颜色 - 更新主题切换说明，支持手动切换浅色/暗色主题 - 新增 BMad 方法文档和架构说明 - 完善 README 和技术栈文档
164 lines
5.5 KiB
Markdown
164 lines
5.5 KiB
Markdown
# Penguin.AvaloniaUI
|
||
|
||
一个现代化的跨平台 UI 控件库，专为 Avalonia 应用程序设计，提供业务场景控件和响应式 MVVM 支持。
|
||
|
||
## 技术栈
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|-----------|---------|---------|
|
||
| .NET | 9.0 | 应用运行时环境 |
|
||
| Avalonia | 11.3.7 | 跨平台桌面 UI 框架 |
|
||
| ReactiveUI.Avalonia | 11.3.0 | 响应式 MVVM 实现 |
|
||
| Semi.Avalonia | 11.2.1.9 | 现代化设计主题 |
|
||
| xUnit | 2.6.6 | 单元测试框架 |
|
||
|
||
## 颜色系统
|
||
|
||
Penguin.AvaloniaUI 的颜色系统完全基于 **Apple Human Interface Guidelines**，使用苹果官方标准色值，确保与 iOS、macOS、iPadOS 等平台的视觉一致性。
|
||
|
||
### 核心语义化颜色
|
||
|
||
颜色系统提供三个主要类别：
|
||
|
||
**System Colors（系统颜色）** - 用于强调和状态指示
|
||
- `SystemBlue` - 主色，用于主要按钮、链接、活动状态
|
||
- `SystemIndigo` - 次要色，用于次要操作、备选强调
|
||
- `SystemGreen` - 成功状态指示，确认操作
|
||
- `SystemOrange` - 警告状态指示，需注意的信息
|
||
- `SystemRed` - 错误状态指示，删除、危险操作
|
||
- 以及其他扩展颜色：SystemYellow, SystemPink, SystemPurple, SystemTeal, SystemGray
|
||
|
||
**Text Colors（文本颜色）** - 用于所有文本内容
|
||
- `TextPrimary` - 主要文本，标题、正文、重要内容
|
||
- `TextSecondary` - 次要文本，副标题、说明性文字
|
||
- `TextTertiary` - 三级文本，占位符、辅助信息
|
||
- `TextQuaternary` - 四级文本，极弱文本、水印
|
||
|
||
**Background Colors（背景颜色）** - 用于视图层次
|
||
- `SystemBackground` - 主背景，窗口、视图的基础背景
|
||
- `SecondarySystemBackground` - 次要背景，卡片、分组内容背景
|
||
- `TertiarySystemBackground` - 三级背景，嵌套内容背景
|
||
|
||
### 主题支持
|
||
|
||
- ✅ **浅色主题** - 已实现，默认主题
|
||
- ✅ **暗色主题** - 已实现，支持手动切换
|
||
- 🔜 **动态主题切换** - 计划在 Story 1.4 实现
|
||
|
||
#### 手动切换主题
|
||
|
||
当前版本支持浅色和暗色两种主题，可以通过修改 `src/Penguin.AvaloniaUI/Theme.axaml` 文件手动切换：
|
||
|
||
**切换到暗色主题：**
|
||
1. 打开 `src/Penguin.AvaloniaUI/Theme.axaml`
|
||
2. 注释掉浅色主题行：
|
||
```xml
|
||
<!-- <ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Light.axaml" /> -->
|
||
```
|
||
3. 取消注释暗色主题行：
|
||
```xml
|
||
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Dark.axaml" />
|
||
```
|
||
4. 重新运行应用
|
||
|
||
**切换回浅色主题：** 执行相反操作
|
||
|
||
> **注意：** Story 1.4 将实现运行时动态主题切换，届时可以在应用运行时切换主题，无需修改代码和重启应用。
|
||
|
||
### 使用示例
|
||
|
||
在 XAML 中使用语义化颜色（必须使用 `{DynamicResource}` 以支持主题切换）：
|
||
|
||
```xml
|
||
<Window Background="{DynamicResource SystemBackground}">
|
||
<StackPanel>
|
||
<TextBlock Text="主要文本"
|
||
Foreground="{DynamicResource TextPrimary}" />
|
||
<TextBlock Text="次要文本"
|
||
Foreground="{DynamicResource TextSecondary}" />
|
||
<Button Background="{DynamicResource SystemBlue}"
|
||
Foreground="{DynamicResource TextPrimary}" />
|
||
</StackPanel>
|
||
</Window>
|
||
```
|
||
|
||
### 参考资料
|
||
|
||
- [Apple HIG - Color](https://developer.apple.com/design/human-interface-guidelines/color)
|
||
- [Apple HIG - Dark Mode](https://developer.apple.com/design/human-interface-guidelines/dark-mode)
|
||
|
||
## 样式系统决策
|
||
|
||
- **日期**: 2025-10-16
|
||
- **决策**: 使用 Semi.Avalonia
|
||
- **理由**: Semi.Avalonia 在 NuGet 上可直接获取（版本 11.2.1.9），集成简单（只需添加 xmlns 和主题引用），提供了基于 Semi Design 的现代化设计系统。评估和集成耗时不到 10 分钟，符合我们的效率要求。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
D:\32_avalonia.ui/
|
||
├── src/
|
||
│ ├── Penguin.AvaloniaUI/ # 核心控件库
|
||
│ │ ├── Controls/ # 业务场景控件
|
||
│ │ ├── Layouts/ # 布局控件
|
||
│ │ ├── Themes/ # 主题系统
|
||
│ │ └── Utils/ # 工具类
|
||
│ │
|
||
│ ├── Example/ # 示例应用
|
||
│ │ ├── Views/ # 视图/窗口
|
||
│ │ ├── ViewModels/ # 视图模型
|
||
│ │ └── Models/ # 测试数据模型
|
||
│ │
|
||
│ └── Penguin.AvaloniaUI.Tests/ # 单元测试
|
||
│ ├── Controls/
|
||
│ ├── Layouts/
|
||
│ ├── Themes/
|
||
│ └── Utils/
|
||
├── docs/ # 项目文档
|
||
├── Directory.Packages.props # 统一包版本管理
|
||
└── Penguin.AvaloniaUI.sln # 解决方案文件
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 先决条件
|
||
|
||
- .NET 9.0 SDK 或更高版本
|
||
- Windows、macOS 或 Linux
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
# 恢复包
|
||
dotnet restore
|
||
|
||
# 编译所有项目
|
||
dotnet build
|
||
|
||
# 运行测试
|
||
dotnet test
|
||
|
||
# 运行示例应用
|
||
dotnet run --project src/Example/Example.csproj
|
||
```
|
||
|
||
### 开发
|
||
|
||
项目使用 Central Package Management（统一包版本管理）。所有包版本在 `Directory.Packages.props` 中定义。在项目文件中添加新包时，不要指定版本号：
|
||
|
||
```xml
|
||
<ItemGroup>
|
||
<PackageReference Include="PackageName" />
|
||
</ItemGroup>
|
||
```
|
||
|
||
代码格式通过 `.editorconfig` 强制执行。运行格式检查：
|
||
|
||
```bash
|
||
dotnet format --verify-no-changes
|
||
```
|
||
|
||
## 许可证
|
||
|
||
详情请参阅 [LICENSE](LICENSE) 文件。
|