syncfusion-blazor-progress-bar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Blazor ProgressBar

实现Syncfusion Blazor ProgressBar

When to Use This Skill

适用场景

Use this skill when the user needs to:

Display progress for file uploads, downloads, or data processing
Show loading states with determinate or indeterminate progress
Visualize task completion percentages
Implement buffer states for media players or streaming content
Create circular or linear progress indicators
Add progress tracking with custom styling and animations
Show multi-stage progress with segments
Implement accessible progress indicators with WCAG compliance
Display progress with annotations, labels, or custom formatting

当用户需要以下功能时，可使用本指南：

显示文件上传、下载或数据处理的进度
显示确定或不确定状态的加载进度
可视化任务完成百分比
为媒体播放器或流媒体内容实现缓冲状态
创建圆形或线性进度指示器
添加带有自定义样式和动画的进度追踪
显示分段式多阶段进度
实现符合WCAG标准的无障碍进度指示器
显示带有注释、标签或自定义格式的进度

Component Overview

组件概述

The Syncfusion Blazor ProgressBar component is a visual indicator that displays the progress of an operation. It supports both linear and circular types, multiple states (determinate, indeterminate, buffer, active, striped), extensive customization options, animations, and full accessibility support.

Syncfusion Blazor ProgressBar组件是一个可视化指示器，用于显示操作的进度。它支持线性和圆形两种类型，多种状态（确定、不确定、缓冲、激活、条纹），丰富的自定义选项、动画效果，以及完整的无障碍支持。

API Reference

API参考

📄 Read: references/api-reference.md

Use this reference when you need the exact ProgressBar API surface, including:

SfProgressBar

properties such as

Value

Type

Role

Theme

Visible

ID

StartAngle

EndAngle

, and

RefreshAsync()

Child components such as

ProgressBarAnimation

ProgressBarEvents

ProgressBarAnnotations

ProgressBarAnnotation

ProgressBarLabelStyle

ProgressBarMargin

ProgressBarRangeColor

, and

ProgressBarRangeColors

Event callbacks such as

ValueChanged

ProgressCompleted

AnimationComplete

AnnotationRender

TextRender

, and

Loaded

Enums such as

ProgressType

CornerType

ModeType

, and

TextAlignmentType

Key Capabilities:

Types: Linear (horizontal bar) and Circular (donut/pie chart style)
States: Determinate (known progress), Indeterminate (unknown progress), Buffer (dual progress), Active (animated), Striped (visual pattern)
Customization: Colors, thickness, segments, radius, corners, margins, RTL support
Features: Annotations, labels, range colors, gradients, secondary progress
Animation: Configurable speed and delay
Events: Value changes, completion, animation lifecycle
Accessibility: WCAG 2.2 compliant with keyboard navigation

📄 阅读： references/api-reference.md

当您需要ProgressBar的完整API详情时，可参考此文档，包括：

SfProgressBar

的属性，如

Value

、

Type

、

Role

、

Theme

、

Visible

、

ID

、

StartAngle

、

EndAngle

和

RefreshAsync()

子组件，如

ProgressBarAnimation

、

ProgressBarEvents

、

ProgressBarAnnotations

、

ProgressBarAnnotation

、

ProgressBarLabelStyle

、

ProgressBarMargin

、

ProgressBarRangeColor

和

ProgressBarRangeColors

事件回调，如

ValueChanged

、

ProgressCompleted

、

AnimationComplete

、

AnnotationRender

、

TextRender

和

Loaded

枚举类型，如

ProgressType

、

CornerType

、

ModeType

和

TextAlignmentType

核心功能：

类型： 线性（水平条形）和圆形（环形/饼图样式）
状态： 确定（已知进度）、不确定（未知进度）、缓冲（双重进度）、激活（动画效果）、条纹（视觉图案）
自定义： 颜色、厚度、分段、半径、边角、边距、RTL支持
特性： 注释、标签、范围颜色、渐变、次级进度
动画： 可配置速度和延迟
事件： 值变化、完成、动画生命周期
无障碍： 符合WCAG 2.2标准，支持键盘导航

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

