syncfusion-winui-busy-indicator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing WinUI BusyIndicator

实现WinUI BusyIndicator

When to Use This Skill

何时使用本指南

Use this skill when the user needs to:

Display a loading indicator during background operations
Show busy/waiting status to users during async tasks
Indicate progress for data loading, file operations, or API calls
Create modal or inline loading animations
Provide visual feedback during lengthy operations
Implement any scenario requiring "please wait" indicators

Always apply this skill when the user mentions: loading indicators, busy indicators, progress animations, waiting screens, async operation feedback, or background task notifications in WinUI applications.

当用户需要完成以下操作时使用本指南：

在后台运行操作时展示加载指示器
在异步任务执行过程中向用户展示忙碌/等待状态
提示数据加载、文件操作或API调用的进度
创建模态或行内加载动画
在耗时操作过程中提供视觉反馈
实现所有需要"请稍候"提示的场景

当用户提及WinUI应用中的加载指示器、忙碌指示器、进度动画、等待界面、异步操作反馈或后台任务通知时，务必使用本指南。

Component Overview

组件概览

SfBusyIndicator is a Syncfusion WinUI control that displays predefined animated indicators to show busy/loading status. It provides 8 built-in animation types and extensive customization options for size, color, duration, and content.

Namespace:

Syncfusion.UI.Xaml.Notifications

NuGet Package:

Syncfusion.Notifications.WinUI

Platform: WinUI 3 Desktop (.NET 5+, Windows App SDK 1.0+)

SfBusyIndicator 是Syncfusion推出的WinUI控件，可展示预定义的动画指示器来显示忙碌/加载状态。它提供8种内置动画类型，支持对尺寸、颜色、动画时长和展示内容进行高度自定义。

命名空间：

Syncfusion.UI.Xaml.Notifications

NuGet包：

Syncfusion.Notifications.WinUI

支持平台： WinUI 3 桌面端 (.NET 5+, Windows App SDK 1.0+)

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and NuGet package setup
Namespace imports and basic initialization
IsActive property for controlling visibility
License registration requirements
First complete example

📄 阅读： references/getting-started.md

安装与NuGet包配置
命名空间导入与基础初始化
控制可见性的IsActive属性
许可证注册要求
首个完整示例

Animation Types

动画类型

📄 Read: references/animation-types.md

8 built-in animation types (DottedCircularFluent, DottedCircle, DottedLinear, etc.)
AnimationType property usage
Visual examples and comparisons
Choosing the right animation for your UI
Default animation (DottedCircularFluent)

📄 阅读： references/animation-types.md

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

Content and Positioning

内容与定位

📄 Read: references/content.md

BusyContent property for custom messages
BusyContentPosition (Top, Bottom, Left, Right)
BusyContentTemplate for advanced customization
Custom DataTemplate examples
Content display best practices

📄 阅读： references/content.md

用于展示自定义消息的BusyContent属性
BusyContentPosition（顶部、底部、左侧、右侧）
支持高级自定义的BusyContentTemplate
自定义DataTemplate示例
内容展示最佳实践

Customization Options

自定义选项

📄 Read: references/customization.md

SizeFactor property (adjusting indicator size)
DurationFactor property (animation speed control)
Color property (indicator color customization)
Combining customization properties
Performance considerations

📄 阅读： references/customization.md

SizeFactor属性（调整指示器尺寸）
DurationFactor属性（控制动画速度）
Color属性（自定义指示器颜色）
自定义属性组合使用
性能注意事项

Quick Start Example

快速入门示例

xaml

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

csharp

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;

xaml

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

csharp

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;

Common Patterns

常用场景模式

1. Simple Loading Indicator

1. 基础加载指示器

xaml

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

When to use: Basic loading feedback without customization.

xaml

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

适用场景： 无需自定义的基础加载反馈。

2. Async Data Loading with Code-Behind

2. 后台代码实现异步数据加载

xaml

<Grid>
    <notification:SfBusyIndicator 
        x:Name="busyIndicator"
        IsActive="{x:Bind ViewModel.IsLoading, Mode=OneWay}"
        AnimationType="DottedCircle"
        BusyContent="Loading data..."/>
</Grid>

csharp

private async void LoadDataAsync()
{
    busyIndicator.IsActive = true;
    
    try
    {
        await FetchDataFromApiAsync();
    }
    finally
    {
        busyIndicator.IsActive = false;
    }
}

When to use: Control busy state programmatically during async operations.

xaml

<Grid>
    <notification:SfBusyIndicator 
        x:Name="busyIndicator"
        IsActive="{x:Bind ViewModel.IsLoading, Mode=OneWay}"
        AnimationType="DottedCircle"
        BusyContent="Loading data..."/>
</Grid>

csharp

private async void LoadDataAsync()
{
    busyIndicator.IsActive = true;
    
    try
    {
        await FetchDataFromApiAsync();
    }
    finally
    {
        busyIndicator.IsActive = false;
    }
}

适用场景： 在异步操作过程中通过代码控制忙碌状态。

3. Custom Animation with Content

3. 带内容的自定义动画

xaml

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

When to use: Need specific animation style with custom positioning and colors.

xaml

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

适用场景： 需要特定动画样式，同时自定义位置和颜色。

4. Modal Overlay Loading Screen

4. 模态遮罩加载界面

xaml

<Grid>
    <!-- Main content -->
    <StackPanel>
        <TextBlock Text="Application Content"/>
        <!-- Other UI elements -->
    </StackPanel>
    
    <!-- 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>

When to use: Block UI interaction during critical operations.

xaml

<Grid>
    <!-- Main content -->
    <StackPanel>
        <TextBlock Text="Application Content"/>
        <!-- Other UI elements -->
    </StackPanel>
    
    <!-- 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交互。

