Back to Details

avalonia

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Avalonia UI Framework - Orchestration Hub

Avalonia UI框架 - 编排中心

Modular guidance for cross-platform desktop and mobile development using Avalonia, a WPF-inspired XAML-based framework for .NET.
基于Avalonia的跨平台桌面与移动开发模块化指导，Avalonia是一款受WPF启发的、基于XAML的.NET框架。

Quick Reference: When to Load Which Resource

快速参考：何时加载对应资源

Task/GoalLoad Resource
MVVM patterns, data binding, dependency injection, value converters
resources/mvvm-databinding.md
UI controls reference (layouts, inputs, collections, menus)
resources/controls-reference.md
Custom controls, advanced layouts, performance optimization, virtualization
resources/custom-controls-advanced.md
Styling, themes, animations, control templates
resources/styling-guide.md
Reactive patterns, commands, observables, animations
resources/reactive-animations.md
Windows, macOS, Linux, iOS, Android implementation details
resources/platform-specific.md
任务/目标加载资源
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

Framework Overview

框架概述

Avalonia is a cross-platform XAML framework supporting:
  • Platforms: Windows, macOS, Linux, iOS, Android, WebAssembly
  • Architecture: MVVM with ReactiveUI support
  • Styling: CSS-like selectors with Fluent/Simple themes
  • Features: Data binding, reactive commands, observable collections, custom controls
  • Modern .NET: .NET 6+ and .NET Standard 2.0
Avalonia是一款支持多平台的XAML框架：
  • 支持平台：Windows、macOS、Linux、iOS、Android、WebAssembly
  • 架构：支持ReactiveUI的MVVM架构
  • 样式系统：类CSS选择器，搭配Fluent/Simple主题
  • 核心功能：数据绑定、响应式命令、可观察集合、自定义控件
  • 现代.NET支持：.NET 6+及.NET Standard 2.0

Standard Project Structure

标准项目结构

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)
MyAvaloniaApp/
├── MyAvaloniaApp/                  # 共享代码
│   ├── App.axaml
│   ├── Views/                      # XAML视图
│   ├── ViewModels/                 # 业务逻辑 + 状态管理
│   ├── Models/                     # 数据模型
│   ├── Services/                   # 应用服务
│   ├── Converters/                 # 值转换器
│   ├── Assets/                     # 图片、字体资源
│   └── Styles/                     # 样式资源
├── MyAvaloniaApp.Desktop/          # 桌面平台专属代码（Win/Mac/Linux）
├── MyAvaloniaApp.Android/          # Android平台专属代码（可选）
├── MyAvaloniaApp.iOS/              # iOS平台专属代码（可选）
└── MyAvaloniaApp.Browser/          # WebAssembly平台专属代码（可选）

Getting Started

快速入门

Minimal Setup

最小化配置

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

public static AppBuilder BuildAvaloniaApp() =>
    AppBuilder.Configure<App>()
        .UsePlatformDetect()
        .LogToTrace();
xml
<!-- App.axaml -->
<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>
xml
<!-- Views/MainWindow.axaml -->
<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>
csharp
// Program.cs
public static void Main(string[] args)
{
    BuildAvaloniaApp().StartWithClassicDesktopLifetime(args);
}

public static AppBuilder BuildAvaloniaApp() =>
    AppBuilder.Configure<App>()
        .UsePlatformDetect()
        .LogToTrace();
xml
<!-- App.axaml -->
<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>
xml
<!-- Views/MainWindow.axaml -->
<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>

Core Patterns

核心模式

MVVM Architecture Pattern

