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.3 实现
• 🔜 动态主题切换 - 计划在 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>

参考资料

• Apple HIG - Color
• Apple HIG - 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

构建

# 恢复包
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 文件。