When the user needs to set up the ProgressBar for the first time, guide them to this reference for:

Prerequisites and system requirements
Installation via Visual Studio, VS Code, or .NET CLI
NuGet package installation (Syncfusion.Blazor.ProgressBar)
Namespace imports and service registration
Adding stylesheet and script references
Basic linear and circular ProgressBar implementation
First working example

📄 阅读： references/getting-started.md

当用户首次设置ProgressBar时，可引导他们参考此文档获取以下信息：

前提条件和系统要求
通过Visual Studio、VS Code或.NET CLI进行安装
NuGet包安装（Syncfusion.Blazor.ProgressBar）
命名空间导入和服务注册
添加样式表和脚本引用
基础线性和圆形ProgressBar实现
第一个可运行示例

Types and Modes

类型与模式

📄 Read: references/types-and-modes.md

When the user asks about or needs:

Linear vs Circular ProgressBar types
Choosing the right type for their use case
Implementing basic linear progress bars
Implementing circular/donut progress bars
Pie progress mode for circular bars
Segments in linear or circular types
Secondary progress indicators
Complete type-specific examples

📄 阅读： references/types-and-modes.md

当用户询问或需要以下内容时：

线性与圆形ProgressBar类型对比
根据使用场景选择合适的类型
实现基础线性进度条
实现圆形/环形进度条
圆形进度条的饼图模式
线性或圆形类型的分段功能
次级进度指示器
完整的类型特定示例

States and Behavior

状态与行为

📄 Read: references/states-and-behavior.md

When the user asks about or needs:

Determinate progress (known completion percentage)
Indeterminate progress (loading without known duration)
Buffer state (dual progress for media/streaming)
Active state (animated progress indicator)
Striped visual pattern (linear only)
Range configuration (Minimum/Maximum values)
Combining multiple states
Choosing the right state for their scenario

📄 阅读： references/states-and-behavior.md

当用户询问或需要以下内容时：

确定进度（已知完成百分比）
不确定进度（无已知时长的加载）
缓冲状态（媒体/流媒体的双重进度）
激活状态（动画进度指示器）
条纹视觉图案（仅线性支持）
范围配置（最小值/最大值）
多种状态组合
根据场景选择合适的状态

Customization

自定义配置

📄 Read: references/customization.md

When the user asks about or needs:

Dividing progress into segments with custom colors
Adjusting track, progress, or secondary progress thickness
Customizing radius and inner radius (circular)
Rounded corners (CornerRadius)
Custom colors for progress, track, and secondary progress
Range colors with gradient effects
RTL (right-to-left) support
Visibility control (showing/hiding progress bar)
Margin and spacing adjustments
Complete visual customization examples

📄 阅读： references/customization.md

当用户询问或需要以下内容时：

将进度划分为带有自定义颜色的分段
调整轨道、进度或次级进度的厚度
自定义圆形进度条的半径和内半径
圆角（CornerRadius）
进度、轨道和次级进度的自定义颜色
带渐变效果的范围颜色
RTL（从右到左）支持
可见性控制（显示/隐藏进度条）
边距和间距调整
完整的视觉自定义示例

Annotations and Labels

注释与标签

📄 Read: references/annotations-and-labels.md

When the user asks about or needs:

Adding text annotations to the progress bar
Custom HTML or component overlays
Showing progress percentage labels
Custom label formatting (TextRender event)
Positioning annotations
Multiple annotations
Styling annotations and labels
Combining annotations with labels

📄 阅读： references/annotations-and-labels.md

当用户询问或需要以下内容时：

为进度条添加文本注释
自定义HTML或组件覆盖层
显示进度百分比标签
自定义标签格式（TextRender事件）
注释定位
多注释配置
注释和标签样式
注释与标签组合使用

Animation

动画效果

📄 Read: references/animation.md

