syncfusion-winui-busy-indicator

WinUI BusyIndicator の実装

このスキルを使用するタイミング

次のことが必要な場合に、このスキルを使用します。

• バックグラウンド処理中に読み込みインジケーターを表示する
• 非同期タスク中にユーザーへビジー状態や待機状態を示す
• データの読み込み、ファイル操作、API 呼び出しの進行状況を示す
• モーダルまたはインラインの読み込みアニメーションを作成する
• 時間のかかる操作中に視覚的なフィードバックを提供する
• 「お待ちください」インジケーターが必要なあらゆるシナリオを実装する

ユーザーが次の内容に言及した場合は、必ずこのスキルを適用してください。 WinUI アプリケーションでの読み込みインジケーター、ビジーインジケーター、進行状況アニメーション、待機画面、非同期操作のフィードバック、またはバックグラウンドタスクの通知。

コンポーネントの概要

SfBusyIndicator は、ビジー状態や読み込み状態を示すために、あらかじめ定義されたアニメーションインジケーターを表示する Syncfusion WinUI コントロールです。8 種類の組み込みアニメーションを備え、サイズ、色、再生時間、コンテンツを幅広くカスタマイズできます。

名前空間： Syncfusion.UI.Xaml.Notifications
NuGet パッケージ： Syncfusion.Notifications.WinUI
プラットフォーム： WinUI 3 Desktop（.NET 5+、Windows App SDK 1.0+）

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• インストールと NuGet パッケージのセットアップ
• 名前空間のインポートと基本的な初期化
• 表示を制御する IsActive プロパティ
• ライセンス登録の要件
• 最初の完全なサンプル

アニメーションの種類

📄 参照： references/animation-types.md

• 8 種類の組み込みアニメーション（DottedCircularFluent、DottedCircle、DottedLinear など）
• AnimationType プロパティの使用方法
• 視覚的な例と比較
• UI に適したアニメーションの選択
• 既定のアニメーション（DottedCircularFluent）

コンテンツと配置

📄 参照： references/content.md

• カスタムメッセージ用の BusyContent プロパティ
• BusyContentPosition（Top、Bottom、Left、Right）
• 高度なカスタマイズに使用する BusyContentTemplate
• カスタム DataTemplate の例
• コンテンツ表示のベストプラクティス

カスタマイズオプション

📄 参照： references/customization.md

• SizeFactor プロパティ（インジケーターのサイズ調整）
• DurationFactor プロパティ（アニメーション速度の制御）
• Color プロパティ（インジケーターの色のカスタマイズ）
• カスタマイズプロパティの組み合わせ
• パフォーマンスに関する考慮事項

クイックスタートの例

<Page
    xmlns:notification="using:Syncfusion.UI.Xaml.Notifications">
    <Grid>
        <notification:SfBusyIndicator 
            x:Name="busyIndicator"
            IsActive="True"
            AnimationType="DottedCircularFluent"
            BusyContent="Loading..."
            BusyContentPosition="Bottom"
            Color="DodgerBlue"
            SizeFactor="0.5"/>
    </Grid>
</Page>

using Syncfusion.UI.Xaml.Notifications;

// Create and configure BusyIndicator
SfBusyIndicator busyIndicator = new SfBusyIndicator
{
    IsActive = true,
    AnimationType = BusyIndicatorAnimationType.DottedCircularFluent,
    BusyContent = "Loading...",
    BusyContentPosition = BusyIndicatorContentPosition.Bottom,
    Color = new SolidColorBrush(Colors.DodgerBlue),
    SizeFactor = 0.5
};

// Add to UI
this.Content = busyIndicator;

よくあるパターン

1. シンプルな読み込みインジケーター

<notification:SfBusyIndicator 
    IsActive="True"
    BusyContent="Loading..."/>

使用するタイミング： カスタマイズせずに基本的な読み込みフィードバックを提供する場合。

2. コードビハインドによる非同期データの読み込み

<Grid>
    <notification:SfBusyIndicator 
        x:Name="busyIndicator"
        IsActive="{x:Bind ViewModel.IsLoading, Mode=OneWay}"
        AnimationType="DottedCircle"
        BusyContent="Loading data..."/>
</Grid>

private async void LoadDataAsync()
{
    busyIndicator.IsActive = true;
    
    try
    {
        await FetchDataFromApiAsync();
    }
    finally
    {
        busyIndicator.IsActive = false;
    }
}

使用するタイミング： 非同期操作中に、プログラムからビジー状態を制御する場合。

3. コンテンツ付きのカスタムアニメーション

<notification:SfBusyIndicator 
    IsActive="True"
    AnimationType="LinearFluent"
    BusyContent="Please wait..."
    BusyContentPosition="Top"
    Color="OrangeRed"
    SizeFactor="0.7"/>

使用するタイミング： 配置や色をカスタマイズして、特定のアニメーションスタイルを使用する場合。

4. モーダルオーバーレイの読み込み画面

