syncfusion-maui-step-progressbar

.NET MAUI StepProgressBar の実装

Syncfusion® .NET MAUI StepProgressBar（SfStepProgressBar）コントロールの実装とカスタマイズに関する包括的なガイドです。このスキルでは、ステップの進捗状況の可視化、複数ステップのプロセスの追跡、順次進むステップによる進捗表示、ステップの外観とコンテンツのカスタマイズ、ステップの状態（完了／進行中／未開始）の処理、向きのオプション、ツールチップ、イベント、アクセシビリティ、RTL サポート、リキッドグラス効果について説明します。

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

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

• .NET MAUI アプリケーションにステップ形式の進捗インジケーターを実装する
• 複数ステップのプロセスを視覚化する（注文の追跡、ユーザー登録、チェックアウトフロー）
• 順次進む段階の進捗を視覚的なフィードバックとともに表示する
• ステップの外観（形状、色、コンテンツの種類、アニメーション）をカスタマイズする
• ステップの状態（完了、進行中、未開始）を処理する
• ステップ表示の水平または垂直の向きを設定する
• ステップにインタラクティブなツールチップを追加して、補足情報を提供する
• ステップのタップイベントと状態変更の処理を実装する
• 国際化に対応した右から左（RTL）のレイアウトをサポートする
• ステップ進捗バーに最新のリキッドグラス効果を適用する
• アクセシブルなステップ進捗表示を作成する

コンポーネントの概要

.NET MAUI StepProgressBar（SfStepProgressBar） は、順次進むプロセスの複数ステップにわたる進捗を表示する視覚的なコントロールです。次の機能を備えています。

• 複数ステップの可視化：進行状況が明確にわかるように、3～10 以上のステップを表示します
• 3 種類の進捗状態：完了、進行中、未開始
• 柔軟な向き：水平または垂直のレイアウト
• 豊富なカスタマイズ：形状（円／四角形）、コンテンツの種類（チェック／クロス／ドット／番号／画像）、色、サイズ
• テキストの説明：書式付きテキストに対応したメインテキストとサブテキスト
• インタラクティブな機能：ツールチップ、タップイベント、状態変更イベント
• アクセシビリティ：スクリーンリーダーのサポートとインクルーシブなデザイン
• 高度な効果：最新の UI デザインを実現するリキッドグラス効果
• RTL サポート：国際化に対応した右から左への描画

一般的な用途には、注文追跡システム、複数ページの登録フォーム、チェックアウトフロー、オンボーディングチュートリアル、アンケートの進捗表示、インストールウィザードなどがあります。

ドキュメントとナビゲーションガイド

はじめに

📄 参照先： references/getting-started.md

参照するタイミング：ユーザーが StepProgressBar を初めて設定する場合、インストール手順が必要な場合、または基本的な動作例を求めている場合。

説明するトピック：

• Syncfusion.Maui.ProgressBar NuGet パッケージのインストール
• ConfigureSyncfusionCore() によるハンドラーの登録
• XAML または C# への SfStepProgressBar の追加
• ItemsSource と ObservableCollection を使用した項目の設定
• ActiveStepIndex と ActiveStepProgressValue の設定
• StepProgressBarItem コレクションを含む ViewModel の作成
• 基本的な水平進捗バーの例

説明とラベル

📄 参照先： references/descriptions-and-labels.md

参照するタイミング：テキストラベルの追加、ラベル位置のカスタマイズ、ステップへの画像の追加、または書式付きテキストの使用が必要な場合。

説明するトピック：

• PrimaryText プロパティと SecondaryText プロパティ
• リッチテキストに使用する PrimaryFormattedText と SecondaryFormattedText
• ステップとテキストの間隔を調整する LabelSpacing
• LabelPosition のオプション（Start、End、Top、Bottom）
• ステップのコンテンツへの画像追加に使用する ImageSource
• FontImageSource を使用したフォントアイコン
• 水平／垂直モードでの、位置に応じたラベルの動作