When the user asks about or needs:

Enabling progress animations
Controlling animation speed (Duration)
Adding animation delays
Animation with different states
AnimationComplete event handling
Performance considerations
Smooth progress transitions

📄 阅读： references/animation.md

当用户询问或需要以下内容时：

启用进度动画
控制动画速度（Duration）
添加动画延迟
不同状态下的动画
AnimationComplete事件处理
性能考量
平滑的进度过渡

Events and Accessibility

事件与无障碍

📄 Read: references/events-and-accessibility.md

When the user asks about or needs:

ValueChanged event (tracking progress changes)
ProgressCompleted event (when progress reaches maximum)
AnimationComplete event (animation lifecycle)
AnnotationRender event (customizing annotations)
TextRender event (custom label formatting)
Loaded event (component initialization)
WCAG 2.2 and Section 508 compliance
Keyboard navigation support
Screen reader compatibility
Color contrast and accessibility standards
Mobile device support

📄 阅读： references/events-and-accessibility.md

当用户询问或需要以下内容时：

ValueChanged事件（追踪进度变化）
ProgressCompleted事件（进度达到最大值时）
AnimationComplete事件（动画生命周期）
AnnotationRender事件（自定义注释）
TextRender事件（自定义标签格式）
Loaded事件（组件初始化）
WCAG 2.2和Section 508合规性
键盘导航支持
屏幕阅读器兼容性
颜色对比度和无障碍标准
移动设备支持

Quick Start Example

快速入门示例

Linear ProgressBar (Basic)

基础线性ProgressBar

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="70" 
               Minimum="0" 
               Maximum="100"
               Height="60"
               TrackThickness="12" 
               ProgressThickness="12">
</SfProgressBar>

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="70" 
               Minimum="0" 
               Maximum="100"
               Height="60"
               TrackThickness="12" 
               ProgressThickness="12">
</SfProgressBar>

Circular ProgressBar (Basic)

基础圆形ProgressBar

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="75" 
               Minimum="0" 
               Maximum="100"
               Height="160px"
               Width="160px"
               TrackThickness="8" 
               ProgressThickness="8">
</SfProgressBar>

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="75" 
               Minimum="0" 
               Maximum="100"
               Height="160px"
               Width="160px"
               TrackThickness="8" 
               ProgressThickness="8">
</SfProgressBar>

Indeterminate Loading State

不确定加载状态

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="20" 
               IsIndeterminate="true"
               Height="60"
               Minimum="0" 
               Maximum="100">
    <ProgressBarAnimation Enable="true" Duration="2000"></ProgressBarAnimation>
</SfProgressBar>

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="20" 
               IsIndeterminate="true"
               Height="60"
               Minimum="0" 
               Maximum="100">
    <ProgressBarAnimation Enable="true" Duration="2000"></ProgressBarAnimation>
</SfProgressBar>

Common Patterns

常见模式

Pattern 1: File Upload Progress

模式1：文件上传进度

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="@uploadProgress" 
               ShowProgressValue="true"
               Height="60"
               ProgressColor="#28a745"
               TrackColor="#e9ecef"
               CornerRadius="CornerType.Round">
    <ProgressBarEvents ProgressCompleted="OnUploadComplete"></ProgressBarEvents>
</SfProgressBar>

@code {
    private double uploadProgress = 0;
    
    private void OnUploadComplete(ProgressValueEventArgs args)
    {
        // Handle upload completion
    }
}

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="@uploadProgress" 
               ShowProgressValue="true"
               Height="60"
               ProgressColor="#28a745"
               TrackColor="#e9ecef"
               CornerRadius="CornerType.Round">
    <ProgressBarEvents ProgressCompleted="OnUploadComplete"></ProgressBarEvents>
</SfProgressBar>

@code {
    private double uploadProgress = 0;
    
    private void OnUploadComplete(ProgressValueEventArgs args)
    {
        // Handle upload completion
    }
}

