syncfusion-react-progress-bar

实现 React 进度条组件

一项全面的技能，用于实现 Syncfusion React Progress Bar 组件，以提供可视化进度反馈、加载状态和任务完成指示。

何时使用此技能

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

• 显示文件上传或下载进度
• 显示任务完成百分比
• 指示加载状态（确定或不确定）
• 可视化数据处理或长时间运行的操作
• 创建进度旋转器或圆形指示器
• 处理次级进度（缓冲场景）
• 自定义进度条的外观和颜色
• 实现动画和过渡效果
• 处理进度事件和回调
• 确保进度指示器符合无障碍要求

组件概述

Syncfusion React Progress Bar 是一款轻量级组件，可使用线性、圆形或半圆形形状来可视化任务进度。它支持多种状态（确定、不确定、缓冲），并具备动画、自定义和完整的无障碍支持。

主要功能：

• 多种类型： 线性、圆形、半圆形
• 状态： 确定（进度已知）、不确定（进度未知）、缓冲（次级进度）
• 动画： 平滑过渡，可配置时长和延迟
• 自定义： 颜色、高度、标签、主题
• 事件： 进度跟踪、开始/完成回调
• 无障碍： 符合 WCAG 2.1 标准并支持 ARIA
• RTL 支持： 支持从右向左书写的语言

文档指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置
• 基本进度条实现
• CSS 导入和主题
• 第一个组件示例
• TypeScript 与 JavaScript

类型和形状

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

• 线性进度条
• 圆形进度条
• 半圆形进度条
• 形状变体和代码示例
• 根据使用场景选择合适的类型

状态和模式

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

• 确定状态（进度已知，默认）
• 不确定状态（进度未知，旋转器）
• 缓冲/次级进度（双进度指示器）
• 组合多种状态
• 各种状态的真实场景

自定义和样式

📄 阅读： references/customization-and-styling.md

• 尺寸设置（高度、宽度配置）
• 颜色和填充自定义
• 标签和文本显示
• 应用主题
• CSS 自定义
• 响应式设计模式

动画、事件和无障碍

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

• 动画配置和控制
• 用于进度跟踪的事件处理程序
• 使用回调处理任务完成
• 符合 WCAG 标准
• ARIA 属性和标签
• 工具提示和注释支持
• 常见问题排查

API 参考

📄 阅读： references/api.md

• ProgressBarComponent 的所有公共属性、方法和事件（详见文件）。

快速入门示例

import { ProgressBarComponent } from '@syncfusion/ej2-react-progressbar';

function App() {
  return (
    <div>
      {/* Linear Determinate Progress Bar */}
      <ProgressBarComponent
        id="linear"
        type="Linear"
        height="60"
        value={75}
        animation={{
          enable: true,
          duration: 2000,
          delay: 0
        }}
      />

      {/* Circular Progress Bar */}
      <ProgressBarComponent
        id="circular"
        type="Circular"
        height="160px"
        value={60}
      />

      {/* Indeterminate Loading Spinner */}
      <ProgressBarComponent
        id="indeterminate"
        type="Linear"
        height="60"
        isIndeterminate={true}
        animation={{
          enable: true,
          duration: 2000,
          delay: 0
        }}
      />
    </div>
  );
}

export default App;

常见模式

1. 文件上传进度

<ProgressBarComponent
  id="upload"
  type="Linear"
  value={uploadPercentage}
  showProgressValue={true}
  progressValueFormat="N0 '%'"
/>

2. 加载旋转器

<ProgressBarComponent
  id="spinner"
  type="Circular"
  isIndeterminate={true}
  height="100px"
/>

3. 缓冲进度（缓冲加载）

<ProgressBarComponent
  id="buffer"
  type="Linear"
  value={40}
  secondaryProgress={80}
  height="60"
/>

4. 确定的任务进度

<ProgressBarComponent
  id="task"
  type="Linear"
  value={taskCompletionPercentage}
  showProgressValue={true}
  animation={{
    enable: true,
    duration: 1500
  }}
/>

关键属性参考

核心属性

Prop	Type	Default	Purpose
id	string	-	组件的唯一标识符
type	"Linear" | "Circular" | "Semicircle"	"Linear"	进度条形状
value	number	0	当前进度值（0-100）
secondaryProgress	number	0	次级／缓冲进度值
isIndeterminate	boolean	false	不确定进度／加载模式
height	string	"100%"	进度条高度（CSS 值）
width	string	"100%"	进度条宽度（CSS 值）
showProgressValue	boolean	false	显示百分比文本

动画与样式

