syncfusion-winui-time-picker

WinUI TimePicker（SfTimePicker）実装ガイド

Windows デスクトップアプリケーションに Syncfusion WinUI TimePicker コントロールを実装するための包括的なガイドです。SfTimePicker は、時刻の制限、書式設定、ローカライズ、幅広いカスタマイズに対応した、ドロップダウンスピナーから時刻を選択できる直感的でタッチ操作に適したインターフェイスを提供します。

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

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

• WinUI 3 デスクトップアプリケーションに時刻選択機能を実装する
• ドロップダウンスピナー付きの時刻入力コントロールを追加する
• 予約のスケジュール設定や時刻入力フォームを作成する
• 時刻の選択範囲や間隔を制限する
• 12 時間制または 24 時間制の時刻形式を実装する
• ドロップダウンの時刻スピナーの外観をカスタマイズする
• RTL レイアウトに対応したローカライズ済みの時刻入力をサポートする
• Windows アプリで時刻入力を検証して書式設定する
• 特定の時刻を選択肢から非表示にする、または選択できないようにする

コンポーネントの概要

SfTimePicker コントロールは、次の機能を備え、WinUI アプリケーションで最新の時刻選択エクスペリエンスを提供します。

主な機能：

• ドロップダウン時刻スピナー - 時、分、午前／午後の列から時刻を選択
• 時刻の制限 - 最小／最大時刻を設定し、特定の時刻を選択不可にする
• 複数の形式 - 12 時間制と 24 時間制に対応
• ローカライズ - RTL レイアウトを含む多言語サポート
• 編集モード - 自動修正機能付きのマスク編集、または自由形式の入力
• 幅広いカスタマイズ - ドロップダウンボタン、ヘッダー、スピナーのセル、テンプレートをカスタマイズ
• 検証 - カスタムロジックに利用できる変更イベントを備えた組み込みの検証機能
• アクセシビリティ - 完全なキーボード操作と WCAG 準拠

コントロールの構造：

• 時刻を直接入力するためのテキストエディター
• 時刻スピナーを開くドロップダウンボタン
• 時、分、午前／午後の列を備えたドロップダウンスピナー
• ヒントを表示するオプションのドロップダウンヘッダー
• 送信／キャンセルボタン（オプション）

NuGet パッケージ： Syncfusion.Editors.WinUI

名前空間： Syncfusion.UI.Xaml.Editors

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

はじめに

📄 参照： references/getting-started.md

初期設定と基本的な実装については、このリファレンスを参照してください。

• Syncfusion.Editors.WinUI NuGet パッケージのインストール
• XAML と C# コードへの SfTimePicker の追加
• コンポーネント構造（エディター、ドロップダウン、スピナー）の理解
• SelectedTime プロパティを使用したプログラムによる選択時刻の設定
• ドロップダウンからの対話的な時刻選択
• AllowNull プロパティによる null 値の許可
• ヘッダーと説明テキストの追加
• HeaderTemplate によるヘッダーのカスタマイズ
• PlaceholderText による透かしテキストの設定
• SelectedTimeChanged による時刻変更イベントの処理

時刻の制限

📄 参照： references/time-restrictions.md

時刻の選択を制御する方法については、このリファレンスを参照してください。

• MinTime プロパティと MaxTime プロパティによる選択可能な時刻の制限
• BlackoutTimes コレクションを使用した特定時刻の選択不可設定
• カスタム時刻間隔（例：5 分刻み、15 分刻み）の作成
• TimeFieldPrepared イベントによる時刻間隔のカスタマイズ
• ShowSubmitButtons プロパティによる送信ボタンの非表示
• スピナーのスクロールに合わせた時刻の直接選択
• SelectedTimeChanging イベントによる時刻変更のキャンセル
• カスタム検証ロジックの実装
• エッジケースと検証エラーの処理

ローカライズと書式設定

📄 参照: references/localization-formatting.md

時刻表示の書式設定とローカライズには、このリファレンスを使用してください。

• ClockIdentifier を使用して12時間形式と24時間形式を切り替える
• FlowDirection を使用してRTL言語の表示方向を変更する
• Language プロパティを使用してコントロールをローカライズする
• DisplayTimeFormat を使用して時刻の表示形式をカスタマイズする
• 書式パターン（hh:mm tt、HH:mm、h:mm など）を理解する
• マスク編集モードを使用して入力を自動修正する
• 通常の編集モードを使用して自由形式の入力を検証する
• 入力動作とフィールドの自動修正
• ShowClearButton を使用してクリアボタンを表示／非表示にする

ドロップダウンのカスタマイズ

📄 参照: references/dropdown-customization.md