Pattern 2: Multi-Stage Progress with Segments

模式2：分段式多阶段进度

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="100" 
               Height="60"
               SegmentCount="4"
               SegmentColor='new string[] { "#00bdaf", "#2f7ecc", "#e9648e", "#fbb78a" }'>
</SfProgressBar>

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="100" 
               Height="60"
               SegmentCount="4"
               SegmentColor='new string[] { "#00bdaf", "#2f7ecc", "#e9648e", "#fbb78a" }'>
</SfProgressBar>

Pattern 3: Buffer State for Media Player

模式3：媒体播放器缓冲状态

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="@currentProgress" 
               SecondaryProgress="@bufferProgress"
               Height="60"
               ProgressColor="#ff4081"
               SecondaryProgressColor="#ff80ab">
</SfProgressBar>

@code {
    private double currentProgress = 0;
    private double bufferProgress = 0;

    protected override void OnInitialized()
    {
        // Sample values for testing
        currentProgress = 40;   // main progress
        bufferProgress = 70;    // secondary buffer progress
    }
}

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Linear" 
               Value="@currentProgress" 
               SecondaryProgress="@bufferProgress"
               Height="60"
               ProgressColor="#ff4081"
               SecondaryProgressColor="#ff80ab">
</SfProgressBar>

@code {
    private double currentProgress = 0;
    private double bufferProgress = 0;

    protected override void OnInitialized()
    {
        // Sample values for testing
        currentProgress = 40;   // main progress
        bufferProgress = 70;    // secondary buffer progress
    }
}

Pattern 4: Circular Progress with Annotation

模式4：带注释的圆形进度

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="80" 
               Height="160px" 
               Width="160px"
               TrackThickness="10" 
               ProgressThickness="10"
               ProgressColor="#e91e63">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="font-size:24px; font-weight:bold; color:#e91e63;">
                    80%
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

razor

@using Syncfusion.Blazor.ProgressBar

<SfProgressBar Type="ProgressType.Circular" 
               Value="80" 
               Height="160px" 
               Width="160px"
               TrackThickness="10" 
               ProgressThickness="10"
               ProgressColor="#e91e63">
    <ProgressBarAnnotations>
        <ProgressBarAnnotation>
            <ContentTemplate>
                <div style="font-size:24px; font-weight:bold; color:#e91e63;">
                    80%
                </div>
            </ContentTemplate>
        </ProgressBarAnnotation>
    </ProgressBarAnnotations>
</SfProgressBar>

Key Props Reference

核心属性参考

Core Properties

基础属性

Type:

ProgressType.Linear

ProgressType.Circular

- Progress bar type

Value: Current progress value within the configured range
Minimum: Minimum range value
Maximum: Maximum range value
Height: Component height
Width: Component width
ID: Component identifier for programmatic targeting
ChildContent: Custom child content inside the component

Type:

ProgressType.Linear

或

ProgressType.Circular

- 进度条类型

Value: 当前进度值，需在配置的范围内
Minimum: 范围最小值
Maximum: 范围最大值
Height: 组件高度
Width: 组件宽度
ID: 组件标识符，用于程序化定位
ChildContent: 组件内部的自定义子内容

State Properties

状态属性

IsIndeterminate: Enable indeterminate loading state (unknown duration)
SecondaryProgress: Secondary progress value for buffer state
IsActive: Enable active animated state
IsStriped: Enable striped pattern (linear only)
Role: Progress indication mode (
```
ModeType.Auto
```
,
```
Success
```
,
```
Info
```
,
```
Danger
```
,
```
Warning
```
)
Theme: Visual theme for the ProgressBar
EnableRtl: Right-to-left rendering support
Visible: Show or hide the component

IsIndeterminate: 启用不确定加载状态（未知时长）
SecondaryProgress: 缓冲状态下的次级进度值
IsActive: 启用激活动画状态
IsStriped: 启用条纹图案（仅线性支持）
Role: 进度指示模式（
```
ModeType.Auto
```
,
```
Success
```
,
```
Info
```
,
```
Danger
```
,
```
Warning
```
）
Theme: ProgressBar的视觉主题
EnableRtl: 启用从右到左渲染
Visible: 显示或隐藏组件