Prop	Type	Default	Purpose
animation	AnimationModel	-	动画配置：{ enable, duration, delay }
progressColor	string	-	进度填充颜色（CSS 颜色）
trackColor	string	-	轨道背景颜色
progressThickness	number	4	进度条粗细（像素）
trackThickness	number	4	轨道粗细（像素）
isStriped	boolean	false	条纹图案外观
isGradient	boolean	false	渐变填充效果
cssClass	string	-	用于样式设置的自定义 CSS 类

高级功能

Prop	Type	Default	Purpose
cornerRadius	"Round" | "Auto"	"Auto"	端点的圆角样式
enableRtl	boolean	false	从右到左布局
enablePieProgress	boolean	false	圆形类型的饼图视图
enableProgressSegments	boolean	false	分段渲染进度
segmentCount	number	1	分段数量
rangeColors	RangeColorModel[]	-	不同范围的颜色
minimum	number	0	最小进度值
maximum	number	100	最大进度值

标签与格式

Prop	Type	Default	Purpose
progressValueFormat	string	"N0 '%'"	数值显示格式（例如："N2 '%'"）
labelOnTrack	boolean	true	在轨道上显示标签
labelStyle	FontModel	-	标签的字体样式

适用场景：

• type：根据可用空间选择：Linear（全宽）、Circular／Semicircle（紧凑）
• value：通过状态更新，以反映实际进度
• isIndeterminate：用于时长未知的任务（加载、处理）
• secondaryProgress：显示缓冲进度／预估进度与实际进度
• animation：通过平滑过渡改善用户体验（实时高频更新时禁用）
• cornerRadius：现代外观选择 "Round"，默认外观选择 "Auto"
• segmentCount：将进度拆分为可视分段（例如：10 段表示每段 10%）

常见使用场景与代码示例

使用场景 1：文件上传／下载

const [uploadProgress, setUploadProgress] = useState(0);

<ProgressBarComponent
  type="Linear"
  value={uploadProgress}
  showProgressValue={true}
  progressValueFormat="N0 '%'"
  height="30"
  animation={{ enable: true, duration: 500 }}
/>

最佳实践：

• 宽屏显示时使用 Linear 类型
• 根据上传进度事件更新 value
• 除百分比外，还显示预计耗时
• 可选使用 secondaryProgress 表示已预取的字节数

使用场景 2：加载状态（时长未知）

<ProgressBarComponent
  type="Circular"
  isIndeterminate={true}
  height="100px"
  animation={{ enable: true, duration: 2000 }}
/>

最佳实践：

• 使用 Circular 进行紧凑显示
• 操作完成前保持 isIndeterminate={true}
• 加载指示器会持续循环动画
• 能够跟踪进度后，改为确定进度模式

使用场景 3：数据处理

const [processProgress, setProcessProgress] = useState(0);
const totalItems = 100;

useEffect(() => {
  processItems().then(processed => {
    setProcessProgress((processed / totalItems) * 100);
  });
}, []);

<ProgressBarComponent
  type="Linear"
  value={processProgress}
  showProgressValue={true}
  height="30"
/>

最佳实践：

• 随项目处理进度更新 value
• 显示项目计数：“25 of 100 items”
• 显示已用时间和预计剩余时间
• 完成后显示成功／错误消息

使用场景 4：多项任务（缓冲／流式传输）

const [processedItems, setProcessedItems] = useState(30);
const [queuedItems, setQueuedItems] = useState(75);
const totalItems = 100;

<ProgressBarComponent
  type="Linear"
  value={(processedItems / totalItems) * 100}
  secondaryProgress={(queuedItems / totalItems) * 100}
  height="30"
/>

最佳实践：

• 主进度（value）＝实际已处理部分
• 次级进度＝已排队／已缓冲项目
• 适用于流式传输／视频缓冲场景
• 也适用于任务队列管理

用例 5：多步骤工作流

const steps = ['Validation', 'Processing', 'Upload', 'Confirmation'];
const [currentStep, setCurrentStep] = useState(0);
const progress = ((currentStep + 1) / steps.length) * 100;

<ProgressBarComponent
  type="Linear"
  value={progress}
  showProgressValue={true}
  height="30"
/>

<div>
  {steps.map((step, i) => (
    <div key={i}>
      {step} {i === currentStep ? '🔄' : i < currentStep ? '✓' : '⏳'}
    </div>
  ))}
</div>

最佳实践：

• 按照（当前步骤 / 总步骤数）* 100 计算进度
• 在进度条旁显示步骤指示器
• 突出显示当前步骤
• 处理期间禁用用户交互

高级用法模式

1. 使用状态管理进行值绑定

import { useState, useEffect } from 'react';
import { ProgressBarComponent } from '@syncfusion/ej2-react-progressbar';

