syncfusion-winui-busy-indicator

SfBusyIndicator 是 Syncfusion WinUI 控件，用于显示预定义的动画指示器，以呈现忙碌或加载状态，提供 8 种内置动画类型以及对尺寸、颜色、持续时间和内容的广泛自定义选项。

命名空间：Syncfusion.UI.Xaml.Notifications NuGet 包：Syncfusion.Notifications.WinUI 平台：WinUI 3 桌面（.NET 5+，Windows App SDK 1.0+）

适用场景

当用户需要以下功能时使用本技能：在后台操作期间显示加载指示器；在异步任务期间向用户显示忙碌或等待状态；为数据加载、文件操作或 API 调用指示进度；创建模态或内联加载动画；在耗时操作期间提供视觉反馈；实现任何需要“请稍候”指示器的场景。

当用户在 WinUI 应用中提到加载指示器、忙碌指示器、进度动画、等待屏幕、异步操作反馈或后台任务通知时，应始终应用本技能。

组件概览

SfBusyIndicator 提供 8 种内置动画类型，并支持对尺寸（SizeFactor）、颜色（Color）、动画速度（DurationFactor）和内容（BusyContent）进行定制。文档与导航指南涵盖以下主题：

快速开始

安装与 NuGet 包设置；命名空间导入与基本初始化；用于控制可见性的 IsActive 属性；许可证注册要求；第一个完整示例。

动画类型

8 种内置动画类型（DottedCircularFluent、DottedCircle、DottedLinear 等）；AnimationType 属性用法；可视化示例与比较；如何为 UI 选择合适的动画；默认动画（DottedCircularFluent）。

内容与定位

BusyContent 属性用于自定义消息；BusyContentPosition（Top、Bottom、Left、Right）；BusyContentTemplate 用于高级自定义；自定义 DataTemplate 示例；内容显示最佳实践。

自定义选项

SizeFactor 属性（调整指示器大小）；DurationFactor 属性（动画速度控制）；Color 属性（指示器颜色自定义）；组合自定义属性；性能注意事项。

快速开始示例（XAML）

快速开始示例（C#）

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;

常见模式

简单加载指示器

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

适用：无需自定义的基本加载反馈。

使用代码隐藏的异步数据加载

private async void LoadDataAsync() { busyIndicator.IsActive = true;

try
{
    await FetchDataFromApiAsync();
}
finally
{
    busyIndicator.IsActive = false;
}

}

适用：在异步操作期间以编程方式控制忙碌状态。

带内容的自定义动画

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

适用：需要特定动画样式并自定义定位和颜色。

模态覆盖加载屏幕

<!-- Overlay BusyIndicator -->
<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 交互。

自定义内容模板

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

适用：需要比简单文本消息更丰富的内容。

缓慢动画以提供细微反馈

<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 | 系统强调色 | 动画指示器元素的颜色。

常见使用场景

数据加载场景

从 REST API 或数据库获取数据；将大型数据集加载到网格或列表；刷新仪表板内容；启动时初始化应用数据。最佳动画：DottedCircularFluent、DottedCircle。

文件操作

上传/下载文件；读取/写入大文件；导入/导出数据；处理文档。最佳动画：LinearFluent、LinearBox。

长时间运行的计算

复杂数据分析；报表生成；图像处理；搜索操作。最佳动画：DoubleCircle、SingleCircle。

后台任务

同步操作；缓存更新；后台服务通信；计划任务。最佳动画：LinearOscillatingBox、DottedLinear（细微）。

实现提示

绑定 IsActive：使用数据绑定到 ViewModel 的布尔属性，实现整洁的 MVVM 模式。

覆盖模式：对于模态加载，使用带有半透明背景的 Grid 包含 BusyIndicator。

性能：BusyIndicator 动画由 GPU 加速。多个实例没有性能顾虑。

无障碍：控件自动处理无障碍功能。自定义内容应包含适当的无障碍属性。

线程：始终在 UI 线程上激活/停用 BusyIndicator。从后台线程更新时使用 DispatcherQueue。

用户体验：

对于预计耗时超过 500ms 的操作，立即显示 BusyIndicator；

操作完成时始终隐藏（使用 try-finally 块）；

根据 UI 上下文适当定位内容；

选择与应用设计语言匹配的动画类型。

技能介绍