syncfusion-blazor-progress-bar

实现 Syncfusion Blazor ProgressBar

何时使用此技能

当用户需要执行以下操作时，使用此技能：

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

组件概览

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

API 参考

📄 阅读： 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 标准，支持键盘导航

文档与导航指南

入门

📄 阅读： references/getting-started.md

用户首次需要设置 ProgressBar 时，请引导他们参考此文档，了解：

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

类型和模式

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

用户询问或需要了解以下内容时，请参考此文档：

• 线性与圆形 ProgressBar 类型
• 根据使用场景选择合适的类型
• 实现基本的线性进度条
• 实现圆形／圆环进度条
• 圆形进度条的饼图进度模式
• 在线性或圆形类型中使用分段
• 次级进度指示器
• 按类型划分的完整示例

状态和行为

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

用户询问或需要了解以下内容时，请参考此文档：

• 确定进度（完成百分比已知）
• 不确定进度（时长未知的加载过程）
• 缓冲状态（媒体／流式内容的双进度）
• 活动状态（带动画效果的进度指示器）
• 条纹视觉图案（仅适用于线性类型）
• 范围配置（Minimum／Maximum 值）
• 组合多种状态
• 根据使用场景选择合适的状态

自定义

📄 阅读： references/customization.md

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

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

注释和标签

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

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

• 在进度条上添加文本注释
• 自定义 HTML 或组件叠加层
• 显示进度百分比标签
• 自定义标签格式（TextRender 事件）
• 设置注释位置
• 添加多个注释
• 设置注释和标签的样式
• 将注释与标签结合使用

动画

📄 阅读： references/animation.md

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

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

事件和无障碍

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

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

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

快速入门示例

线性 ProgressBar（基本）

@using Syncfusion.Blazor.ProgressBar

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

圆形 ProgressBar（基本）

@using Syncfusion.Blazor.ProgressBar

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

不确定加载状态

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

常见模式

模式 1：文件上传进度

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

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

@using Syncfusion.Blazor.ProgressBar

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

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

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

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

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

关键属性参考

核心属性

• Type：ProgressType.Linear 或 ProgressType.Circular - 进度条类型
• Value：配置范围内的当前进度值
• Minimum：范围最小值
• Maximum：范围最大值
• Height：组件高度
• Width：组件宽度
• ID：用于以编程方式定位组件的标识符
• ChildContent：组件内部的自定义子内容

状态属性

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

自定义属性

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

显示属性

• ShowProgressValue：显示百分比标签
• EnablePieProgress：将圆形进度填充为饼图

动画属性

使用 <ProgressBarAnimation> 子组件：

• Enable：启用动画
• Duration：动画时长（毫秒）
• Delay：动画开始延迟（毫秒）

方法

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

常见用例

用例 1：简单的加载指示器

场景： 获取数据时显示加载栏 实现： 使用带动画的非确定性线性进度条

用例 2：显示百分比的文件上传

场景： 显示文件上传进度及百分比 实现： 使用确定性进度，并设置 ShowProgressValue="true"

用例 3：多步骤向导

场景： 显示多步骤表单的进度 实现： 使用分段进度条，并将步骤数作为分段数

用例 4：视频缓冲状态

场景： 显示播放位置和已缓冲内容 实现： 使用缓冲状态，以主要进度表示播放进度，以次级进度表示缓冲进度

用例 5：仪表板 KPI 指示器

场景： 使用圆形进度显示目标完成情况 实现： 使用圆形进度，并通过注释显示百分比和目标值

用例 6：显示剩余时间估算的下载进度

场景： 显示下载进度，并自定义剩余时间标签 实现： 使用线性进度，并通过 TextRender 事件进行自定义格式化

用例 7：确定性任务进度

场景： 显示已知步骤的批处理操作进度 实现： 使用确定性进度条，并在每个步骤完成时更新 Value

最佳实践

1. 选择合适的类型：

   • 水平布局、文件操作和加载栏使用 Linear
   • 空间紧凑的区域、仪表板和目标指示器使用 Circular

2. 选择合适的状态：

   • 知道完成百分比时使用 Determinate
   • 操作时长未知时使用 Indeterminate
   • 流式处理或多阶段加载时使用 Buffer
   • 需要突出显示正在进行的操作时使用 Active/Striped

3. 提供用户反馈：

   • 耗时较长的操作应显示百分比标签
   • 使用注释提供上下文信息
   • 处理 ProgressCompleted 事件以通知用户

4. 无障碍访问：

   • 确保颜色对比度充足
   • 不要仅依靠颜色传达信息
   • 使用屏幕阅读器进行测试
   • 支持键盘导航

5. 性能：

   • 避免过于频繁地更新 Value（可对更新进行节流，以实现流畅动画）
   • 使用合适的动画时长（通常为 1000-2000ms）
   • 更新非常频繁时，可考虑禁用动画

6. 样式：

   • 与应用程序的设计系统保持一致
   • 使用范围颜色表示有意义的阈值
   • 确保进度条在背景上清晰可见
   • 根据具体场景选择合适的粗细

故障排查速查

• 看不到进度条： 检查高度、宽度以及与背景的颜色对比度
• 动画无法运行： 确保设置了 <ProgressBarAnimation Enable="true" />
• 主题未应用： 检查 index.html 中的样式表引用
• 事件未触发： 检查 ProgressBarEvents 组件和方法签名
• 未显示条纹： 条纹仅适用于 Linear 类型
• 未显示百分比： 设置 ShowProgressValue="true"

如需详细了解设置、配置和高级场景，请参阅上方相应的参考文件。