<Grid>
    
    <StackPanel>
        <TextBlock Text="Application Content"/>
        
    </StackPanel>
    
    
    <Grid x:Name="loadingOverlay" 
          Background="#80000000"
          Visibility="{x:Bind IsProcessing, Mode=OneWay}">
        <notification:SfBusyIndicator 
            IsActive="True"
            AnimationType="DoubleCircle"
            BusyContent="Processing..."
            Color="White"/>
    </Grid>
</Grid>

使用するタイミング： 重要な操作中に UI の操作をブロックする場合。

5. カスタムコンテンツテンプレート

<notification:SfBusyIndicator IsActive="True" AnimationType="DottedCircle">
    <notification:SfBusyIndicator.BusyContentTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal" Spacing="10">
                <TextBlock Text="⏳" FontSize="24"/>
                <TextBlock Text="Loading data..." 
                          FontSize="16" 
                          FontWeight="SemiBold"/>
            </StackPanel>
        </DataTemplate>
    </notification:SfBusyIndicator.BusyContentTemplate>
</notification:SfBusyIndicator>

使用するタイミング： 単純なテキストメッセージを超える、リッチなコンテンツが必要な場合。

6. 控えめなフィードバック用の低速アニメーション

<notification:SfBusyIndicator 
    IsActive="True"
    AnimationType="SingleCircle"
    DurationFactor="0.9"
    SizeFactor="0.3"
    Color="Gray"/>

使用するタイミング： ユーザーの注意をそらさずに、バックグラウンドでのアクティビティを控えめに示す場合。

主なプロパティ

プロパティ	型	デフォルト	説明
IsActive	bool	false	インジケーターを表示してアニメーションさせるかどうかを制御します。表示するには true、非表示にするには false を設定します。
AnimationType	BusyIndicatorAnimationType	DottedCircularFluent	アニメーションのスタイルです。選択肢：DottedCircularFluent、DottedCircle、DottedLinear、DoubleCircle、LinearBox、LinearFluent、LinearOscillatingBox、SingleCircle。
BusyContent	object	null	インジケーターの下／上／横に表示されるコンテンツ（通常はメッセージ）です。
BusyContentPosition	BusyIndicatorContentPosition	Bottom	インジケーターに対するコンテンツの位置です。選択肢：Top、Bottom、Left、Right。
BusyContentTemplate	DataTemplate	null	ビジー状態のコンテンツに使用するカスタムテンプレートです。単純なテキスト以外のリッチコンテンツを表示できます。
SizeFactor	double	0.5	インジケーターのサイズを制御します。範囲：0.0～1.0。値が大きいほどインジケーターも大きくなります。
DurationFactor	double	0.5	アニメーションの速度を制御します。範囲：0.0～1.0。値が大きいほどアニメーションは遅くなります。
Color	Brush	System accent color	アニメーションするインジケーター要素の色です。

一般的な使用例

データ読み込みの場面

• REST API またはデータベースからデータを取得する
• グリッドやリストに大規模なデータセットを読み込む
• ダッシュボードのコンテンツを更新する
• 起動時にアプリケーションデータを初期化する

おすすめのアニメーション： DottedCircularFluent、DottedCircle

ファイル操作

• ファイルをアップロード／ダウンロードする
• 大容量ファイルを読み込み／書き込みする
• データをインポート／エクスポートする
• ドキュメントを処理する

おすすめのアニメーション： LinearFluent、LinearBox

長時間実行される計算

• 複雑なデータ分析
• レポートの生成
• 画像処理
• 検索操作

おすすめのアニメーション： DoubleCircle、SingleCircle

バックグラウンドタスク

• 同期操作
• キャッシュの更新
• バックグラウンドサービスとの通信
• スケジュールされたタスク

おすすめのアニメーション： LinearOscillatingBox、DottedLinear（控えめ）

実装のヒント

1. IsActive のバインディング： MVVM パターンをすっきりと実装するには、ViewModel の bool プロパティにデータバインディングします。

2. オーバーレイパターン： モーダルな読み込み表示には、BusyIndicator を含む半透明の背景を設定した Grid を使用します。

3. パフォーマンス： BusyIndicator のアニメーションは GPU で高速化されます。複数のインスタンスを使用してもパフォーマンス上の懸念はありません。

4. アクセシビリティ： このコントロールはアクセシビリティ機能を自動的に処理します。カスタムコンテンツには適切なアクセシビリティプロパティを含めてください。

5. スレッド処理： BusyIndicator の有効化／無効化は必ず UI スレッドで行ってください。バックグラウンドスレッドから更新する場合は DispatcherQueue を使用します。

6. ユーザーエクスペリエンス：

   • 500ms を超えると予想される処理では、BusyIndicator をすぐに表示します
   • 処理が完了したら必ず非表示にします（try-finally ブロックを使用してください）
   • UI の状況に合わせてコンテンツを適切に配置します
   • アプリのデザインに合ったアニメーションの種類を選びます

関連ドキュメント

• アニメーションの種類： 8 種類すべてのアニメーションスタイルの詳細な比較については、references/animation-types.md を参照してください
• コンテンツのカスタマイズ： テンプレートの例と配置方法については、references/content.md を参照してください
• カスタマイズ： サイズ、速度、色の設定については、references/customization.md を参照してください