syncfusion-wpf-busy-indicator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WPF Busy Indicator

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.

Syncfusion® WPF Busy Indicator控件实现综合指南。SfBusyIndicator可在长时间运行操作期间提供视觉反馈，内置37种以上动画效果，支持自定义标题，且完全兼容MVVM模式。

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.

当你需要以下操作时，可使用本技能：

在数据获取或处理操作期间显示加载指示器
在等待异步操作完成时展示进度动画
在长时间后台任务执行期间提供视觉反馈
为文件操作、API调用或数据库查询实现等待界面
在WPF应用中通过动画指示器显示忙碌状态
通过标题、模板和动画样式自定义加载UI
与MVVM模式集成，为命令执行提供反馈
从37种以上内置动画选项中配置动画类型

SfBusyIndicator通过在用户需要等待的操作期间提供清晰的视觉反馈，对提升用户体验至关重要。

Component Overview

组件概述

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

SfBusyIndicator控件为WPF应用提供了灵活且可自定义的加载指示器展示方式：

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

37种以上内置动画 - 包含Flight、Spin、Ball、Box等多种动画样式
动画速度控制 - 可调整所有动画类型的速度（Fluent类型除外）
自定义标题 - 在动画下方显示说明性文本
标题模板 - 支持对标题内容进行高级模板自定义
灵活尺寸设置 - 通过ViewboxHeight和ViewboxWidth控制动画尺寸
IsBusy属性 - 简单的布尔值切换，用于显示/隐藏指示器
主题支持 - 与Syncfusion主题系统内置集成
MVVM适配 - 完全支持属性和命令的数据绑定
可扩展方法 - 可重写方法以实现自定义控件行为

Assembly and Namespace

程序集与命名空间

Assembly:
```
Syncfusion.SfBusyIndicator.WPF
```

Namespace:

Syncfusion.Windows.Controls.Notification

NuGet Package:
```
Syncfusion.SfBusyIndicator.WPF
```

程序集：
```
Syncfusion.SfBusyIndicator.WPF
```

命名空间：

Syncfusion.Windows.Controls.Notification

