syncfusion-react-progress-bar

React プログレスバーコンポーネントの実装

視覚的な進捗フィードバック、読み込み状態、タスク完了インジケーターを実現する Syncfusion React プログレスバーコンポーネントの実装に関する包括的なスキルです。

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

• ファイルのアップロードやダウンロードの進捗を表示する
• タスクの完了率を表示する
• 読み込み状態を示す（確定または不確定）
• データ処理や長時間実行される操作を可視化する
• プログレススピナーや円形インジケーターを作成する
• 2次進捗（バッファーのシナリオ）を処理する
• プログレスバーの外観や色をカスタマイズする
• アニメーションやトランジションを実装する
• 進捗イベントやコールバックを処理する
• 進捗インジケーターのアクセシビリティ準拠を確保する

コンポーネントの概要

Syncfusion React プログレスバーは、タスクの進捗を直線、円形、または半円形で可視化する軽量なコンポーネントです。複数の状態（確定、不確定、バッファー）に対応し、アニメーション、カスタマイズ、完全なアクセシビリティサポートを備えています。

主な機能：

• 複数の種類： 直線、円形、半円形
• 状態： 確定（進捗が既知）、不確定（進捗が不明）、バッファー（2次進捗）
• アニメーション： 設定可能な時間と遅延による滑らかなトランジション
• カスタマイズ： 色、高さ、ラベル、テーマ
• イベント： 進捗の追跡、開始時／完了時のコールバック
• アクセシビリティ： ARIA をサポートし、WCAG 2.1 に準拠
• RTL サポート： 右から左に記述する言語への対応

ドキュメントガイド

はじめに

📄 参照： references/getting-started.md

• インストールとパッケージのセットアップ
• 基本的なプログレスバーの実装
• CSS のインポートとテーマ
• 最初のコンポーネントの例
• TypeScript と JavaScript の比較

種類と形状

📄 参照： references/types-and-shapes.md

• 直線プログレスバー
• 円形プログレスバー
• 半円形プログレスバー
• 形状のバリエーションとコード例
• ユースケースに適した種類の選び方

状態とモード

📄 参照： references/states-and-modes.md

• 確定状態（進捗が既知、デフォルト）
• 不確定状態（進捗が不明、スピナー）
• バッファー／2次進捗（2つの進捗インジケーター）
• 複数の状態の組み合わせ
• 各状態の実際のシナリオ

カスタマイズとスタイル設定

📄 参照： 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
  }}
/>

主な Props のリファレンス

主なプロパティ

プロパティ	型	デフォルト	用途
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	パーセンテージのテキストを表示

アニメーションとスタイル設定

プロパティ	型	デフォルト	用途
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 クラス

高度な機能

プロパティ	型	デフォルト	用途
cornerRadius	"Round" | "Auto"	"Auto"	端の角のスタイル
enableRtl	boolean	false	右から左へのレイアウト
enablePieProgress	boolean	false	円形タイプで円グラフ表示を有効化
enableProgressSegments	boolean	false	セグメント分割した進捗表示を有効化
segmentCount	number	1	セグメント数
rangeColors	RangeColorModel[]	-	範囲ごとの色
minimum	number	0	進捗値の最小値
maximum	number	100	進捗値の最大値

ラベルと書式

プロパティ	型	デフォルト	用途
progressValueFormat	string	"N0 '%'"	値の表示形式（例："N2 '%'"）
labelOnTrack	boolean	true	トラック上にラベルを表示
labelStyle	FontModel	-	ラベルのフォントスタイル

各プロパティの使用方法：

• type：スペースに応じて選択します。Linear は横幅いっぱいに表示する場合、Circular／Semicircle はコンパクトに表示する場合に適しています
• value：実際の進捗を反映するため、状態を通じて更新します
• isIndeterminate：所要時間が不明なタスク（読み込み、処理）に使用します
• secondaryProgress：バッファーの進捗や推定進捗と実際の進捗を表示します
• animation：滑らかな遷移で UX を向上させます（リアルタイムで更新頻度が高い場合は無効にします）
• cornerRadius：「Round」はモダンな見た目に、「Auto」はデフォルトの見た目に使用します
• segmentCount：進捗を視覚的なセグメントに分割します（例：10 セグメントなら、1 セグメントあたり 10％）

コード例で見る一般的なユースケース

ユースケース 1：ファイルのアップロード／ダウンロード

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

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

ベストプラクティス：

• 横幅の広い表示には Linear タイプを使用します
• アップロードの進捗イベントから値を更新します
• パーセンテージに加えて推定時間を表示します
• 必要に応じて、事前取得したバイト数を 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"
/>

ベストプラクティス：

• 項目の処理に応じて値を更新します
• 項目数を表示します：「100 項目中 25 項目」
• 経過時間と残り時間の推定値を表示します
• 完了時に成功／エラーメッセージを表示します

ユースケース 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())}
    />
  );
}