Customization Properties

自定义属性

ProgressColor: Progress indicator color
TrackColor: Background track color
SecondaryProgressColor: Secondary progress color
ProgressThickness: Progress bar thickness
TrackThickness: Track thickness
SecondaryProgressThickness: Secondary progress thickness
CornerRadius: Edge rounding (
```
CornerType.Auto
```
,
```
Square
```
,
```
Round
```
,
```
Round4px
```
)
SegmentCount: Divide progress into segments
SegmentColor: Array of colors for segments
EnableProgressSegments: Segments without track background
EnablePieProgress: Circular pie-style rendering
Radius: Circular progress radius
InnerRadius: Circular inner radius
GapWidth: Gap width between segments
StartAngle: Circular start angle
EndAngle: Circular end angle
IsGradient: Enable gradient rendering

ProgressColor: 进度指示器颜色
TrackColor: 背景轨道颜色
SecondaryProgressColor: 次级进度颜色
ProgressThickness: 进度条厚度
TrackThickness: 轨道厚度
SecondaryProgressThickness: 次级进度厚度
CornerRadius: 边角圆角（
```
CornerType.Auto
```
,
```
Square
```
,
```
Round
```
,
```
Round4px
```
）
SegmentCount: 将进度划分为分段的数量
SegmentColor: 分段颜色数组
EnableProgressSegments: 无轨道背景的分段
EnablePieProgress: 圆形进度条的饼图样式渲染
Radius: 圆形进度条半径
InnerRadius: 圆形进度条内半径
GapWidth: 分段之间的间隙宽度
StartAngle: 圆形进度条起始角度
EndAngle: 圆形进度条结束角度
IsGradient: 启用渐变渲染

Display Properties

显示属性

ShowProgressValue: Show percentage label
EnablePieProgress: Fill circular progress as pie chart

ShowProgressValue: 显示百分比标签
EnablePieProgress: 将圆形进度条渲染为饼图样式

Animation Properties

动画属性

Use

<ProgressBarAnimation>

child component:

Enable: Enable animation
Duration: Animation duration in milliseconds
Delay: Animation start delay in milliseconds

使用

<ProgressBarAnimation>

子组件：

Enable: 启用动画
Duration: 动画时长（毫秒）
Delay: 动画启动延迟（毫秒）

Methods

方法

RefreshAsync(): Re-render the ProgressBar when the state changes outside the normal render flow

RefreshAsync(): 当状态在正常渲染流程外发生变化时，重新渲染ProgressBar

Common Use Cases

常见使用场景

Use Case 1: Simple Loading Indicator

场景1：简单加载指示器

Scenario: Show a loading bar while fetching data Implementation: Use indeterminate linear progress bar with animation

场景描述： 获取数据时显示加载条 实现方式： 使用带动画的不确定线性进度条

Use Case 2: File Upload with Percentage

场景2：带百分比的文件上传

Scenario: Display file upload progress with percentage Implementation: Determinate progress with

ShowProgressValue="true"

场景描述： 显示文件上传进度及百分比 实现方式： 确定进度条，设置

ShowProgressValue="true"

Use Case 3: Multi-Step Wizard

场景3：多步骤向导

Scenario: Show progress through a multi-step form Implementation: Segmented progress bar with step count as segments

场景描述： 显示多步骤表单的进度 实现方式： 分段式进度条，步骤数对应分段数量

Use Case 4: Video Buffer State

场景4：视频缓冲状态

Scenario: Show playback position and buffered content Implementation: Buffer state with primary (playback) and secondary (buffered) progress

场景描述： 显示播放位置和已缓冲内容 实现方式： 缓冲状态，包含主进度（播放）和次级进度（缓冲）

