syncfusion-wpf-busy-indicator

实现 Syncfusion WPF 忙碌指示器

Syncfusion® WPF 忙碌指示器控件的全面实现指南。SfBusyIndicator 提供 37 种以上内置动画、可自定义标题和完整的 MVVM 支持，可在长时间运行的操作期间提供视觉反馈。

何时使用此技能

在以下情况下使用此技能：

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

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

组件概览

SfBusyIndicator 控件提供灵活且可自定义的方式，可在 WPF 应用程序中显示加载指示器：

主要功能

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

程序集和命名空间

• 程序集： Syncfusion.SfBusyIndicator.WPF
• 命名空间： Syncfusion.Windows.Controls.Notification
• NuGet 包： Syncfusion.SfBusyIndicator.WPF

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 通过 NuGet 包管理器安装
• 程序集引用和命名空间导入
• 许可证配置和注册
• 在 XAML 和代码隐藏中进行基本实现
• 主题设置和配置
• 最小可运行示例
• GitHub 示例存储库链接

动画配置

📄 阅读： references/animation-types.md

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

显示控制

📄 阅读： references/isbusy-property.md

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

标题自定义

📄 阅读： references/header-customization.md

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

尺寸和布局

📄 阅读： references/sizing.md

• ViewboxHeight 属性配置
• ViewboxWidth 属性配置
• 响应式尺寸调整策略
• 容器和布局注意事项
• 保持纵横比
• 适用于不同屏幕尺寸的示例
• 尺寸调整最佳实践

高级用法 - 方法

📄 阅读： references/methods.md

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

快速入门示例

基本忙碌指示器

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

使用数据绑定（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;
    }
}

常见模式

模式 1：使用忙碌指示器执行异步操作

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

模式 2：自定义动画选择

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

模式 3：叠加忙碌指示器

<Grid>
    
    <ContentControl Content="{Binding MainContent}"/>
    
    
    <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>

模式 4：条件标题

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

关键属性

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

关键方法

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

常见用例

数据加载操作

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

文件操作

上传、下载或处理文件时，显示加载反馈，并使用信息性标题说明当前操作。

后台处理

使用合适的动画类型和消息，提示后台任务正在运行（例如计算、图像处理和批量操作）。

应用程序初始化

应用程序启动时，加载配置、用户设置或初始数据的过程中显示忙碌指示器。

搜索和筛选操作

对大型数据集执行复杂的搜索或筛选操作时，提供视觉反馈。

导航和页面加载

在基于导航的应用程序中，切换视图或加载页面内容时显示忙碌指示器。

最佳实践

1. 始终配合异步操作使用 - 确保在开始操作前设置 IsBusy，并在操作完成后清除
2. 提供有意义的标题 - 使用描述性文本告知用户当前正在进行的操作
3. 选择合适的动画 - 选择与应用程序主题和用途相符的动画
4. 考虑使用叠加层 - 使用半透明叠加层，防止用户在忙碌状态下进行交互
5. 正确处理异常 - 始终在 finally 块中重置 IsBusy，避免指示器卡住
6. 使用 MVVM 模式 - 将 IsBusy 绑定到视图模型属性，以提高可测试性和可维护性
7. 适当调整大小 - 根据指示器的重要性和可用屏幕空间调整其大小
8. 保持主题一致 - 使用 Syncfusion 主题，确保应用程序外观一致

性能提示

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

相关组件

• ProgressBar - 用于显示带百分比的确定进度
• Toast - 用于显示简短的通知消息
• Message - 用于显示带操作的用户通知
• Skeleton - 用于显示内容占位动画

后续步骤： 根据具体的实现需求，浏览上面的参考文件。初始设置请从 getting-started.md 开始；如需了解高级场景，可直接跳转到特定功能的参考文件。