avalonia

Avalonia UI Framework - 编排中心

使用 Avalonia 进行跨平台桌面和移动端开发的模块化指南。Avalonia 是一个受 WPF 启发、基于 XAML 的 .NET 框架。

快速参考：何时加载哪个资源

任务/目标	加载资源
MVVM 模式、数据绑定、依赖注入、值转换器	resources/mvvm-databinding.md
UI 控件参考（布局、输入、集合、菜单）	resources/controls-reference.md
自定义控件、高级布局、性能优化、虚拟化	resources/custom-controls-advanced.md
样式、主题、动画、控件模板	resources/styling-guide.md
响应式模式、命令、可观察对象、动画	resources/reactive-animations.md
Windows、macOS、Linux、iOS、Android 实现细节	resources/platform-specific.md

框架概览

Avalonia 是一个跨平台 XAML 框架，支持：

• 平台：Windows、macOS、Linux、iOS、Android、WebAssembly
• 架构：MVVM，支持 ReactiveUI
• 样式：类似 CSS 的选择器，以及 Fluent/Simple 主题
• 功能：数据绑定、响应式命令、可观察集合、自定义控件
• 现代 .NET：.NET 6+ 和 .NET Standard 2.0

标准项目结构

MyAvaloniaApp/
├── MyAvaloniaApp/                  # Shared code
│   ├── App.axaml
│   ├── Views/                      # XAML views
│   ├── ViewModels/                 # Business logic + state
│   ├── Models/                     # Data models
│   ├── Services/                   # Application services
│   ├── Converters/                 # Value converters
│   ├── Assets/                     # Images, fonts
│   └── Styles/                     # Style resources
├── MyAvaloniaApp.Desktop/          # Desktop-specific (Win/Mac/Linux)
├── MyAvaloniaApp.Android/          # Android-specific (optional)
├── MyAvaloniaApp.iOS/              # iOS-specific (optional)
└── MyAvaloniaApp.Browser/          # WebAssembly (optional)

开始使用

最小设置

// Program.cs
public static void Main(string[] args)
{
    BuildAvaloniaApp().StartWithClassicDesktopLifetime(args);
}

public static AppBuilder BuildAvaloniaApp() =>
    AppBuilder.Configure<App>()
        .UsePlatformDetect()
        .LogToTrace();

<Application xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Class="MyApp.App">
    <Application.Styles>
        <FluentTheme />
    </Application.Styles>
</Application>

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        x:Class="MyApp.Views.MainWindow"
        Title="My Application"
        Width="800"
        Height="600">
    <StackPanel Padding="20" Spacing="10">
        <TextBlock Text="Hello, Avalonia!" FontSize="24" FontWeight="Bold" />
    </StackPanel>
</Window>

核心模式

MVVM 架构模式

1. View（XAML）：通过数据绑定呈现 UI
2. ViewModel（C#）：状态管理和命令
3. Model（C#）：业务逻辑和数据访问
4. Service：横切关注点（DI/IoC）

加载 resources/mvvm-databinding.md，了解：

• ViewModel 基类
• 数据绑定模式和路径
• 多重绑定和转换器
• 依赖注入设置
• 设计时数据

响应式编程模式

利用 ReactiveUI 实现事件驱动的 UI 更新：

this.WhenAnyValue(x => x.SearchText)
    .Debounce(TimeSpan.FromMilliseconds(300))
    .Subscribe(text => PerformSearch(text));

加载 resources/reactive-animations.md，了解：

• 响应式属性和命令
• 可观察序列
• 动画和过渡效果
• 性能优化

平台自适应模式

一次设计，按平台调整：

<OnPlatform Default="16">
    <On Options="Windows" Content="14" />
    <On Options="macOS" Content="15" />
</OnPlatform>

加载 resources/platform-specific.md，了解：

• 运行时平台检测
• 平台专属服务
• 条件式 UI 渲染
• 原生对话框和功能

按任务导航

“我需要构建带验证的表单”

1. 加载 resources/mvvm-databinding.md → 实现带属性验证的 ViewModel
2. 加载 resources/controls-reference.md → 查找 TextBox、ComboBox、Button 控件
3. 加载 resources/reactive-animations.md → 使用可观察对象添加防抖验证

“大型列表的性能不佳”

1. 加载 resources/custom-controls-advanced.md → 启用虚拟化
2. 加载 resources/mvvm-databinding.md → 使用编译绑定
3. 加载 resources/reactive-animations.md → 对更新进行防抖/节流

“我需要平台专属行为”

1. 加载 resources/platform-specific.md → 实现服务接口
2. 加载 resources/mvvm-databinding.md → 通过 DI 注册平台实现
3. 平台专属的 resources/ → 实现各平台项目

