syncfusion-maui-toolkit-time-picker

Syncfusion .NET MAUI TimePicker の実装

Syncfusion .NET MAUI TimePicker（SfTimePicker）は、直感的に操作できるスクロール式のインターフェイスで時刻を選択できる強力なコントロールです。複数の時刻形式、カスタマイズ可能な間隔、ダイアログモード、時刻の制限、幅広いスタイル設定に対応しています。

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

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

• .NET MAUI アプリケーションに時刻選択機能を実装する
• XAML または C# コードに SfTimePicker コントロールを追加する
• 時刻形式（12 時間／24 時間、秒あり／なし、ミリ秒）を設定する
• ダイアログモードまたは位置指定ピッカーモードを設定する
• 時刻選択の時、分、秒の間隔を定義する
• 選択可能な時刻を制限する（営業時間、予約枠、選択不可の時刻）
• 時刻選択イベントを処理する、または MVVM コマンドを使用する
• ピッカーの外観（ヘッダー、フッター、選択ビュー、テキスト表示）をカスタマイズする
• アクセシビリティに配慮した、またはローカライズされた時刻ピッカーを実装する
• TimePicker の設定や動作に関する問題をトラブルシューティングする

コンポーネントの概要

SfTimePicker には次の機能があります。

• 14 種類の定義済み時刻形式があり、時、分、秒、ミリ秒を含む 12 時間形式と 24 時間形式に対応しています
• 3 つのピッカーモード：Default（インライン）、Dialog（ポップアップ）、RelativeDialog（位置指定ポップアップ）
• 時、分、秒、ミリ秒の時間間隔
• 最小時刻／最大時刻や選択不可の時刻などの時刻制限
• 最初と最後の項目間をシームレスに移動できるループ機能
• 選択変更、ダイアログのライフサイクル、フッターボタンのイベントを備えた豊富なイベントシステム
• コマンド（SelectionChangedCommand、AcceptCommand、DeclineCommand）によるMVVM 対応
• ヘッダー、フッター、列ヘッダー、選択ビュー、テキスト表示モードの幅広いカスタマイズ
• グローバルなアプリケーション向けのアクセシビリティとローカライズへの対応

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

はじめに

📄 参照： references/getting-started.md

参照するタイミング： TimePicker を初めて設定するとき、インストールするとき、基本的な実装を行うとき。

内容：

• NuGet パッケージのインストール（Syncfusion.Maui.Toolkit）
• ハンドラーの登録（MauiProgram.cs の ConfigureSyncfusionToolkit）
• SfTimePicker の基本的な初期化（XAML と C#）
• ヘッダーとフッタービューの設定
• 高さと幅の設定
• SelectedTime プロパティの使用
• 選択のクリアへの対応

時刻の書式設定

📄 参照： references/formatting.md

参照するタイミング： 時刻の表示方法（12 時間／24 時間、秒やミリ秒の表示／非表示）を設定するとき。

内容：

• Format プロパティの概要
• 14 種類の定義済み時刻形式：
  • H_mm、H_mm_ss（先頭にゼロを付けない 24 時間形式）
  • HH_mm、HH_mm_ss、HH_mm_ss_fff（先頭にゼロを付ける 24 時間形式）
  • h_mm_tt、h_mm_ss_tt（先頭にゼロを付けない 12 時間形式＋AM/PM）
  • hh_mm_tt、hh_mm_ss_tt、hh_mm_ss_fff_tt、hh_tt（先頭にゼロを付ける 12 時間形式＋AM/PM）
  • mm_ss、mm_ss_fff、ss_fff（分／秒の組み合わせ）
  • Default（カルチャに基づく形式）
• 形式の使用例と形式の切り替え

ピッカーモードと表示

📄 参照： references/picker-modes.md

参照するタイミング： ピッカーの表示方法（インライン、ポップアップダイアログ、位置指定ダイアログ）を設定するとき。

内容：