向き

📄 参照先： references/orientation.md

参照するタイミング：レイアウトを水平から垂直に変更したい場合、または向きのオプションに関する説明が必要な場合。

説明するトピック：

• 水平向き（デフォルト）
• 垂直向き
• Orientation プロパティの設定
• 向きによる表示の違い
• 各向きを使用する場面

カスタマイズ

📄 参照: references/customization.md

参照するタイミング：ユーザーがステップの形状、色、コンテンツの種類、アニメーション、テンプレート、またはステップごとのスタイルをカスタマイズしたい場合。

対象トピック：

• ShapeTypeプロパティを使用したステップの形状タイプ（Circle、Square）
• ContentTypeプロパティを使用したコンテンツの種類（Numbering、Tick、Cross、Dot）
• ProgressAnimationDurationを使用したアニメーションの時間
• プログレスバーの背景色のカスタマイズ
• ProgressTrackSizeを使用したステップごとのカスタムプログレストラックサイズ
• 完了、進行中、未開始の各状態に対応するStepSettings
• Background、ContentFillColor、ProgressColor、Strokeプロパティ
• TextStyleのカスタマイズ（色、フォント、属性）
• カスタムステップ表示に使用するDataTemplateを指定するStepTemplate
• 条件に応じたステップテンプレートに使用するDataTemplateSelector
• カスタムラベルに使用するPrimaryTextTemplateとSecondaryTextTemplate
• カスタマイズの完全な例

イベント

📄 参照: references/events.md

参照するタイミング：ユーザーがステップのタップ操作を処理したい場合や、ステップのステータス変更に応答したい場合。

対象トピック：

• ステップのタップ操作を処理するStepTappedイベント
• StepTappedEventArgsのプロパティ
• ステータスの変更を追跡するStepStatusChangedイベント
• StepStatusChangedEventArgsのプロパティ
• イベントハンドラーの実装例

ツールチップ

📄 参照: references/tooltips.md

参照するタイミング：ユーザーがステップにツールチップを追加したい場合、ツールチップの外観をカスタマイズしたい場合、またはカスタムツールチップテンプレートを使用したい場合。

対象トピック：

• ShowToolTipプロパティを使用したツールチップの有効化
• StepProgressBarItemでのToolTipTextの設定
• 外観のカスタマイズに使用するToolTipSettings
• Background、Stroke、Duration、TextStyleプロパティ
• カスタムツールチップデザインに使用するDataTemplateを指定するToolTipTemplate
• ツールチップの表示時間の制御
• カスタムツールチップのレイアウトとコンテンツ

アクセシビリティ

📄 参照: references/accessibility.md

参照するタイミング：ユーザーがアクセシビリティへの準拠を確保したい場合、またはスクリーンリーダーのサポートについて知りたい場合。

対象トピック：

• アクセシビリティ機能の概要
• スクリーンリーダーによる読み上げ形式
• ステップ番号、テキスト、ステータスの読み上げ
• インクルーシブデザインに関する考慮事項

右から左への表示のサポート

📄 参照: references/right-to-left.md

参照するタイミング：ユーザーがRTL言語（アラビア語、ヘブライ語など）をサポートしたい場合、またはレイアウトを反転したい場合。

対象トピック：

• RightToLeftに設定するFlowDirectionプロパティ
• RTLのレンダリング動作
• 国際化に対応したレイアウトの反転

リキッドグラスエフェクト

📄 参照: references/liquid-glass-effect.md

参照するタイミング：ユーザーが最新のリキッドグラス視覚効果を適用したい場合（.NET 10+、macOS 26+、iOS 26+）。

対象トピック：

• SfGlassEffectViewとの統合
• グラスエフェクトビュー内でのStepProgressBarのラップ
• グラスエフェクト用の透明な背景の設定
• プラットフォームとバージョンの要件
• グラデーション背景を使用した完全な実装