syncfusion-wpf-busy-indicator（同步融合 wpf 繁忙指示器）

Implementing Syncfusion WPF Busy Indicator

Comprehensive guide for implementing the Syncfusion® WPF Busy Indicator control. The SfBusyIndicator provides visual feedback during long-running operations with over 37 built-in animations, customizable headers, and full MVVM support.

When to Use This Skill

Use this skill when user need to:

• Show loading indicators during data fetching or processing operations
• Display progress animations while waiting for async operations to complete
• Provide visual feedback during long-running background tasks
• Implement wait screens for file operations, API calls, or database queries
• Indicate busy status in WPF applications with animated indicators
• Customize loading UI with headers, templates, and animation styles
• Integrate with MVVM patterns for command execution feedback
• Configure animation types from 37+ built-in animation options

The SfBusyIndicator is essential for improving user experience by providing clear visual feedback during operations that require users to wait.

Component Overview

The SfBusyIndicator control provides a flexible and customizable way to display loading indicators in WPF applications:

Key Features

• 37+ Built-in Animations - Multiple animation styles including Flight, Spin, Ball, Box, and more
• Animation Speed Control - Adjustable animation speed for all animation types (except Fluent)
• Custom Headers - Display informative text below the animation
• Header Templates - Full template customization for header content
• Flexible Sizing - Control animation size with ViewboxHeight and ViewboxWidth
• IsBusy Property - Simple boolean toggle to show/hide the indicator
• Theme Support - Built-in theme integration with Syncfusion theme system
• MVVM Ready - Full data binding support for properties and commands
• Extensible Methods - Override methods for custom control behaviors

Assembly and Namespace

• Assembly: Syncfusion.SfBusyIndicator.WPF
• Namespace: Syncfusion.Windows.Controls.Notification
• NuGet Package: Syncfusion.SfBusyIndicator.WPF

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation via NuGet Package Manager
• Assembly references and namespace imports
• License configuration and registration
• Basic implementation in XAML and code-behind
• Theme setup and configuration
• Minimal working example
• GitHub sample repository links

Animation Configuration

📄 Read: references/animation-types.md

• AnimationType property overview
• Complete list of 37+ built-in animations
• AnimationSpeed property configuration
• Speed adjustment examples (normal, faster, slower)
• Platform-specific notes (Fluent animation behavior)
• Visual animation gallery reference
• XAML, C#, and VB code examples

Display Control

📄 Read: references/isbusy-property.md

• IsBusy property purpose and usage
• Controlling animation execution on/off
• Data binding to async operations
• MVVM pattern integration with commands
• RelayCommand and ICommand examples
• Triggering busy state from view models
• Common display control scenarios

Header Customization

📄 Read: references/header-customization.md

• Header property for simple text
• HeaderTemplate for advanced customization
• DataTemplate examples with styles
• Dynamic content binding
• Multi-line headers and formatting
• Foreground and font customization
• Layout and positioning options

Sizing and Layout

📄 Read: references/sizing.md

• ViewboxHeight property configuration
• ViewboxWidth property configuration
• Responsive sizing strategies
• Container and layout considerations
• Maintaining aspect ratios
• Examples for different screen sizes
• Best practices for sizing

Advanced Usage - Methods

📄 Read: references/methods.md

• Dispose() method for resource cleanup
• Dispose(Boolean) protected overload
• OnApplyTemplate() for template initialization
• OnAnimationTypeChanged() for animation changes
• OnPropertyChanged() for property monitoring
• Custom control extension scenarios
• Template part access patterns
• Advanced customization examples

Quick Start Example

Basic Busy Indicator

<Window xmlns:syncfusion="clr-namespace:Syncfusion.Windows.Controls.Notification;assembly=Syncfusion.SfBusyIndicator.WPF"
        x:Class="BusyIndicatorApp.MainWindow">
    <Grid Background="CornflowerBlue">
        <syncfusion:SfBusyIndicator IsBusy="True"
                                     AnimationType="Flight"
                                     Header="Loading..."
                                     Foreground="White"/>
    </Grid>
</Window>

With Data Binding (MVVM)

<Grid>
    <syncfusion:SfBusyIndicator IsBusy="{Binding IsLoading}"
                                 AnimationType="DoubleCircle"
                                 Header="{Binding LoadingMessage}"/>
</Grid>

public class MainViewModel : INotifyPropertyChanged
{
    private bool _isLoading;
    public bool IsLoading
    {
        get => _isLoading;
        set { _isLoading = value; OnPropertyChanged(); }
    }

    private string _loadingMessage = "Please wait...";
    public string LoadingMessage
    {
        get => _loadingMessage;
        set { _loadingMessage = value; OnPropertyChanged(); }
    }