ドロップダウンコンテナーのカスタマイズには、このリファレンスを使用してください。

• DropDownButtonTemplate を使用してドロップダウンボタンのUIをカスタマイズする
• ShowDropDownButton プロパティを使用してドロップダウンボタンを非表示にする
• DropDownPlacement を使用してドロップダウンの配置を変更する
• IsOpen プロパティを使用してドロップダウンをプログラムから開閉する
• DropDownHeight プロパティを使用してドロップダウンの高さを設定する
• VisibleItemsCount プロパティを使用して表示項目数を制御する
• ドロップダウンのスマート配置を理解する
• ドロップダウンを開くキーボードショートカット（Alt+Down）

ドロップダウンヘッダーのカスタマイズ

📄 参照: references/dropdown-header-customization.md

ドロップダウンヘッダーのカスタマイズには、このリファレンスを使用してください。

• DropDownHeader プロパティを使用してドロップダウンヘッダーにヒントを追加する
• ShowDropDownHeader プロパティを使用してヘッダーを表示／非表示にする
• DropDownHeaderTemplate を使用してヘッダーの外観をカスタマイズする
• アイコンとテキストを使ったカスタムヘッダーレイアウトを作成する
• ShowColumnHeaders プロパティを使用して列ヘッダーを非表示にする
• 列ヘッダーのカスタマイズについて理解する
• ヘッダーのスタイル設定に関するベストプラクティス

ドロップダウンスピナーのカスタマイズ

📄 参照: references/dropdown-spinner-customization.md

ドロップダウンスピナーのセルと列のカスタマイズには、このリファレンスを使用してください。

• ItemWidth プロパティと ItemHeight プロパティを使用してセルのサイズを変更する
• MinItemWidth プロパティと MaxItemWidth プロパティを使用してセルの幅を制限する
• ItemContainerStyle プロパティを使用してすべてのセルにスタイルを設定する
• ItemTemplate を使用してセルテンプレートをカスタマイズする
• ItemTemplateSelector を使用して条件に応じたセルのスタイルを設定する
• TimeFieldPrepared イベントを使用して個々の列をカスタマイズする
• 列ごとに列ヘッダー、間隔、セルサイズを変更する
• 特定の時刻セルにアイコンやカスタムコンテンツを追加する
• 大規模なカスタマイズに向けたパフォーマンスの最適化

クイックスタートの例

基本的なTimePickerの実装

XAML:

<Window xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    <Grid>
        <editors:SfTimePicker 
            x:Name="sfTimePicker"
            Header="Select Time"
            PlaceholderText="Pick a time"
            Width="250" />
    </Grid>
</Window>

C#:

using Syncfusion.UI.Xaml.Editors;

// Create TimePicker programmatically
SfTimePicker timePicker = new SfTimePicker();
timePicker.Header = "Select Time";
timePicker.PlaceholderText = "Pick a time";

// Set selected time
timePicker.SelectedTime = new DateTimeOffset(
    new DateTime(2024, 1, 1, 14, 30, 0));

// Handle time changed event
timePicker.SelectedTimeChanged += (s, e) => {
    var oldTime = e.OldDateTime;
    var newTime = e.NewDateTime;
    // Handle time change
};

一般的なパターン

制限付きの時刻選択

時刻選択を営業時間（午前9時～午後5時）に制限します。

// Requires: using Syncfusion.UI.Xaml.Editors;
sfTimePicker.MinTime = new DateTimeOffset(
    new DateTime(DateTime.Now.Year, DateTime.Now.Month, 
                 DateTime.Now.Day, 9, 0, 0));
sfTimePicker.MaxTime = new DateTimeOffset(
    new DateTime(DateTime.Now.Year, DateTime.Now.Month, 
                 DateTime.Now.Day, 17, 0, 0));

24時間形式

24時間形式に切り替えます。

<editors:SfTimePicker 
    ClockIdentifier="24HourClock"
    DisplayTimeFormat="HH:mm" />

カスタムの時刻間隔

15分間隔のみを許可します。

using System.Collections.ObjectModel;
using Syncfusion.UI.Xaml.Editors;

sfTimePicker.TimeFieldPrepared += (s, e) => {
    if (e.Column?.Field == DateTimeField.Minute) {
        var minutes = new ObservableCollection<string>();
        for (int i = 0; i < 60; i += 15) {
            minutes.Add(i.ToString("00"));
        }
        e.Column.ItemsSource = minutes;
    }
};

ランチタイムの選択を禁止

昼休み（午後12時～午後1時）の選択を禁止します。

using Syncfusion.UI.Xaml.Editors;