MVVM架构模式

  1. View (XAML): UI presentation with data bindings
  2. ViewModel (C#): State management and commands
  3. Model (C#): Business logic and data access
  4. Service: Cross-cutting concerns (DI/IoC)
Load 
resources/mvvm-databinding.md
for:
  • ViewModel base classes
  • Data binding modes and paths
  • Multi-binding and converters
  • Dependency injection setup
  • Design-time data
  1. View（视图）（XAML）：带有数据绑定的UI展示层
  2. ViewModel（视图模型）（C#）：状态管理与命令定义
  3. Model（模型）（C#）：业务逻辑与数据访问层
  4. Service（服务）：横切关注点（依赖注入/控制反转）
加载 
resources/mvvm-databinding.md
获取以下内容：
  • ViewModel基类
  • 数据绑定模式与语法
  • 多绑定与转换器
  • 依赖注入配置
  • 设计时数据

Reactive Programming Pattern

响应式编程模式

Leverage ReactiveUI for event-driven UI updates:
csharp
this.WhenAnyValue(x => x.SearchText)
    .Debounce(TimeSpan.FromMilliseconds(300))
    .Subscribe(text => PerformSearch(text));
Load 
resources/reactive-animations.md
for:
  • Reactive properties and commands
  • Observable sequences
  • Animations and transitions
  • Performance optimization
借助ReactiveUI实现事件驱动的UI更新：
csharp
this.WhenAnyValue(x => x.SearchText)
    .Debounce(TimeSpan.FromMilliseconds(300))
    .Subscribe(text => PerformSearch(text));
加载 
resources/reactive-animations.md
获取以下内容：
  • 响应式属性与命令
  • 可观察序列
  • 动画与过渡效果
  • 性能优化

Platform-Adaptive Pattern

平台适配模式

Design once, adapt per platform:
xml
<OnPlatform Default="16">
    <On Options="Windows" Content="14" />
    <On Options="macOS" Content="15" />
</OnPlatform>
Load 
resources/platform-specific.md
for:
  • Runtime platform detection
  • Platform-specific services
  • Conditional UI rendering
  • Native dialogs and features
一次设计，多平台适配：
xml
<OnPlatform Default="16">
    <On Options="Windows" Content="14" />
    <On Options="macOS" Content="15" />
</OnPlatform>
加载 
resources/platform-specific.md
获取以下内容：
  • 运行时平台检测
  • 平台专属服务
  • 条件化UI渲染
  • 原生对话框与功能

Navigation by Task

按任务导航

"I need to build a form with validation"

"我需要构建一个带验证功能的表单"

  1. Load 
    resources/mvvm-databinding.md
    → Implement ViewModel with property validation
  2. Load 
    resources/controls-reference.md
    → Find TextBox, ComboBox, Button controls
  3. Load 
    resources/reactive-animations.md
    → Add debounced validation with observables
  1. 加载
    resources/mvvm-databinding.md
    → 实现带属性验证的ViewModel
  2. 加载
    resources/controls-reference.md
    → 查找TextBox、ComboBox、Button等控件
  3. 加载
    resources/reactive-animations.md
    → 借助可观察对象实现防抖验证

"I'm seeing poor performance with large lists"

"我发现大型列表的性能很差"

  1. Load 
    resources/custom-controls-advanced.md
    → Enable virtualization
  2. Load 
    resources/mvvm-databinding.md
    → Use compiled bindings
  3. Load 
    resources/reactive-animations.md
    → Debounce/throttle updates
  1. 加载
    resources/custom-controls-advanced.md
    → 启用虚拟化
  2. 加载
    resources/mvvm-databinding.md
    → 使用编译绑定
  3. 加载
    resources/reactive-animations.md
    → 对更新操作进行防抖/节流

"I need platform-specific behavior"

"我需要平台专属行为"

  1. Load 
    resources/platform-specific.md
    → Implement service interfaces
  2. Load 
    resources/mvvm-databinding.md
    → Register platform implementations via DI
  3. Platform-specific 
    resources/
    → Implement per-platform project
  1. 加载
    resources/platform-specific.md
    → 实现服务接口
  2. 加载
    resources/mvvm-databinding.md
    → 通过依赖注入注册平台专属实现
  3. 平台专属
    resources/
    → 在对应平台项目中实现

"I want custom styling and animations"

"我想要自定义样式与动画"

  1. Load 
    resources/styling-guide.md
    → Define styles and themes
  2. Load 
    resources/reactive-animations.md
    → Add animations to styles
  3. Load 
    resources/custom-controls-advanced.md
    → Custom control templates
  1. 加载
    resources/styling-guide.md
    → 定义样式与主题
  2. 加载
    resources/reactive-animations.md
    → 为样式添加动画
  3. 加载
    resources/custom-controls-advanced.md
    → 自定义控件模板

"I'm building a complex control"

"我正在构建一个复杂控件"

  1. Load 
    resources/custom-controls-advanced.md
    → TemplatedControl or UserControl pattern
  2. Load 
    resources/mvvm-databinding.md
    → Attached properties and data binding
  3. Load 
    resources/styling-guide.md
    → Control templates and styling
  1. 加载
    resources/custom-controls-advanced.md
    → 采用TemplatedControl或UserControl模式
  2. 加载
    resources/mvvm-databinding.md
    → 附加属性与数据绑定
  3. 加载
    resources/styling-guide.md
    → 控件模板与样式设计

Resource Organization

资源说明

mvvm-databinding.md
(Primary)

mvvm-databinding.md
（基础核心）

  • Architecture overview
  • ViewModel patterns with ReactiveUI
  • Binding modes and syntax
  • Value converters
  • Collections and list binding
  • Design-time data
  • Master-detail and tab patterns
  • 架构概述
  • 结合ReactiveUI的ViewModel模式
  • 绑定模式与语法
  • 值转换器
  • 集合与列表绑定
  • 设计时数据
  • 主从视图与标签页模式

controls-reference.md
(Primary)

controls-reference.md
（基础核心）

  • Layout controls (Grid, StackPanel, DockPanel, etc.)
  • Input controls (TextBox, Button, CheckBox, ComboBox, etc.)
  • Display controls (TextBlock, Image, ProgressBar, etc.)
  • Collection controls (ListBox, DataGrid, TreeView, etc.)
  • Navigation (Menu, TabControl, SplitView, etc.)
  • Shapes and drawing
  • 布局控件（Grid、StackPanel、DockPanel等）
  • 输入控件（TextBox、Button、CheckBox、ComboBox等）
  • 显示控件（TextBlock、Image、ProgressBar等）
  • 集合控件（ListBox、DataGrid、TreeView等）
  • 导航控件（Menu、TabControl、SplitView等）
  • 图形与绘制

styling-guide.md
(Primary)

styling-guide.md
（基础核心）

  • CSS-like selectors (type, class, pseudo-classes)
  • Resource dictionaries and themes
  • Control templates
  • Data templates
  • Animations and transitions
  • Easing functions
  • Theme variants (light/dark)
  • 类CSS选择器（类型、类、伪类）
  • 资源字典与主题
  • 控件模板
  • 数据模板
  • 动画与过渡效果
  • 缓动函数
  • 主题变体（亮色/暗色）

reactive-animations.md
(Advanced)

reactive-animations.md
（进阶）

  • ReactiveUI integration
  • Reactive properties
  • Reactive commands (sync and async)
  • Observable sequences
  • Filtering, transformation, combining
  • Programmatic animations
  • Common patterns (search, validation, auto-complete)
  • ReactiveUI集成
  • 响应式属性
  • 响应式命令（同步与异步）
  • 可观察序列
  • 过滤、转换、组合操作
  • 程序化动画
  • 常见模式（搜索、验证、自动补全）

custom-controls-advanced.md
(Advanced)

custom-controls-advanced.md
（进阶）

  • Custom TemplatedControl creation
  • User control composition
  • Advanced layouts
  • Virtualization
  • Performance optimization
  • Render transforms
  • Graphics and drawing
  • 自定义TemplatedControl创建
  • 用户控件组合
  • 高级布局
  • 虚拟化
  • 性能优化
  • 渲染变换
  • 图形与绘制

platform-specific.md
(Advanced)

platform-specific.md
（进阶）

  • Runtime platform detection
  • Multi-project structure
  • Service abstractions
  • Platform-specific implementations
  • Window management per platform
  • File system access
  • Native features (Windows DLL, macOS Cocoa, etc.)
  • 运行时平台检测
  • 多项目结构
  • 服务抽象
  • 平台专属实现
  • 各平台窗口管理
  • 文件系统访问
  • 原生功能（Windows DLL、macOS Cocoa等）

Common Workflows

常见工作流

Build a Desktop App (Windows/macOS/Linux)

构建桌面应用（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. → 配置：标准项目结构 + FluentTheme
2. → 遵循MVVM模式创建Views与ViewModels
3. → 参考controls-reference进行UI布局
4. → 借助styling-guide添加样式
5. → 通过依赖注入实现服务（mvvm-databinding）
6. → 借助reactive-animations添加动画
7. → 参考platform-specific在各平台测试

Build a Cross-Platform Mobile+Desktop App

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

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. → 创建共享项目 + 平台专属项目
2. → 在共享代码中定义服务接口（mvvm-databinding）
3. → 为各平台实现对应服务（platform-specific）
4. → 使用OnPlatform实现自适应UI
5. → 通过依赖注入注册平台专属实现
6. → 在所有目标平台（iOS/Android/Windows/Mac）进行全面测试

Add Real-Time Search

添加实时搜索功能

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)
1. → 创建SearchViewModel（mvvm-databinding）
2. → 使用ObservableCollection存储搜索结果（mvvm-databinding）
3. → 采用响应式搜索模式实现（reactive-animations）
4. → 对输入进行防抖以减少API调用
5. → 使用ListBox展示结果（controls-reference）
6. → 借助类CSS选择器设置样式（styling-guide）

Build Complex Data-Driven UI

构建复杂数据驱动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)
1. → 设计ViewModel层级结构（mvvm-databinding）
2. → 创建主从视图（mvvm-databinding）
3. → 使用DataGrid展示表格数据（controls-reference）
4. → 借助可观察对象添加排序/过滤功能（reactive-animations）
5. → 启用虚拟化优化性能（custom-controls-advanced）
6. → 按需添加自定义控件（custom-controls-advanced）

