145 lines
6.0 KiB
Markdown
145 lines
6.0 KiB
Markdown
# Epic 1 Details: Foundation & Theme Infrastructure
|
||
|
||
### Epic Goal
|
||
|
||
建立 Penguin.AvaloniaUI 控件库项目的完整基础设施，实现基于苹果颜色系统的主题框架。该 Epic 交付一个可运行的示例应用，演示浅色和暗色主题的流畅切换，为后续控件开发提供样式和颜色基础。通过该 Epic，验证技术栈选择（Avalonia、ReactiveUI、Semi.Avalonia）的可行性。
|
||
|
||
---
|
||
|
||
### Story 1.1: 项目基础设施搭建并初始化示例应用
|
||
|
||
**As a** 控件库开发者，
|
||
**I want** 建立完整的项目结构和依赖配置，并创建一个可运行的示例应用，
|
||
**so that** 我可以在稳定的基础设施上开始控件开发，并有一个测试载体来验证功能。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 创建 Monorepo 目录结构，包含以下项目：
|
||
- `src/Penguin.AvaloniaUI/`（核心控件库，.NET 8 类库）
|
||
- `src/Example/`（示例应用，Avalonia 桌面应用）
|
||
- `src/Penguin.AvaloniaUI.Tests/`（单元测试项目，xUnit）
|
||
|
||
2. 配置 `Penguin.AvaloniaUI` 项目的核心依赖：
|
||
- Avalonia 11.x（最新稳定版）
|
||
- Avalonia.ReactiveUI
|
||
- Semi.Avalonia（如果评估后可用）
|
||
|
||
3. 配置 `Example` 项目引用 `Penguin.AvaloniaUI` 项目
|
||
|
||
4. Example 应用能够成功启动，显示一个基础窗口，包含：
|
||
- 标题："Penguin.AvaloniaUI Demo"
|
||
- 一个 TextBlock 显示 "Hello World"
|
||
- 窗口大小：800x600
|
||
|
||
5. 项目能够在 Windows 平台成功编译和运行
|
||
|
||
6. 创建基础的 `.gitignore` 和 `README.md`
|
||
|
||
7. 快速评估 Semi.Avalonia 的可用性：
|
||
- 如果 Semi.Avalonia 可用，在 Example 中应用其基础样式
|
||
- 如果不可用或过于复杂，记录决策并准备自定义样式系统
|
||
|
||
---
|
||
|
||
### Story 1.2: 实现浅色主题和颜色系统
|
||
|
||
**As a** 控件库开发者，
|
||
**I want** 定义基于苹果颜色系统的语义化颜色，并实现浅色主题，
|
||
**so that** 后续开发的控件可以使用一致的颜色语义，且示例应用有专业的视觉呈现。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 在 `Penguin.AvaloniaUI/Themes/ColorSystem/` 下创建颜色系统定义：
|
||
- 定义语义化颜色资源（ResourceDictionary），包含至少以下颜色：
|
||
- Primary（主色）
|
||
- Secondary（次要色）
|
||
- Success（成功）
|
||
- Warning（警告）
|
||
- Error（错误）
|
||
- Background（背景）
|
||
- Surface（表面）
|
||
- TextPrimary（主要文本）
|
||
- TextSecondary（次要文本）
|
||
|
||
2. 在 `Penguin.AvaloniaUI/Themes/` 下创建 `LightTheme.axaml`（浅色主题资源字典）：
|
||
- 为每个语义化颜色定义浅色主题的具体色值
|
||
- 确保颜色对比度足够（文本与背景对比度 ≥ 4.5:1）
|
||
|
||
3. 将浅色主题应用到 Example 应用：
|
||
- 在 `App.axaml` 中引用 `LightTheme.axaml`
|
||
- 示例窗口的背景色使用 `Background` 颜色
|
||
- TextBlock 的文本色使用 `TextPrimary` 颜色
|
||
|
||
4. 在 Example 中添加一个演示页面，展示所有语义化颜色：
|
||
- 显示每个颜色的名称和色块（使用 Border 或 Rectangle）
|
||
- 色块大小：至少 100x50 像素
|
||
|
||
5. 浅色主题下，示例应用视觉呈现专业、清晰，无明显的配色问题
|
||
|
||
6. 在 `README.md` 中添加颜色系统的简要说明
|
||
|
||
---
|
||
|
||
### Story 1.3: 实现暗色主题
|
||
|
||
**As a** 控件库开发者，
|
||
**I want** 基于颜色系统创建暗色主题，
|
||
**so that** 控件库可以支持暗色模式，满足长时间使用场景的需求。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 在 `Penguin.AvaloniaUI/Themes/` 下创建 `DarkTheme.axaml`（暗色主题资源字典）：
|
||
- 为每个语义化颜色定义暗色主题的具体色值
|
||
- 确保颜色对比度足够（文本与背景对比度 ≥ 4.5:1）
|
||
- 暗色主题的背景色应较深（避免纯黑 #000000，推荐深灰色系）
|
||
|
||
2. 暗色主题的颜色定义应与浅色主题在语义上对应：
|
||
- Primary 在两种主题下都表示"强调色"，但色值可以不同
|
||
- Background 在浅色主题下是浅色，在暗色主题下是深色
|
||
|
||
3. 修改 Example 应用，支持手动切换到暗色主题：
|
||
- 在 `App.axaml` 中暂时保留浅色主题为默认
|
||
- 提供注释说明如何切换到暗色主题（修改 `App.axaml` 中的资源引用）
|
||
|
||
4. 在暗色主题下，颜色演示页面能够正确显示所有暗色主题的颜色
|
||
|
||
5. 暗色主题视觉呈现舒适，无过度刺眼或过暗的问题
|
||
|
||
6. 两种主题下的颜色演示页面应使用相同的 XAML 代码（通过语义化颜色资源绑定）
|
||
|
||
---
|
||
|
||
### Story 1.4: 实现运行时主题切换
|
||
|
||
**As a** 示例应用的用户，
|
||
**I want** 通过 UI 按钮动态切换浅色和暗色主题，
|
||
**so that** 我可以快速验证控件库在不同主题下的视觉效果，无需修改代码和重启应用。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 在 `Penguin.AvaloniaUI/Themes/` 下创建 `ThemeManager.cs` 类：
|
||
- 提供 `ApplyTheme(ThemeType theme)` 方法，支持动态加载主题资源
|
||
- ThemeType 枚举包含 `Light` 和 `Dark`
|
||
- 主题切换通过替换 `Application.Current.Resources` 中的资源字典实现
|
||
|
||
2. 提供一个 ReactiveUI Command：`SwitchThemeCommand`
|
||
- 接受 `ThemeType` 参数
|
||
- 调用 `ThemeManager.ApplyTheme()` 切换主题
|
||
|
||
3. 在 Example 应用的主窗口添加主题切换按钮：
|
||
- 两个按钮："浅色主题" 和 "暗色主题"（或一个 ToggleButton）
|
||
- 按钮绑定到 `SwitchThemeCommand`
|
||
- 按钮样式使用当前主题的颜色系统
|
||
|
||
4. 主题切换应流畅无闪烁：
|
||
- 切换时间 < 100ms（符合 NFR4）
|
||
- 所有使用语义化颜色的控件应自动更新外观
|
||
|
||
5. 主题切换后，颜色演示页面应立即反映新主题的颜色
|
||
|
||
6. 主题状态应持久化（可选，MVP 可以每次启动默认浅色主题）
|
||
|
||
7. 在 Example 中添加一个简单的测试页面，包含多种控件（Button、TextBox、CheckBox），验证主题切换对不同控件的影响
|
||
|
||
---
|
||
|