syncfusion-blazor-progress-bar

Syncfusion Blazor ProgressBar の実装

このスキルを使用するタイミング

ユーザーが以下を必要としている場合に、このスキルを使用します。

• ファイルのアップロード、ダウンロード、またはデータ処理の進行状況を表示する
• 確定または不確定の進行状況を示す読み込み状態を表示する
• タスクの完了率を視覚化する
• メディアプレーヤーやストリーミングコンテンツのバッファー状態を実装する
• 円形または線形の進行状況インジケーターを作成する
• カスタムスタイルやアニメーションを使った進行状況の追跡を追加する
• セグメントを使って複数段階の進行状況を表示する
• WCAG に準拠したアクセシブルな進行状況インジケーターを実装する
• 注釈、ラベル、またはカスタム書式を使って進行状況を表示する

コンポーネントの概要

Syncfusion Blazor ProgressBar コンポーネントは、操作の進行状況を表示する視覚的なインジケーターです。線形と円形の両方の種類に対応し、複数の状態（確定、不確定、バッファー、アクティブ、ストライプ）、幅広いカスタマイズオプション、アニメーション、完全なアクセシビリティサポートを備えています。

API リファレンス

📄 参照： references/api-reference.md

以下を含む ProgressBar API の正確な仕様を確認する必要がある場合は、このリファレンスを使用してください。

• Value、Type、Role、Theme、Visible、ID、StartAngle、EndAngle、RefreshAsync() などの SfProgressBar プロパティ
• ProgressBarAnimation、ProgressBarEvents、ProgressBarAnnotations、ProgressBarAnnotation、ProgressBarLabelStyle、ProgressBarMargin、ProgressBarRangeColor、ProgressBarRangeColors などの子コンポーネント
• ValueChanged、ProgressCompleted、AnimationComplete、AnnotationRender、TextRender、Loaded などのイベントコールバック
• ProgressType、CornerType、ModeType、TextAlignmentType などの列挙型

主な機能：

• 種類： 線形（横棒）と円形（ドーナツ／円グラフ形式）
• 状態： 確定（進行状況が既知）、不確定（進行状況が不明）、バッファー（2 つの進行状況）、アクティブ（アニメーション）、ストライプ（視覚的なパターン）
• カスタマイズ： 色、太さ、セグメント、半径、角、余白、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

ユーザーが以下について質問した場合、または以下を必要としている場合に使用します。

• 確定進行状況（完了率が既知）
• 不確定進行状況（所要時間が不明な読み込み）
• バッファー状態（メディア／ストリーミング用の 2 つの進行状況）
• アクティブ状態（アニメーションする進行状況インジケーター）
• ストライプの視覚パターン（線形のみ）
• 範囲の設定（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 への準拠
• キーボードナビゲーションのサポート
• スクリーンリーダーとの互換性
• 色のコントラストとアクセシビリティ基準
• モバイルデバイスのサポート

クイックスタートの例

線形プログレスバー（基本）

@using Syncfusion.Blazor.ProgressBar

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

円形プログレスバー（基本）

@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：プログレスバーのビジュアルテーマ
• 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" を設定してください

セットアップ、設定、高度なシナリオの詳細については、上記の該当するリファレンスファイルを参照してください。