Best Practices Summary

最佳实践总结

Architecture
  • Maintain strict MVVM separation of concerns
  • Use dependency injection for testability
  • Keep business logic in ViewModels, not Views
Performance
  • Enable compiled bindings with 
    x:DataType
  • Virtualize large collections
  • Debounce rapid updates
Styling
  • Use resource dictionaries for consistency
  • Support light and dark themes
  • Test styles on all target platforms
Reactive Patterns
  • Use observables for event-driven updates
  • Debounce/throttle input-triggered operations
  • Always handle ThrownExceptions on commands
Testing
  • Unit test ViewModels in isolation
  • Use Avalonia.Headless for UI testing
  • Provide design-time DataContext in XAML
架构方面
  • 严格遵循MVVM关注点分离原则
  • 使用依赖注入提升可测试性
  • 业务逻辑应放在ViewModel中，而非Views
性能方面
  • 启用带
    x:DataType
    的编译绑定
  • 对大型集合启用虚拟化
  • 对频繁更新操作进行防抖
样式方面
  • 使用资源字典保证样式一致性
  • 支持亮色/暗色主题
  • 在所有目标平台测试样式效果
响应式模式方面
  • 使用可观察对象实现事件驱动更新
  • 对输入触发的操作进行防抖/节流
  • 始终处理命令中的ThrownExceptions
测试方面
  • 单独对ViewModel进行单元测试
  • 使用Avalonia.Headless进行UI测试
  • 在XAML中提供设计时DataContext

Cross-Platform Deployment

跨平台部署

  • Windows: ClickOnce, MSI, portable exe
  • macOS: DMG, homebrew
  • Linux: AppImage, snap, flatpak
  • Mobile: Apple App Store, Google Play Store
  • Web: Static hosting (WASM runtime required)
Refer to 
resources/platform-specific.md
for platform-specific build and deployment guidance.
Navigation: Choose a resource above based on your task. Each resource is self-contained with comprehensive examples and best practices.
  • Windows：ClickOnce、MSI、便携版exe
  • macOS：DMG、Homebrew
  • Linux：AppImage、Snap、Flatpak
  • 移动平台：苹果App Store、Google Play商店
  • Web平台：静态托管（需WASM运行时）
如需平台专属构建与部署指导，请参考
resources/platform-specific.md
。
导航提示：根据你的任务选择上方对应的资源。每个资源均为独立模块，包含完整示例与最佳实践。