avalonia

Avalonia UI フレームワーク - オーケストレーションハブ

.NET 向けの WPF に着想を得た XAML ベースのフレームワークである Avalonia を使用した、クロスプラットフォームのデスクトップおよびモバイル開発のためのモジュール式ガイダンスです。

クイックリファレンス：読み込むリソースの選び方

タスク／目標	読み込むリソース
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
• アーキテクチャ：ReactiveUI をサポートする MVVM
• スタイル設定：Fluent／Simple テーマに対応した CSS 風セレクター
• 機能：データバインディング、リアクティブコマンド、オブザーバブルコレクション、カスタムコントロール
• モダンな .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. サービス：横断的関心事（DI／IoC）

以下については resources/mvvm-databinding.md を読み込んでください。

• ViewModel の基底クラス
• データバインディングのモードとパス
• マルチバインディングとコンバーター
• 依存性注入のセットアップ
• デザイン時データ

リアクティブプログラミングパターン

イベント駆動型の UI 更新には ReactiveUI を活用します。

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 の関心事を厳密に分離する
• テスト容易性のために依存性注入を使用する
• ビジネスロジックは View ではなく ViewModel に保持する

パフォーマンス

• x:DataType を使用してコンパイル済みバインディングを有効にする
• 大規模なコレクションを仮想化する
• 頻繁な更新をデバウンスする

スタイリング

• 一貫性を保つためにリソースディクショナリを使用する
• ライトテーマとダークテーマに対応する
• すべての対象プラットフォームでスタイルをテストする

リアクティブパターン

• イベント駆動型の更新にはオブザーバブルを使用する
• 入力によって起動される操作をデバウンス／スロットルする
• コマンドの ThrownExceptions を必ず処理する

テスト

• ViewModel の単体テストを個別に行う
• UI テストには Avalonia.Headless を使用する
• 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 を参照してください。

---

ナビゲーション：タスクに応じて、上記のリソースを選択してください。各リソースは包括的な例とベストプラクティスを備えた、自己完結型の内容です。