syncfusion-aspnetcore-progress-bar

实现 Syncfusion 进度条

Syncfusion 进度条组件是一种可自定义的控件，可通过多种形状选项、动画支持和交互功能直观展示任务进度。它非常适合显示文件上传、下载、数据处理进度，以及任何需要向用户清晰反馈任务完成状态的场景。

何时使用此技能

在需要以下功能时使用此技能：

• 显示线性或圆形进度指示器
• 通过可视化反馈显示任务完成百分比
• 实现文件上传／下载进度跟踪
• 创建确定或不确定模式的加载状态
• 为缓冲操作添加次级进度指示器
• 平滑地为进度变化添加动画
• 显示进度注释和标签
• 使进度条符合 WCAG 无障碍标准
• 添加显示进度信息的工具提示
• 使用颜色、粗细和样式自定义外观

文档和导航指南

API 参考

📄 阅读： references/api-reference.md

• 完整的 ProgressBar 类 API 文档
• 属性定义及其类型和默认值
• 所有可用事件和回调
• 配置选项和使用模式
• 相关设置类和枚举
• Syncfusion 官方 API 参考链接

入门

📄 阅读： references/getting-started.md

• 通过 NuGet 包安装
• ASP.NET Core 项目设置
• Tag Helper 配置
• 添加样式表和脚本
• 基本进度条初始化
• 渲染第一个进度条

类型和形状

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

• 用于标准水平进度显示的线性进度条
• 用于紧凑显示的圆形进度条
• 用于类似仪表盘显示的半圆形进度条
• 根据使用场景选择合适的形状

模式和状态

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

• 用于已知进度估算的确定模式
• 用于进度时长未知情况的不确定模式
• 用于次级进度可视化的缓冲模式
• 在不同状态之间切换

自定义

📄 阅读： references/customization.md

• 自定义颜色和主题
• 调整粗细和尺寸
• 半径和圆角样式
• 用于里程碑跟踪的分段
• 基于 CSS 的自定义选项
• 高级样式示例

动画和效果

📄 阅读： references/animation-and-effects.md

• 启用和配置动画
• 时长和时间控制
• 缓动函数和性能
• 平滑的状态转换

标签和注释

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

• 为进度条添加文本标签
• 显示进度百分比
• 圆形进度的注释内容
• 动态更新标签
• 定位和设置标签样式

事件和交互

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

• 处理 ValueChanged 事件
• 触发 ProgressCompleted 事件
• 事件绑定和回调
• 与应用程序工作流集成

工具提示支持

📄 阅读： references/tooltip-support.md

• 启用工具提示显示
• 工具提示格式设置和自定义
• 悬停时显示工具提示
• 自定义工具提示内容

无障碍

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 规范和标准
• ARIA 属性和角色
• 键盘导航支持
• 屏幕阅读器兼容性
• 测试和验证

快速入门示例

以下是在 ASP.NET Core 中创建基本线性进度条的最简示例：

<ejs-progressbar id="linearProgress" 
                  type="Linear" 
                  value="50" 
                  minimum="0" 
                  maximum="100">
</ejs-progressbar>

此示例会创建一个显示 50％ 完成度的进度条。默认类型为 Linear，范围从 0（最小值）到 100（最大值）。

常见模式

模式 1：跟踪文件上传进度

<ejs-progressbar id="uploadProgress" 
                  type="Linear" 
                  value="0" 
                  minimum="0" 
                  maximum="100">
    <e-progressbar-animation enable="true" 
                              duration="1000" 
                              delay="0">
    </e-progressbar-animation>
</ejs-progressbar>

<button id="uploadBtn" type="button">Start Upload</button>
<script>
document.getElementById('uploadBtn').addEventListener('click', function() {
    var progressBar = document.getElementById('uploadProgress').ej2_instances[0];
    var interval = setInterval(function() {
        var currentValue = progressBar.value;
        if (currentValue < 100) {
            progressBar.value += 10;
        } else {
            clearInterval(interval);
        }
    }, 500);
});
</script>

模式 2：使用圆形进度条显示任务完成情况

<ejs-progressbar id="taskProgress" 
                  type="Circular" 
                  value="75" 
                  minimum="0" 
                  maximum="100"
                  showProgressValue="true">
</ejs-progressbar>

模式 3：不确定的加载状态

<ejs-progressbar id="loadingProgress" 
                  type="Linear" 
                  value="30"
                  isIndeterminate="true">
</ejs-progressbar>

当任务持续时间未知，但应用程序正在积极处理数据时，可使用此模式。

模式 4：多个步骤的分段进度

<ejs-progressbar id="stepsProgress" 
                  type="Linear" 
                  value="60" 
                  segmentCount="5"
                  minimum="0" 
                  maximum="100">
</ejs-progressbar>

将进度条划分为 5 个区段，适用于多步骤流程。

关键属性

属性	类型	默认值	用途
type	string	"Linear"	进度条形状：Linear、Circular、SemiCircular
value	number	0	当前进度值
minimum	number	0	范围最小值
maximum	number	100	范围最大值
isIndeterminate	boolean	false	显示不确定的加载状态
segmentCount	number	1	将进度条划分为多个区段
showProgressValue	boolean	false	显示百分比标签
trackThickness	number	0	轨道条的粗细，单位为像素
progressThickness	number	0	进度条的粗细，单位为像素
cornerRadius	string	"Auto"	圆角样式
secondaryProgress	number	NaN	缓冲模式下的次要进度值
trackColor	string	null	轨道（背景）颜色
progressColor	string	null	主要进度填充颜色
secondaryProgressColor	string	""	次要／缓冲进度颜色

关键事件

事件	触发条件	使用场景
ValueChanged	进度值变化时	更新 UI、跟踪进度里程碑
ProgressCompleted	数值达到最大值时	触发下一步操作、显示完成消息

---

有关详细的实现指南，请参阅上方的参考文件。每个文件都针对相应主题提供具体说明、代码示例和最佳实践。