NuGet包：
```
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

📄 阅读： references/getting-started.md

通过NuGet包管理器安装
程序集引用与命名空间导入
许可证配置与注册
在XAML和代码后置中的基础实现
主题设置与配置
最简运行示例
GitHub示例仓库链接

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

📄 阅读： references/animation-types.md

AnimationType属性概述
37种以上内置动画的完整列表
AnimationSpeed属性配置
速度调整示例（正常、更快、更慢）
平台特定说明（Fluent动画行为）
视觉动画图库参考
XAML、C#和VB代码示例

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

📄 阅读： references/isbusy-property.md

IsBusy属性的用途与使用方法
控制动画的开启/关闭
与异步操作的数据绑定
与MVVM模式的命令集成
RelayCommand和ICommand示例
从视图模型触发忙碌状态
常见显示控制场景

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

📄 阅读： references/header-customization.md

用于简单文本的Header属性
用于高级自定义的HeaderTemplate
带样式的DataTemplate示例
动态内容绑定
多行标题与格式设置
前景色与字体自定义
布局与定位选项

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

📄 阅读： references/sizing.md

ViewboxHeight属性配置
ViewboxWidth属性配置
响应式尺寸策略
容器与布局注意事项
保持宽高比
不同屏幕尺寸的示例
尺寸设置最佳实践

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

📄 阅读： references/methods.md

用于资源清理的Dispose()方法
受保护的重载方法Dispose(Boolean)
用于模板初始化的OnApplyTemplate()
用于处理动画类型变更的OnAnimationTypeChanged()
用于属性监控的OnPropertyChanged()
自定义控件扩展场景
模板部件访问模式
高级自定义示例

Quick Start Example

快速入门示例

Basic Busy Indicator

基础忙碌指示器

xml

<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>

xml

<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)

数据绑定（MVVM模式）

xml

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

csharp

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;
    }
}

xml

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

csharp

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

模式1：带忙碌指示器的异步操作

csharp

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;
        }
    }
}

csharp

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

模式2：自定义动画选择

xml

<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>

xml

<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

模式3：覆盖式忙碌指示器

xml

<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>

xml

<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

模式4：条件式标题

xml

<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>

xml

<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

核心属性

Property	Type	Description
IsBusy	bool	Controls whether the animation is displayed
AnimationType	AnimationTypes	Sets the animation style (Flight, Spin, etc.)
AnimationSpeed	double	Controls animation speed (not for Fluent type)
Header	object	Text or content displayed below animation
HeaderTemplate	DataTemplate	Custom template for header content
ViewboxHeight	double	Height of the animation viewbox
ViewboxWidth	double	Width of the animation viewbox

属性	类型	说明
IsBusy	bool	控制是否显示动画
AnimationType	AnimationTypes	设置动画样式（Flight、Spin等）
AnimationSpeed	double	控制动画速度（不适用于Fluent类型）
Header	object	显示在动画下方的文本或内容
HeaderTemplate	DataTemplate	标题内容的自定义模板
ViewboxHeight	double	动画视图框的高度
ViewboxWidth	double	动画视图框的宽度

Key Methods

核心方法

Method	Description
Dispose()	Releases managed and unmanaged resources
Dispose(Boolean)	Protected overload for resource cleanup
OnApplyTemplate()	Override to access template parts
OnAnimationTypeChanged()	Override to handle animation type changes
OnPropertyChanged()	Override to monitor property changes

方法	说明
Dispose()	释放托管和非托管资源
Dispose(Boolean)	用于资源清理的受保护重载方法
OnApplyTemplate()	重写以访问模板部件
OnAnimationTypeChanged()	重写以处理动画类型变更
OnPropertyChanged()	重写以监控属性变更

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.

从API、数据库或文件系统获取数据时显示忙碌指示器。将IsBusy绑定到视图模型中的加载状态。

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

最佳实践

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

始终与异步操作配合使用 - 确保在操作开始前设置IsBusy，完成后清除该状态
提供有意义的标题 - 使用描述性文本告知用户当前正在进行的操作
选择合适的动画 - 选择与应用主题和用途匹配的动画
考虑使用覆盖式方案 - 使用半透明覆盖层，在忙碌状态下阻止用户交互
正确处理异常 - 始终在finally块中重置IsBusy，避免指示器卡住
使用MVVM模式 - 将IsBusy绑定到视图模型属性，提升可测试性和可维护性
合理调整尺寸 - 根据重要性和可用屏幕空间调整指示器尺寸
保持主题一致性 - 使用Syncfusion主题，确保应用外观一致

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

避免使用可能影响渲染性能的复杂HeaderTemplate
根据使用场景选择合适的动画类型（频繁操作使用更简单的动画）
避免不必要地嵌套多个忙碌指示器
使用多个指示器时，考虑缓存动画资源

syncfusion-wpf-busy-indicator

Original

Translation

Implementing Syncfusion WPF Busy Indicator

Syncfusion WPF Busy Indicator控件实现指南

When to Use This Skill

何时使用该技能

Component Overview

组件概述

Key Features

核心特性

Assembly and Namespace

程序集与命名空间

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

Animation Configuration

动画配置

Display Control

显示控制

Header Customization

标题自定义

Sizing and Layout

尺寸与布局

Advanced Usage - Methods

高级用法 - 方法

Quick Start Example

快速入门示例

Basic Busy Indicator

基础忙碌指示器

With Data Binding (MVVM)

数据绑定（MVVM模式）

Common Patterns

常见模式

Pattern 1: Async Operation with Busy Indicator

模式1：带忙碌指示器的异步操作

Pattern 2: Custom Animation Selection

模式2：自定义动画选择

Pattern 3: Overlay Busy Indicator

模式3：覆盖式忙碌指示器

Pattern 4: Conditional Headers

模式4：条件式标题

Key Properties

核心属性

Key Methods

核心方法

Common Use Cases

常见使用场景

Data Loading Operations

数据加载操作

File Operations

文件操作

Background Processing

后台处理

Application Initialization

应用初始化

Search and Filter Operations

搜索与筛选操作

Navigation and Page Loading

导航与页面加载

Best Practices

最佳实践

Performance Tips

性能提示

Related Components

相关组件