chuan/ui

Files

chuan c4a9b8d8d4 feat: 实现暗色主题和完善颜色系统架构

- 完成三层颜色架构实现（Primitives → Semantic → Component）
- 新增暗色主题支持，包含完整的 Apple HIG Dark Mode 色值
- 重构颜色系统为六类别架构（Background, Foreground, Border, Accent, State, Surface）
- 完善颜色演示页面，按类别分组展示所有颜色
- 更新主题切换说明，支持手动切换浅色/暗色主题
- 新增 BMad 方法文档和架构说明
- 完善 README 和技术栈文档

2025-10-17 18:16:14 +08:00

5.5 KiB

Raw Permalink Blame History

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 文件手动切换：

切换到暗色主题：

打开 src/Penguin.AvaloniaUI/Theme.axaml

注释掉浅色主题行：

<!-- <ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Light.axaml" /> -->

取消注释暗色主题行：

<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Dark.axaml" />

重新运行应用

切换回浅色主题： 执行相反操作

注意： Story 1.4 将实现运行时动态主题切换，届时可以在应用运行时切换主题，无需修改代码和重启应用。

使用示例

在 XAML 中使用语义化颜色（必须使用 {DynamicResource} 以支持主题切换）：

<Window Background="{DynamicResource SystemBackground}">
  <StackPanel>
    <TextBlock Text="主要文本"
               Foreground="{DynamicResource TextPrimary}" />
    <TextBlock Text="次要文本"
               Foreground="{DynamicResource TextSecondary}" />
    <Button Background="{DynamicResource SystemBlue}"
            Foreground="{DynamicResource TextPrimary}" />
  </StackPanel>
</Window>

参考资料

样式系统决策

日期: 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

构建

# 恢复包
dotnet restore

# 编译所有项目
dotnet build

# 运行测试
dotnet test

# 运行示例应用
dotnet run --project src/Example/Example.csproj

开发

项目使用 Central Package Management（统一包版本管理）。所有包版本在 Directory.Packages.props 中定义。在项目文件中添加新包时，不要指定版本号：

<ItemGroup>
  <PackageReference Include="PackageName" />
</ItemGroup>

代码格式通过 .editorconfig 强制执行。运行格式检查：

dotnet format --verify-no-changes

许可证

详情请参阅 LICENSE 文件。

5.5 KiB Raw Permalink Blame History Unescape Escape