function ProgressManager() {
  const [progress, setProgress] = useState(0);
  const [isProcessing, setIsProcessing] = useState(false);

  useEffect(() => {
    if (!isProcessing) return;

    const interval = setInterval(() => {
      setProgress(prev => {
        if (prev >= 100) {
          setIsProcessing(false);
          return 100;
        }
        return prev + Math.random() * 15;
      });
    }, 500);

    return () => clearInterval(interval);
  }, [isProcessing]);

  return (
    <div>
      <ProgressBarComponent 
        type="Linear"
        value={progress}
        showProgressValue={true}
      />
      <button 
        onClick={() => { setProgress(0); setIsProcessing(true); }}
        disabled={isProcessing}
      >
        {isProcessing ? 'Processing...' : 'Start'}
      </button>
    </div>
  );
}

export default ProgressManager;

2. 动画配置模式

// Real-time updates (no animation for smoothness)
animation={{ enable: false }}

// User interactions (quick feedback)
animation={{ enable: true, duration: 300, delay: 0 }}

// Page loads (smooth transition)
animation={{ enable: true, duration: 1500, delay: 0 }}

// Cascading effects (staggered)
animation={{ enable: true, duration: 1000, delay: 200 }}

// Loading spinners (continuous)
animation={{ enable: true, duration: 2000 }}

3. 基于状态的条件渲染

function ConditionalProgress() {
  const [state, setState] = useState('idle'); // idle | loading | success | error
  const [value, setValue] = useState(0);

  const getProgressType = () => {
    if (state === 'loading') return 'Circular';
    return 'Linear';
  };

  return (
    <>
      {state === 'loading' && (
        <ProgressBarComponent
          type={getProgressType()}
          isIndeterminate={state === 'loading'}
          height="100px"
        />
      )}

      {state === 'success' && (
        <div style={{ color: 'green' }}>✓ Complete</div>
      )}

      {state === 'error' && (
        <div style={{ color: 'red' }}>✗ Error occurred</div>
      )}
    </>
  );
}

export default ConditionalProgress;

4. 用于跟踪的事件处理

function ProgressWithEvents() {
  const handleStart = () => {
    console.log('Progress started');
    analytics.track('progress_started');
  };

  const handleComplete = () => {
    console.log('Progress completed');
    analytics.track('progress_completed');
    showNotification('Task completed!');
  };

  const handleValueChange = (args) => {
    console.log(`Progress: ${args.value}%`);
    // Milestone tracking
    if (args.value === 50) {
      analytics.track('progress_midpoint');
    }
  };

  return (
    <ProgressBarComponent
      type="Linear"
      value={75}
      progressStart={handleStart}
      progressComplete={handleComplete}
      valueChanged={handleValueChange}
    />
  );
}

export default ProgressWithEvents;

5. 响应式设计

function ResponsiveProgress() {
  const [isMobile, setIsMobile] = useState(window.innerWidth < 768);

  useEffect(() => {
    const handleResize = () => setIsMobile(window.innerWidth < 768);
    window.addEventListener('resize', handleResize);
    return () => window.removeEventListener('resize', handleResize);
  }, []);

  return (
    <ProgressBarComponent
      type={isMobile ? 'Semicircle' : 'Linear'}
      value={65}
      height={isMobile ? '100px' : '40'}
      showProgressValue={true}
    />
  );
}

export default ResponsiveProgress;

6. 错误处理与重试逻辑

async function uploadWithRetry(file, maxRetries = 3) {
  const [attempts, setAttempts] = useState(0);
  const [progress, setProgress] = useState(0);
  const [error, setError] = useState(null);

  for (let i = 0; i < maxRetries; i++) {
    try {
      setAttempts(i + 1);
      const result = await uploadFile(file, (p) => setProgress(p));
      return result;
    } catch (err) {
      if (i === maxRetries - 1) {
        setError(`Failed after ${maxRetries} attempts`);
        throw err;
      }
      // Retry with exponential backoff
      await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
    }
  }
}

与常见模式集成

与 React Query 集成

import { useQuery } from '@tanstack/react-query';

function DataProcessing() {
  const { data, isLoading, progress } = useQuery({
    queryKey: ['processData'],
    queryFn: async ({ signal }) => {
      // Process with progress tracking
    }
  });

  return (
    <ProgressBarComponent
      isIndeterminate={isLoading}
      value={progress || 0}
    />
  );
}

与 Redux 集成

import { useSelector, useDispatch } from 'react-redux';

function ReduxProgress() {
  const { progress, isLoading } = useSelector(state => state.upload);
  const dispatch = useDispatch();

  return (
    <ProgressBarComponent
      value={progress}
      isIndeterminate={isLoading}
      progressComplete={() => dispatch(resetProgress())}
    />
  );
}