ProgressBar Display

ProgressBar は操作の進捗を視覚的に表示するコントロールです。進捗率が分かる確定モード（Determinate）と、進捗が不明な場合のアニメーション表示モード（Indeterminate）をサポートします。

概要

WPF の ProgressBar は RangeBase を継承したコントロールで、Minimum、Maximum、Value プロパティで進捗状況を管理します。Slider と同じ基底クラスを持ちますが、ProgressBar は読み取り専用の表示のみを目的としています。

確定モード（IsIndeterminate="False"）では、Value プロパティを Minimum〜Maximum の範囲でバインドすることで、実際の進捗をバーの幅で表現します。非同期処理のバックグラウンドワーカーからパーセンテージをレポートして ProgressBar の Value を更新するのが一般的なパターンです。

不確定モード（IsIndeterminate="True"）では、進捗量が不明な処理（ネットワーク待ち、初期化中など）でアニメーションするストライプまたはドットを表示します。ファイルサイズが不明なダウンロードや長時間かかる検索処理に使用します。

ProgressBar は水平（デフォルト）と垂直の両方向に配置できます。Orientation="Vertical" にすると縦方向に進捗が増加する棒グラフ風の表示になります。

画面キャプチャ

デモしているプロパティ

以下のプロパティが WPF 標準コントロールデモアプリでインタラクティブにデモされています。

プロパティ	設定値	説明
`IsIndeterminate`	`bool`	ネットワーク待ち・初期化処理・ファイルサイズが不明なダウンロードなど、処理の進捗率が事前に計算できない場合に使用します。True にするとバー全体がアニメーションするマーキー表示になり、False（デフォルト）のときは Value に基づいた確定進捗を表示します。IsIndeterminate=True のままコントロールが表示されている限りアニメーションによる CPU 負荷が継続するため、処理が完了したら必ず False に戻し、処理中でない場合は Visibility=Collapsed にしてリソースを解放してください。
`Orientation`	`Horizontal / Vertical`	バッテリー残量表示・縦型の充填インジケーターなど、縦方向の進捗表示が視覚的に適切なデザインで使用します。Horizontal（デフォルト）は左から右に進捗バーが伸び、Vertical は下から上に進捗バーが伸びます。Vertical モードでは値が下から上に増加するため、下端が Minimum・上端が Maximum に対応します。これが直感と逆に感じるデザインではカスタムテンプレートによる調整が必要になります。
`Minimum / Maximum (RangeBase)`	`double`	0〜100 のパーセンテージではなく処理件数や実際のデータ量を直接反映したい場合（例：Minimum=0、Maximum=処理対象ファイル数）に設定します。バーの進捗は (Value - Minimum) / (Maximum - Minimum) の割合で表示され、Minimum=0・Maximum=500 とすれば処理済み件数を Value に直接設定できます。Maximum が 0 または Maximum と Minimum が等しい場合はゼロ除算に相当するレイアウト計算が発生してバーが正しく表示されないため、常に Maximum > Minimum を保証し、空のコレクションをループする前に最大値を確認してください。
`Value (RangeBase)`	`double`	バックグラウンドで実行している非同期処理（ファイルコピー・データ処理・ダウンロード）の現在の進捗を反映する際に使用します。IProgress<T> パターンで定期的に報告するのが推奨であり、Minimum〜Maximum の範囲にクランプされた値を進捗バーの幅（または高さ）としてリアルタイムに表示します。バックグラウンドスレッド（Task や Thread）から直接 Value プロパティを設定すると InvalidOperationException（別スレッドからの UI 更新エラー）が発生するため、必ず IProgress<T> または Dispatcher.Invoke を使って UI スレッドで更新してください。

XAML 使用例

<!-- 確定モード -->
<ProgressBar Minimum="0" Maximum="100"
             Value="{Binding Progress}"
             Height="20" Width="300" />

<!-- 不確定モード（アニメーション） -->
<ProgressBar IsIndeterminate="True"
             Height="20" Width="300"
             Visibility="{Binding IsLoading,
               Converter={StaticResource BoolToVisibilityConverter}}" />

<!-- 縦向き -->
<ProgressBar Orientation="Vertical"
             Minimum="0" Maximum="100"
             Value="{Binding BatteryLevel}"
             Width="20" Height="100" />

主な使用例

ファイルダウンロード進捗 — ファイルサイズと受信バイト数から計算したパーセンテージを ProgressBar で表示します。
インポート処理の進捗 — CSV や Excel のインポート処理で、処理済みレコード数を ProgressBar で可視化します。
ローディングインジケーター — IsIndeterminate=True でネットワーク通信や初期化処理中のローディング状態を表示します。
バッテリー残量表示 — Vertical モードと組み合わせて電池残量や容量を視覚的に表示します。
ステップ進捗 — ウィザードの完了ステップ数を ProgressBar で表示し、どの程度完了したかを示します。

ヒントとベストプラクティス

IProgress<T> パターンを使う — async メソッドから進捗を報告するには IProgress<T> を使うのが推奨パターンです。new Progress<int>(v => ProgressValue = v) のようにコンストラクタにコールバックを渡すことで、スレッドセーフに UI スレッドで Value を更新できます。Dispatcher.Invoke より簡潔に記述できます。
キャンセル機能と組み合わせる — CancellationTokenSource と CancellationToken を使って、ユーザーが長時間処理をキャンセルできる UI を実装します。キャンセルボタンのクリックで CancellationTokenSource.Cancel() を呼び、非同期処理側でトークンを監視してキャンセル処理を行います。処理キャンセル後は IsIndeterminate=False に戻すのを忘れないようにしてください。
テキストオーバーレイで進捗率を表示する — Grid を使って ProgressBar の上に TextBlock を重ねることで「45%」のような進捗率テキストを表示できます。TextBlock の Text を "{Binding Progress, StringFormat={}{0:F0}%}" のようにバインドし、HorizontalAlignment=Center・VerticalAlignment=Center に設定するだけで実現できます。
処理件数を直接設定可能 — Minimum=0、Maximum=500（処理する総件数）のように設定すれば、パーセンテージ計算なしに処理済み件数を Value に設定できます。
IsIndeterminate の切り替え — 最初はファイルサイズ不明で Indeterminate、ダウンロード開始後にサイズが判明したら Value バインドの Determinate に切り替えます。処理完了後は Visibility=Collapsed にしてアニメーション負荷を解放してください。

ソースコード

このデモ画面のソースコードは GitHub で公開しています。

GitHub で ProgressBar のソースコードを見る →