    public async Task LoadDataAsync()
    {
        IsLoading = true;
        LoadingMessage = "Loading data...";

        await Task.Delay(3000); // Simulate operation

        IsLoading = false;
    }
}

Common Patterns

Pattern 1: Async Operation with Busy Indicator

public class DataViewModel : ViewModelBase
{
    private bool _isBusy;
    public bool IsBusy
    {
        get => _isBusy;
        set => SetProperty(ref _isBusy, value);
    }

    public ICommand LoadCommand { get; }

    public DataViewModel()
    {
        LoadCommand = new RelayCommand(async () => await LoadDataAsync());
    }

    private async Task LoadDataAsync()
    {
        IsBusy = true;
        try
        {
            var data = await _dataService.GetDataAsync();
            // Process data
        }
        finally
        {
            IsBusy = false;
        }
    }
}

Pattern 2: Custom Animation Selection

<StackPanel>
    <ComboBox x:Name="AnimationSelector" SelectedIndex="0">
        <ComboBoxItem Content="Flight"/>
        <ComboBoxItem Content="DoubleCircle"/>
        <ComboBoxItem Content="Spin"/>
    </ComboBox>

    <syncfusion:SfBusyIndicator IsBusy="True"
                                 AnimationType="{Binding ElementName=AnimationSelector,
                                                Path=SelectedItem.Content}"/>
</StackPanel>

Pattern 3: Overlay Busy Indicator

<Grid>
    <!-- Main content -->
    <ContentControl Content="{Binding MainContent}"/>

    <!-- Overlay busy indicator -->
    <Grid Background="#80000000"
          Visibility="{Binding IsBusy, Converter={StaticResource BoolToVisibilityConverter}}">
        <syncfusion:SfBusyIndicator IsBusy="{Binding IsBusy}"
                                     AnimationType="Ball"
                                     Header="Processing..."
                                     Foreground="White"
                                     ViewboxHeight="150"
                                     ViewboxWidth="150"/>
    </Grid>
</Grid>

Pattern 4: Conditional Headers

<syncfusion:SfBusyIndicator IsBusy="{Binding IsProcessing}">
    <syncfusion:SfBusyIndicator.HeaderTemplate>
        <DataTemplate>
            <StackPanel>
                <TextBlock Text="{Binding CurrentOperation}"
                          FontSize="14" FontWeight="Bold"/>
                <TextBlock Text="{Binding ProgressPercentage, StringFormat='Progress: {0}%'}"
                          FontSize="11" Margin="0,5,0,0"/>
            </StackPanel>
        </DataTemplate>
    </syncfusion:SfBusyIndicator.HeaderTemplate>
</syncfusion:SfBusyIndicator>

Key Properties

Key Methods

Common Use Cases

Data Loading Operations

Display a busy indicator while fetching data from APIs, databases, or file systems. Bind IsBusy to the loading state in your view model.

File Operations

Show loading feedback during file uploads, downloads, or processing operations with informative headers indicating the current operation.

Background Processing

Indicate that background tasks are running (calculations, image processing, batch operations) with appropriate animation types and messages.

Application Initialization

Display a busy indicator during application startup while loading configuration, user settings, or initial data.

Search and Filter Operations

Provide visual feedback while performing complex search or filter operations on large datasets.

Navigation and Page Loading

Show busy indicators when navigating between views or loading page content in navigation-based applications.

Best Practices

1. Always use with async operations - Ensure IsBusy is set before starting and cleared after completing operations
2. Provide meaningful headers - Use descriptive text to inform users what's happening
3. Choose appropriate animations - Select animations that match your application's theme and purpose
4. Consider overlay approach - Use semi-transparent overlays to prevent user interaction during busy states
5. Handle exceptions properly - Always reset IsBusy in finally blocks to avoid stuck indicators
6. Use MVVM pattern - Bind IsBusy to view model properties for better testability and maintainability
7. Adjust sizing appropriately - Size the indicator based on the importance and screen space available
8. Theme consistently - Use Syncfusion themes for consistent appearance across your application

Performance Tips

• Avoid complex HeaderTemplates that may impact rendering performance
• Use appropriate animation types for your use case (simpler animations for frequent operations)
• Don't nest multiple busy indicators unnecessarily
• Consider caching animation resources when using many indicators

Related Components

• ProgressBar - For determinate progress indication with percentage
• Toast - For brief notification messages
• Message - For user notifications with actions
• Skeleton - For content placeholder animations

Next Steps: Navigate to the reference files above based on your specific implementation needs. Start with getting-started.md for initial setup or jump directly to feature-specific references for advanced scenarios.