Use Case 5: Dashboard KPI Indicator

场景5：仪表盘KPI指示器

Scenario: Circular progress showing goal completion Implementation: Circular progress with annotation showing percentage and target

场景描述： 圆形进度显示目标完成情况 实现方式： 带注释的圆形进度条，显示百分比和目标

Use Case 6: Download Progress with Time Estimate

场景6：带时间预估的下载进度

Scenario: Show download progress with custom time remaining label Implementation: Linear progress with TextRender event for custom formatting

场景描述： 显示下载进度及自定义剩余时间标签 实现方式： 线性进度条，使用TextRender事件自定义格式

Use Case 7: Determinate Task Progress

场景7：确定任务进度

Scenario: Show progress of a batch operation with known steps Implementation: Determinate progress bar updating Value as each step completes

场景描述： 显示已知步骤的批量操作进度 实现方式： 确定进度条，每完成一步更新Value值

Best Practices

最佳实践

Choose the Right Type:
- Use Linear for horizontal layouts, file operations, loading bars
- Use Circular for compact spaces, dashboards, goal indicators
Select Appropriate State:
- Determinate when you know the completion percentage
- Indeterminate for unknown duration operations
- Buffer for streaming or multi-stage loading
- Active/Striped for visual emphasis on ongoing operations
Provide User Feedback:
- Show percentage labels for long operations
- Use annotations for contextual information
- Handle ProgressCompleted event to notify users
Accessibility:
- Ensure adequate color contrast
- Don't rely solely on color to convey information
- Test with screen readers
- Support keyboard navigation
Performance:
- Avoid excessive Value updates (throttle updates for smooth animation)
- Use appropriate animation durations (1000-2000ms typically)
- Consider disabling animation for very frequent updates
Styling:
- Match your application's design system
- Use range colors for meaningful thresholds
- Ensure progress bar is visible against background
- Use appropriate thickness for the context

选择合适的类型：
- 线性：适用于水平布局、文件操作、加载条
- 圆形：适用于紧凑空间、仪表盘、目标指示器
选择合适的状态：
- 确定状态：已知完成百分比时使用
- 不确定状态：适用于时长未知的操作
- 缓冲状态：适用于流媒体或多阶段加载
- 激活/条纹状态：用于强调正在进行的操作
提供用户反馈：
- 长操作显示百分比标签
- 使用注释提供上下文信息
- 处理ProgressCompleted事件通知用户
无障碍支持：
- 确保足够的颜色对比度
- 不要仅依赖颜色传达信息
- 使用屏幕阅读器测试
- 支持键盘导航
性能优化：
- 避免过于频繁更新Value值（节流更新以保证动画流畅）
- 使用合适的动画时长（通常1000-2000毫秒）
- 对于非常频繁的更新，考虑禁用动画
样式设计：
- 匹配应用的设计系统
- 使用范围颜色表示有意义的阈值
- 确保进度条在背景上清晰可见
- 根据上下文选择合适的厚度

Troubleshooting Quick Reference

故障排除快速参考

Progress bar not visible: Check Height, Width, and color contrast with background
Animation not working: Ensure
```
<ProgressBarAnimation Enable="true" />
```
Themes not applied: Verify stylesheet reference in index.html
Events not firing: Check ProgressBarEvents component and method signatures
Striped not showing: Striped only works with Linear type
Percentage not displaying: Set
```
ShowProgressValue="true"
```

For detailed setup, configuration, and advanced scenarios, navigate to the appropriate reference file above.

进度条不可见： 检查Height、Width及与背景的颜色对比度
动画不生效： 确保已添加
```
<ProgressBarAnimation Enable="true" />
```
主题未应用： 验证index.html中的样式表引用
事件未触发： 检查ProgressBarEvents组件和方法签名
条纹效果不显示： 条纹仅支持线性类型
百分比未显示： 设置
```
ShowProgressValue="true"
```

如需详细的设置、配置和高级场景说明，请参考上方对应的参考文档。