var blackoutTimes = new DateTimeOffsetCollection();
for (int minute = 0; minute < 60; minute++) {
    blackoutTimes.Add(new DateTimeOffset(
        new DateTime(DateTime.Now.Year, DateTime.Now.Month, 
                     DateTime.Now.Day, 12, minute, 0)));
}
sfTimePicker.BlackoutTimes = blackoutTimes;

主なプロパティ

コアプロパティ

プロパティ	型	説明
SelectedTime	DateTimeOffset?	選択された時刻の値を取得または設定します
MinTime	DateTimeOffset	選択可能な最小時刻（既定値：1/1/1921 10:37:16 PM）
MaxTime	DateTimeOffset	選択可能な最大時刻（既定値：12/31/2121 10:37:16 PM）
BlackoutTimes	DateTimeOffsetCollection	選択不可にする時刻のコレクション
AllowNull	bool	SelectedTime に null 値を許可します（既定値：false）
PlaceholderText	string	SelectedTime が null の場合に表示される透かしテキスト

書式設定プロパティ

プロパティ	型	説明
ClockIdentifier	string	時計の形式：「12HourClock」または「24HourClock」
DisplayTimeFormat	string	時刻表示の書式パターン（例：「hh:mm tt」、「HH:mm」）
EditMode	DateTimeEditMode	編集モード：Mask（自動修正）またはNormal（Enterキーを押したときに検証）
ShowClearButton	bool	クリアボタンの表示／非表示を切り替えます（既定値：true）

ドロップダウンのプロパティ

プロパティ	型	説明
ShowDropDownButton	bool	ドロップダウンボタンの表示／非表示を切り替えます（既定値：true）
DropDownButtonTemplate	DataTemplate	ドロップダウンボタンをカスタマイズするためのテンプレート
DropDownPlacement	FlyoutPlacementMode	ドロップダウンの配置（Auto、Bottom、Top など）
IsOpen	bool	ドロップダウンをプログラムから開閉します
DropDownHeight	double	ドロップダウンスピナーの固定の高さ
VisibleItemsCount	int	ドロップダウンに表示する項目数（既定値：-1）

ドロップダウンヘッダーのプロパティ

プロパティ	型	説明
ShowDropDownHeader	bool	ドロップダウンヘッダーの表示／非表示を切り替えます（既定値：false）
DropDownHeader	object	ドロップダウンヘッダーのコンテンツ
DropDownHeaderTemplate	DataTemplate	ドロップダウンヘッダーをカスタマイズするためのテンプレート
ShowColumnHeaders	bool	スピナーの列ヘッダーの表示／非表示を切り替えます（既定値：true）

スピナーのカスタマイズプロパティ

プロパティ	型	説明
ItemWidth	double	スピナーセルの幅（既定値：80）
ItemHeight	double	スピナーセルの高さ（既定値：40）
MinItemWidth	double	スピナーセルの最小幅（既定値：0）
MaxItemWidth	double	スピナーセルの最大幅（既定値：Infinity）
ItemContainerStyle	Style	すべてのスピナーセルに適用されるスタイル
ItemTemplate	DataTemplate	スピナーセルのコンテンツ用テンプレート
ItemTemplateSelector	DataTemplateSelector	スピナーセルに条件に応じて適用するテンプレート

イベント

イベント	説明
SelectedTimeChanged	SelectedTime の変更後に発生し、変更前と変更後の値を提供します
SelectedTimeChanging	SelectedTime の更新前に発生し、キャンセルできます
TimeFieldPrepared	ドロップダウンスピナーの列が準備されたときに発生し、カスタマイズできます

よくあるユースケース

予約のスケジュール設定

TimePicker を使用して、営業時間の制限、昼休み時間のブロック、15～30分間隔での予約に対応します。

時刻入力フォーム

検証、null 許容の時刻、ユーザーのロケールに応じたカスタム書式を使って、フォームに時刻入力を実装します。

シフト管理

範囲を制限したシフト時刻セレクターを作成します（例：朝勤：午前6時～午後2時、夕勤：午後2時～午後10時、夜勤：午後10時～午前6時）。

会議のスケジューラー

既存の会議時間を選択不可にし、カスタム間隔（30分または1時間枠）を設定した会議時刻ピッカーを作成します。

タイマーアプリケーション

24時間形式でアラーム時刻、カウントダウンタイマー、リマインダーのスケジュールを設定するために TimePicker を使用します。

ローカライズされたアプリケーション

アラビア語／ヘブライ語向けの右から左へのレイアウトと、ロケール固有の書式を使って時刻選択を実装します。

カスタム時刻間隔

特定の間隔が必要な業界向けに、専用の時刻ピッカーを作成します（例：交通機関の時刻表、医療機関の予約）。