syncfusion-angular-progress-bar

实现 Syncfusion Angular 进度条

Angular 进度条是一个轻量级组件，可直观呈现任务或流程的进度。它支持多种形状（线性、圆形、半圆形）、进度模式（确定、不确定、缓冲）、动画以及丰富的自定义选项。

何时使用此技能

在以下情况下使用此技能：

• 需要在 Angular 中显示任务进度
• 想要通过动画显示加载状态
• 需要不同形状的进度条（线性、圆形）
• 正在构建下载／上传进度界面
• 需要符合无障碍规范的进度指示器
• 想要显示多个进度状态（主要进度 + 次要进度）

在以下情况下不要使用此技能：

• 加载动画（加载状态请使用 Skeleton Loader）
• 步骤指示器（请使用 Stepper 组件）
• 时间线可视化（请使用 Timeline 组件）

组件概览

Syncfusion 进度条提供：

• 多种形状：线性、圆形、半圆形
• 进度模式：确定、不确定、缓冲
• 动画：平滑的进度过渡，可自定义持续时间和延迟
• 自定义：颜色（进度、轨道、次要进度）、粗细、分段、圆角、范围
• 分段支持：将进度划分为多个分段，并可调整间距
• 无障碍功能：完全符合 WCAG 标准，支持键盘导航和 ARIA 属性
• 事件：进度完成、值变化、文本呈现
• 响应式：与 Angular 的变更检测无缝协作

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和包配置
• Angular 依赖项和导入
• 基本进度条实现
• CSS 主题配置
• 最小可运行示例
• 常见配置模式

类型和形状

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

• 线性进度条
• 圆形进度条
• 半圆形进度条
• 特定形状的属性
• 各类型的适用场景
• 在不同类型之间切换

进度模式

📄 阅读： references/progress-modes.md

• 确定模式（进度已知）
• 不确定模式（进度未知）
• 缓冲模式（主要进度 + 次要进度）
• 模式选择指南
• 各模式的实际应用场景

自定义

📄 阅读： references/customization.md

• 尺寸和粗细
• 颜色配置（进度和轨道）
• Min、Max 和 Value 属性
• Radius 和 InnerRadius
• 分段和分段间距
• 高级样式模式

功能和交互

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

• 注释和标签
• 动画配置
• 工具提示支持
• 事件处理（valueChanged、progressComplete）
• 范围指示器
• 响应式数据绑定

无障碍功能

📄 阅读： references/accessibility.md

• 符合 WCAG 2.1 标准
• WAI-ARIA 属性
• 键盘导航支持
• 屏幕阅读器注意事项
• 无障碍测试
• 最佳实践

快速入门示例

import { Component } from '@angular/core';
import { ProgressBarModule } from '@syncfusion/ej2-angular-progressbar';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [ProgressBarModule],
  template: `
    <div style="margin: 20px;">
      
      <h4>File Download</h4>
      <ejs-progressbar
        [value]="65"
        height="20"
        type="Linear"
        style="width: 300px;">
      </ejs-progressbar>

      
      <h4 style="margin-top: 20px;">Task Completion</h4>
      <ejs-progressbar
        [value]="65"
        type="Circular"
        height="200"
        width="200">
      </ejs-progressbar>

      
      <h4 style="margin-top: 20px;">System Status</h4>
      <ejs-progressbar
        [value]="65"
        type="SemiCircular"
        height="200"
        width="200">
      </ejs-progressbar>
    </div>
  `
})
export class AppComponent {
}

常见模式

模式 1：文件上传进度

export class FileUploadComponent {
  uploadProgress = 0;

  onFileUpload(file: File) {
    // Simulate upload
    const interval = setInterval(() => {
      this.uploadProgress += Math.random() * 30;
      if (this.uploadProgress >= 100) {
        this.uploadProgress = 100;
        clearInterval(interval);
      }
    }, 500);
  }
}

模式 2：带动画的加载状态

export class LoadingComponent {
  @Input() isLoading = false;
}

模板：

<ejs-progressbar
  *ngIf="isLoading"
  [isIndeterminate]="true"
  [height]="4"
  [animation]="{ enable: true, duration: 2000, delay: 0 }">
</ejs-progressbar>

模式 3：多个进度状态

export class DownloadComponent {
  primaryProgress = 35;
  secondaryProgress = 65;
}

模板：

<ejs-progressbar
  [value]="primaryProgress"
  [secondaryProgress]="secondaryProgress"
  type="Linear">
</ejs-progressbar>

关键属性参考

属性	类型	用途
value	number	当前进度值（0-100 或自定义最小值/最大值）
type	string	形状：'Linear'、'Circular'、'SemiCircular'
isIndeterminate	boolean	为 true 时显示不确定状态
secondaryProgress	number	缓冲/次级进度值
minimum	number	进度范围的最小值（默认值：0）
maximum	number	进度范围的最大值（默认值：100）
height	number|string	进度条高度，单位为像素或百分比
width	number|string	进度条宽度，单位为像素或百分比
trackThickness	number	轨道线条粗细
progressThickness	number	进度条粗细
secondaryProgressThickness	number	次级进度粗细
progressColor	string	进度条颜色（hex、rgb 等）
secondaryProgressColor	string	次级进度颜色
trackColor	string	轨道背景颜色
cornerRadius	string	'Round' | 'Square' - 圆角样式
radius	number|string	圆形/半圆形进度条的外半径
innerRadius	number|string	环形外观的内半径
segmentCount	number	将进度划分为 N 个区段
segmentSpacing	number	区段间距，单位为像素
showProgressValue	boolean	显示进度百分比文本
animation	AnimationModel	动画配置：{enable, duration, delay}

事件参考

Progress Bar 组件会触发多个重要事件：

事件	说明	参数
valueChanged	进度值变化时触发	IProgressValueEventArgs
progressCompleted	进度达到 100% 时触发	IProgressValueEventArgs
textRender	渲染进度文本前触发	ITextRenderEventArgs

注意： 使用 (textRender) 事件可自定义进度标签的显示格式。

API 参考

完整的 Syncfusion Angular ProgressBar API 参考位于 references 文件夹中。其中包含属性类型、方法锚点和事件参数链接，可对应到官方文档。

阅读 API 参考：references/api-reference.md

相关组件

• 骨架加载器 - 用作通用加载指示器
• 微调器 - 用于不确定状态的加载
• 步骤条 - 用于逐步展示进度
• Toast - 用于进度通知