“我想要自定义样式和动画”

1. 加载 resources/styling-guide.md → 定义样式和主题
2. 加载 resources/reactive-animations.md → 为样式添加动画
3. 加载 resources/custom-controls-advanced.md → 自定义控件模板

“我正在构建复杂控件”

1. 加载 resources/custom-controls-advanced.md → 使用 TemplatedControl 或 UserControl 模式
2. 加载 resources/mvvm-databinding.md → 附加属性和数据绑定
3. 加载 resources/styling-guide.md → 控件模板和样式

资源组织

mvvm-databinding.md（主要）

• 架构概览
• 使用 ReactiveUI 的 ViewModel 模式
• 绑定模式和语法
• 值转换器
• 集合和列表绑定
• 设计时数据
• 主从和选项卡模式

controls-reference.md（主要）

• 布局控件（Grid、StackPanel、DockPanel 等）
• 输入控件（TextBox、Button、CheckBox、ComboBox 等）
• 显示控件（TextBlock、Image、ProgressBar 等）
• 集合控件（ListBox、DataGrid、TreeView 等）
• 导航（Menu、TabControl、SplitView 等）
• 形状和绘图

styling-guide.md（主要）

• 类 CSS 选择器（类型、类、伪类）
• 资源字典和主题
• 控件模板
• 数据模板
• 动画和过渡
• 缓动函数
• 主题变体（浅色/深色）

reactive-animations.md（高级）

• ReactiveUI 集成
• 响应式属性
• 响应式命令（同步和异步）
• 可观察序列
• 筛选、转换、组合
• 编程式动画
• 常见模式（搜索、验证、自动补全）

custom-controls-advanced.md（高级）

• 创建自定义 TemplatedControl
• 用户控件组合
• 高级布局
• 虚拟化
• 性能优化
• 渲染变换
• 图形和绘图

platform-specific.md（高级）

• 运行时平台检测
• 多项目结构
• 服务抽象
• 特定平台的实现
• 各平台的窗口管理
• 文件系统访问
• 原生功能（Windows DLL、macOS Cocoa 等）

常见工作流

构建桌面应用（Windows/macOS/Linux）

1. → Setup: Standard project structure + FluentTheme
2. → Create Views and ViewModels following MVVM
3. → Use controls-reference for UI layouts
4. → Add styles with styling-guide
5. → Implement services with DI (mvvm-databinding)
6. → Add animations with reactive-animations
7. → Test on each platform with platform-specific guidance

构建跨平台移动端+桌面应用

1. → Create shared project + platform-specific projects
2. → Define service interfaces in shared code (mvvm-databinding)
3. → Implement services per platform (platform-specific)
4. → Use OnPlatform for adaptive UI
5. → Register platform implementations via DI
6. → Test thoroughly on each target (iOS/Android/Windows/Mac)

添加实时搜索

1. → Create SearchViewModel (mvvm-databinding)
2. → Use ObservableCollection for results (mvvm-databinding)
3. → Implement with reactive search pattern (reactive-animations)
4. → Debounce input to reduce API calls
5. → Display with ListBox (controls-reference)
6. → Style with appropriate CSS selectors (styling-guide)

构建复杂的、数据驱动的 UI

1. → Design ViewModel hierarchy (mvvm-databinding)
2. → Create master-detail view (mvvm-databinding)
3. → Use DataGrid for tabular data (controls-reference)
4. → Add sorting/filtering with observables (reactive-animations)
5. → Optimize with virtualization (custom-controls-advanced)
6. → Add custom controls if needed (custom-controls-advanced)

最佳实践摘要

架构

• 保持严格的 MVVM 关注点分离
• 使用依赖注入以便于测试
• 将业务逻辑放在 ViewModel 中，而非 View 中

性能

• 使用 x:DataType 启用编译绑定
• 对大型集合进行虚拟化
• 对快速更新进行防抖处理

样式

• 使用资源字典以保持一致性
• 支持浅色和深色主题
• 在所有目标平台上测试样式

响应式模式

• 使用可观察对象实现事件驱动更新
• 对输入触发的操作进行防抖/节流
• 始终处理命令上的 ThrownExceptions

测试

• 隔离测试 ViewModel
• 使用 Avalonia.Headless 进行 UI 测试
• 在 XAML 中提供设计时 DataContext

跨平台部署

• Windows：ClickOnce、MSI、便携版 exe
• macOS：DMG、homebrew
• Linux：AppImage、snap、flatpak
• 移动端：Apple App Store、Google Play Store
• Web：静态托管（需要 WASM 运行时）

请参阅 resources/platform-specific.md，了解特定平台的构建和部署指南。

---

导航：根据你的任务选择上方的资源。每项资源都可独立使用，并包含全面的示例和最佳实践。