5. Custom Content Template

5. 自定义内容模板

xaml

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

When to use: Need rich content beyond simple text messages.

xaml

<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. Slow Animation for Subtle Feedback

6. 慢动画实现轻度反馈

xaml

<notification:SfBusyIndicator 
    IsActive="True"
    AnimationType="SingleCircle"
    DurationFactor="0.9"
    SizeFactor="0.3"
    Color="Gray"/>

When to use: Provide subtle background activity indication without distracting users.

xaml

<notification:SfBusyIndicator 
    IsActive="True"
    AnimationType="SingleCircle"
    DurationFactor="0.9"
    SizeFactor="0.3"
    Color="Gray"/>

适用场景： 提示后台活动状态，同时不会分散用户注意力。

Key Properties

核心属性

Property	Type	Default	Description
`IsActive`	bool	false	Controls whether the indicator is visible and animating. Set to `true` to show, `false` to hide.
`AnimationType`	BusyIndicatorAnimationType	DottedCircularFluent	The animation style. Options: DottedCircularFluent, DottedCircle, DottedLinear, DoubleCircle, LinearBox, LinearFluent, LinearOscillatingBox, SingleCircle.
`BusyContent`	object	null	The content displayed below/above/beside the indicator (typically a message).
`BusyContentPosition`	BusyIndicatorContentPosition	Bottom	Position of content relative to indicator. Options: Top, Bottom, Left, Right.
`BusyContentTemplate`	DataTemplate	null	Custom template for the busy content. Allows rich content beyond simple text.
`SizeFactor`	double	0.5	Controls the size of the indicator. Range: 0.0 to 1.0. Higher values = larger indicator.
`DurationFactor`	double	0.5	Controls animation speed. Range: 0.0 to 1.0. Higher values = slower animation.
`Color`	Brush	System accent color	The color of the animated indicator elements.

属性名	类型	默认值	说明
`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	系统强调色	动画指示器元素的颜色。

Common Use Cases

常见使用场景

Data Loading Scenarios

数据加载场景

Fetching data from REST APIs or databases
Loading large datasets into grids or lists
Refreshing dashboard content
Initializing application data on startup

Best Animation: DottedCircularFluent, DottedCircle

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

推荐动画： DottedCircularFluent、DottedCircle

File Operations

文件操作

Uploading/downloading files
Reading/writing large files
Importing/exporting data
Processing documents

Best Animation: LinearFluent, LinearBox

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

推荐动画： LinearFluent、LinearBox

Long-Running Calculations

长时间运行的计算

Complex data analysis
Report generation
Image processing
Search operations

Best Animation: DoubleCircle, SingleCircle

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

推荐动画： DoubleCircle、SingleCircle

Background Tasks

后台任务

Synchronization operations
Cache updates
Background service communication
Scheduled tasks

Best Animation: LinearOscillatingBox, DottedLinear (subtle)

同步操作
缓存更新
与后台服务通信
定时任务

推荐动画： LinearOscillatingBox、DottedLinear（轻度提示）

Implementation Tips

实现建议

Binding IsActive: Use data binding to ViewModel boolean properties for clean MVVM patterns.
Overlay Pattern: For modal loading, use a Grid with semi-transparent background containing the BusyIndicator.
Performance: BusyIndicator animations are GPU-accelerated. No performance concerns for multiple instances.
Accessibility: The control automatically handles accessibility features. Custom content should include proper accessibility properties.
Threading: Always activate/deactivate BusyIndicator on the UI thread. Use
```
DispatcherQueue
```
if updating from background threads.
User Experience:
- Show BusyIndicator immediately for operations expected to take >500ms
- Always hide when operation completes (use try-finally blocks)
- Position content appropriately for the UI context
- Choose animation types that match your app's design language

绑定IsActive属性： 采用MVVM模式时，将属性与ViewModel的布尔值绑定，代码更简洁。
遮罩模式： 实现模态加载时，使用带有半透明背景的Grid容器包裹BusyIndicator。
性能： BusyIndicator的动画是GPU加速的，多实例使用也不会有性能问题。
无障碍支持： 控件自带无障碍适配功能，自定义内容需要补充合适的无障碍属性。
线程操作： 始终在UI线程中激活/隐藏BusyIndicator，如果从后台线程更新状态请使用
```
DispatcherQueue
```
。
用户体验：
- 预计耗时超过500ms的操作需要立即展示BusyIndicator
- 操作完成后务必隐藏指示器（建议使用try-finally代码块）
- 根据UI场景合理调整内容位置
- 选择符合应用设计语言的动画类型

syncfusion-winui-busy-indicator

Original

Translation

Implementing WinUI BusyIndicator

实现WinUI BusyIndicator

When to Use This Skill

何时使用本指南

Component Overview

组件概览

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

Animation Types

动画类型

Content and Positioning

内容与定位

Customization Options

自定义选项

Quick Start Example

快速入门示例

Common Patterns

常用场景模式

1. Simple Loading Indicator

1. 基础加载指示器

2. Async Data Loading with Code-Behind

2. 后台代码实现异步数据加载

3. Custom Animation with Content

3. 带内容的自定义动画

4. Modal Overlay Loading Screen

4. 模态遮罩加载界面

5. Custom Content Template

5. 自定义内容模板

6. Slow Animation for Subtle Feedback

6. 慢动画实现轻度反馈

Key Properties

核心属性

Common Use Cases

常见使用场景

Data Loading Scenarios

数据加载场景

File Operations

文件操作

Long-Running Calculations

长时间运行的计算

Background Tasks

后台任务

Implementation Tips

实现建议

Related Documentation

相关文档