• Mode プロパティ（Default、Dialog、RelativeDialog）
• ダイアログモードの設定
• IsOpen プロパティによるピッカーのプログラム制御
• 位置指定ポップアップの RelativeDialog モード
• RelativePosition のオプション（8 種類の配置位置）：
  • AlignTop、AlignBottom、AlignToLeftOf、AlignToRightOf
  • AlignTopLeft、AlignTopRight、AlignBottomLeft、AlignBottomRight
• 特定のコントロールを基準に配置する RelativeView プロパティ
• ポップアップサイズのカスタマイズ（PopupWidth、PopupHeight プロパティ）
• 各モードのコード例

時間間隔とループ

📄 参照： references/time-intervals-looping.md

参照するタイミング： 時刻の値の間隔を設定したり、連続ループを有効にしたりする場合です。

対象範囲：

• HourInterval プロパティ（例：2 時間ごとに表示）
• MinuteInterval プロパティ（例：5 分、10 分、15 分ごとに表示）
• SecondInterval プロパティ（例：10 秒ごとに表示）
• 正確な時刻選択のための MilliSecondInterval プロパティ
• 最初の項目と最後の項目の間をシームレスに移動する EnableLooping プロパティ
• 異なる時刻形式と間隔の組み合わせ
• 実践的なシナリオ（予約、時間記録）

時刻の制限

📄 参照： references/time-restrictions.md

参照するタイミング： 選択可能な時刻を制限する場合（営業時間、最小／最大範囲、ブロックする時刻）。

対象範囲：

• 選択可能な最も早い時刻を設定する MinimumTime プロパティ
• 選択可能な最も遅い時刻を設定する MaximumTime プロパティ
• 特定の時刻を無効にする BlackoutTimes コレクション
• 時刻範囲の検証ルール
• ユースケース（営業時間：午前 9 時〜午後 5 時、予約枠、昼休み時間のブロック）
• 形式や間隔と制限の組み合わせ

イベントとコマンド

📄 参照： references/events-commands.md

参照するタイミング： 時刻選択の変更やダイアログのライフサイクルを処理する場合、または MVVM コマンドを使用する場合です。

対象範囲：

• SelectionChanged イベント
  • NewValue と OldValue を持つ TimePickerSelectionChangedEventArgs
  • IsSelectionImmediate の動作（即時選択と遅延選択）
• ダイアログモードのイベント：
  • Opened イベント（ピッカーを開いたとき）
  • CancelEventArgs を伴う Closing イベント（閉じる操作をキャンセル可能）
  • Closed イベント（ピッカーを閉じた後）
• フッタービューのイベント：
  • OkButtonClicked イベント
  • CancelButtonClicked イベント
• MVVM コマンド：
  • SelectionChangedCommand
  • AcceptCommand（OK ボタン）
  • DeclineCommand（キャンセルボタン）
• イベントの使用パターンとベストプラクティス

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

📄 参照： references/customization.md

参照するタイミング： ピッカーの外観（色、フォント、ヘッダー／フッター、視覚効果）をカスタマイズする場合です。

対象範囲：

• ヘッダービューのカスタマイズ
  • Text、Height、Background、TextStyle プロパティ
• フッタービューのカスタマイズ
  • OkButtonText、CancelButtonText
  • ShowOkButton、Height、Background、TextStyle
• 列ヘッダービューのカスタマイズ
  • 列ごとの Text、Height、TextStyle
• 選択ビューのカスタマイズ
  • Background、Stroke、StrokeThickness、CornerRadius、TextStyle
• TextDisplayMode のオプション：
  • Default、Fade、Shrink、FadeAndShrink
• 項目テキストのスタイル設定
• カスタマイズの完全な例

アクセシビリティとローカライズ

📄 参照： references/accessibility-localization.md

参照するタイミング： アクセシブルなコントロールを実装する場合や、複数の言語／カルチャをサポートする場合です。

対象範囲：

• WCAG 準拠機能
• スクリーンリーダーのサポート
• キーボードナビゲーション
• アクセシビリティのためのセマンティックプロパティ
• ローカライズの設定
• カルチャ固有の時刻形式
• RTL（右から左）言語のサポート
• 多言語実装の例