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

常见使用场景

数据加载场景

• 从 REST API 或数据库获取数据
• 将大型数据集加载到网格或列表中
• 刷新仪表板内容
• 启动时初始化应用程序数据

推荐动画： DottedCircularFluent、DottedCircle

文件操作

• 上传/下载文件
• 读取/写入大型文件
• 导入/导出数据
• 处理文档

推荐动画： LinearFluent、LinearBox

长时间运行的计算

• 复杂的数据分析
• 生成报告
• 图像处理
• 搜索操作

推荐动画： DoubleCircle、SingleCircle

后台任务

• 同步操作
• 更新缓存
• 与后台服务通信
• 计划任务

推荐动画： LinearOscillatingBox、DottedLinear（较为轻柔）

实现提示

1. 绑定 IsActive： 使用数据绑定将其关联到 ViewModel 布尔属性，以遵循清晰的 MVVM 模式。

2. 叠加模式： 对于模态加载，可使用带半透明背景的 Grid，并在其中放置 BusyIndicator。

3. 性能： BusyIndicator 动画由 GPU 加速。多个实例不会带来性能问题。

4. 辅助功能： 控件会自动处理辅助功能。自定义内容应包含适当的辅助功能属性。

5. 线程： 始终在 UI 线程上启用/停用 BusyIndicator。从后台线程更新时，请使用 DispatcherQueue。

6. 用户体验：

   • 对于预计耗时超过 500 ms 的操作，应立即显示 BusyIndicator
   • 操作完成时务必隐藏（使用 try-finally 块）
   • 根据 UI 上下文妥善放置内容
   • 选择与应用程序设计语言相符的动画类型

相关文档

• 动画类型： 请参阅 references/animation-types.md，了解全部 8 种动画样式的详细比较
• 内容自定义： 请参阅 references/content.md，了解模板示例和位置策略
• 自定义： 请参阅 references/customization.md，了解大小、速度和颜色选项