syncfusion-winui-date-picker

WinUI DatePicker（SfDatePicker）

Syncfusion WinUI DatePicker コントロールを実装するための包括的なガイドです。ドロップダウン式のスピナー、複数の日付形式、日付の制限、豊富なカスタマイズオプションを備えた、直感的でタッチ操作に適した日付選択コントロールです。

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

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

• WinUI デスクトップアプリケーションに日付入力コントロールを追加する
• ドロップダウン式のカレンダースピナーを備えた日付ピッカーを実装する
• 日付選択を特定の範囲に制限する、または特定の日付を除外する
• 複数の暦体系（ヘブライ暦、ヒジュラ暦、ペルシャ暦など）をサポートする
• 日付の表示形式と編集形式をカスタマイズする
• RTL をサポートするローカライズ済みの日付ピッカーを実装する
• タッチ操作に適した日付選択インターフェイスを作成する
• カスタムルールで日付入力を検証する
• ドロップダウンの外観と動作をカスタマイズする
• 日付選択イベントと検証を処理する

コンポーネントの概要

SfDatePicker コントロールは、WinUI 3 デスクトップアプリケーションにモダンな日付入力エクスペリエンスを提供します。編集可能なテキストフィールドとドロップダウン式の日付スピナーを組み合わせ、さまざまな日付形式、暦の種類、検証ルールをサポートします。

主な特長：

• タッチ操作に適したドロップダウン式の日付スピナーインターフェイス
• 複数の日付形式に対応（表示形式と編集形式）
• 日付範囲の制限（MinDate、MaxDate）
• 特定の日付を除外するブラックアウト日付
• 複数の暦の種類（グレゴリオ暦、ヘブライ暦、ヒジュラ暦、ペルシャ暦など）
• ローカライズと RTL のサポート
• マスク編集モードと自由形式編集モード
• カスタマイズ可能なドロップダウン UI とスピナーセル
• 組み込みの検証機能と透かしテキスト
• XAML と C# による構成をサポート

パッケージ： Syncfusion.Editors.WinUI
名前空間： Syncfusion.UI.Xaml.Editors
コントロール： SfDatePicker

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

はじめに

📄 参照： references/getting-started.md

初期設定と基本的な使い方については、こちらから始めてください。

• Syncfusion.Editors.WinUI パッケージのインストール
• XAML と C# コードへの SfDatePicker の追加
• 選択した日付の設定と取得（SelectedDate プロパティ）
• ドロップダウンからの日付の対話的な選択
• null 値の有効化（AllowNull プロパティ）
• プレースホルダーテキスト（透かし）の追加
• ヘッダーと説明の設定
• ヘッダーテンプレートのカスタマイズ
• 日付変更イベントの処理（SelectedDateChanged）

日付の制限

📄 参照： references/date-restriction.md

日付選択の制限と検証方法を学びます。

• 最小および最大の日付範囲の設定（MinDate、MaxDate）
• BlackoutDates コレクションによる特定の日付の除外
• 日付の動的な無効化（DateFieldItemPrepared イベント）
• プログラムによる週末の日付の除外
• 即時選択のための送信ボタンの非表示
• 日付変更のキャンセル（SelectedDateChanging イベント）
• 日付の検証パターンとエラー処理

ローカライズと書式設定

📄 参照： references/localization-formatting.md

暦の種類、形式、ローカライズを設定します。

• 暦の種類の変更（CalendarIdentifier：ヘブライ暦、ヒジュラ暦、ペルシャ暦など）
• RTL 言語のフロー方向の設定
• Language プロパティによるローカライズ
• 表示形式のカスタマイズ（DisplayDateFormat）
• 日、月、年フィールドの書式設定（DayFormat、MonthFormat、YearFormat）
• 自動修正機能付きのマスク編集モード
• 自由形式編集モード（EditMode）
• クリアボタンの表示／非表示（ShowClearButton）

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

📄 参照： references/dropdown-customization.md

ドロップダウンボタンとコンテナーをカスタマイズします。

• ドロップダウンボタン UI のカスタマイズ（DropDownButtonTemplate）
• ドロップダウンボタンの非表示（ShowDropDownButton）
• ドロップダウンの配置の変更（DropDownPlacement）
• プログラムによるドロップダウンの表示（IsOpen プロパティ）
• ドロップダウンの高さの設定（DropDownHeight）
• 表示項目数の制御（VisibleItemsCount）

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

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

ドロップダウンのヘッダー領域を設定します：

• ドロップダウンヘッダーへのヒントの追加（DropDownHeader）
• ドロップダウンヘッダーの表示／非表示（ShowDropDownHeader）
• ヘッダー UI のカスタマイズ（DropDownHeaderTemplate）
• 列ヘッダーの非表示（ShowColumnHeaders）
• ヘッダーのレイアウトパターン

スピナーのカスタマイズ

📄 参照： references/spinner-customization.md

日付スピナーのセルと列をカスタマイズします：

• セルの寸法の設定（ItemWidth、ItemHeight）
• セル幅の制限（MinItemWidth、MaxItemWidth）
• スピナーセルのスタイル設定（ItemContainerStyle）
• カスタムセルテンプレート（ItemTemplate）
• 条件付きセル表示（ItemTemplateSelector）
• 列のカスタマイズ（DateFieldPrepared イベント）
• 個々の日付フィールドの書式設定
• スピナーでの日付のループを有効化

クイックスタートの例

基本的な DatePicker の設定

XAML：

<Window
    x:Class="DatePickerDemo.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    
    <Grid>
        <editors:SfDatePicker 
            x:Name="datePicker"
            Header="Select Date"
            PlaceholderText="Choose a date"
            SelectedDate="2026-03-22"
            Width="250" 
            Height="75" />
    </Grid>
</Window>

C#：

using Syncfusion.UI.Xaml.Editors;

namespace DatePickerDemo
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
            
            // Creating an instance of the Date Picker control
            SfDatePicker sfDatePicker = new SfDatePicker();
            this.Content = sfDatePicker;
        }
    }
}

よく使われるパターン

パターン 1：日付範囲の制限

<editors:SfDatePicker 
    x:Name="datePicker"
    MinDate="2026-01-01"
    MaxDate="2026-12-31"
    Header="Select date within 2026" />

パターン 2：特定の日付の選択を禁止

// In ViewModel or code-behind
public DateTimeOffsetCollection BlockedDates { get; set; }

public void InitializeBlockedDates()
{
    BlockedDates = new DateTimeOffsetCollection();
    BlockedDates.Add(new DateTimeOffset(new DateTime(2026, 12, 25))); // Christmas
    BlockedDates.Add(new DateTimeOffset(new DateTime(2026, 1, 1)));   // New Year
}

<editors:SfDatePicker 
    BlackoutDates="{Binding BlockedDates}" />

パターン 3：日付形式のカスタマイズ

<editors:SfDatePicker 
    DisplayDateFormat="MMMM dd, yyyy"
    DayFormat="{}{day.integer}"
    MonthFormat="{}{month.full}"
    YearFormat="{}{year.full}" />

パターン 4：カレンダーの種類を指定したローカライズ済み DatePicker

<editors:SfDatePicker 
    CalendarIdentifier="HebrewCalendar"
    Language="he-IL"
    FlowDirection="RightToLeft" />

パターン 5：null 値のサポート

<editors:SfDatePicker 
    AllowNull="True"
    SelectedDate="{x:Null}"
    PlaceholderText="Select a date" />

パターン 6：即時選択（送信ボタンなし）

<editors:SfDatePicker 
    ShowSubmitButtons="False" />

主要なプロパティのリファレンス

日付の選択

プロパティ	型	説明
SelectedDate	DateTimeOffset?	選択した日付を取得または設定します
AllowNull	bool	null 値の選択を許可します

日付の制限

プロパティ	型	説明
MinDate	DateTimeOffset	選択可能な最小の日付（既定値：1/1/1921）
MaxDate	DateTimeOffset	選択可能な最大の日付（既定値：12/31/2121）
BlackoutDates	DateTimeOffsetCollection	選択できない日付のコレクション

書式設定

プロパティ	型	説明
DisplayDateFormat	string	エディターでの表示形式（既定値："d"）
DayFormat	string	スピナーの日フィールドの書式
MonthFormat	string	スピナーの月フィールドの書式
YearFormat	string	スピナーの年フィールドの書式

ローカライズ

プロパティ	型	説明
CalendarIdentifier	string	カレンダーの種類（Gregorian、Hebrew、Hijri など）
Language	string	ローカライズに使用する言語／カルチャ

ドロップダウンの設定

プロパティ	型	説明
DropDownHeader	object	ドロップダウンのヘッダーコンテンツ
ShowDropDownHeader	bool	ドロップダウンヘッダーの表示／非表示を切り替えます
ShowColumnHeaders	bool	スピナーの列ヘッダーの表示／非表示を切り替えます
ShowDropDownButton	bool	ドロップダウンボタンの表示／非表示を切り替えます
IsOpen	bool	プログラムからドロップダウンを開閉します
DropDownHeight	double	ドロップダウンスピナーの高さ
VisibleItemsCount	int	スピナーに表示する項目数

スピナー項目のサイズ設定

プロパティ	型	説明
ItemWidth	double	スピナーセルの幅（既定値：80）
ItemHeight	double	スピナーセルの高さ（既定値：40）
MinItemWidth	double	セルの最小幅
MaxItemWidth	double	セルの最大幅

UI のカスタマイズ

プロパティ	型	説明
PlaceholderText	string	日付が選択されていない場合の透かしテキスト
Header	object	コントロールの上に表示するヘッダーコンテンツ
Description	object	コントロールの下に表示する説明テキスト
ItemTemplate	DataTemplate	スピナーセルのテンプレート
ItemTemplateSelector	DataTemplateSelector	条件付きセルテンプレート
ItemContainerStyle	Style	スピナーセルのスタイル
ShowClearButton	bool	エディターのクリアボタンの表示／非表示を切り替えます
ShowSubmitButtons	bool	OK／キャンセルボタンの表示／非表示を切り替えます

編集

プロパティ	型	説明
EditMode	DateTimeEditMode	マスクまたは通常の編集モード

イベント

イベント	説明
SelectedDateChanged	選択した日付が変更されたときに発生します
SelectedDateChanging	日付が変更される前に発生します（キャンセル可能）
DateFieldItemPrepared	各スピナー項目に対して発生します（カスタマイズ用）
DateFieldPrepared	各スピナー列に対して発生します（カスタマイズ用）

一般的なユースケース

ユースケース 1：予約スケジューラー

営業時間のみの予約日を選択するための日付ピッカー：

// Block weekends and restrict to business days
datePicker.DateFieldItemPrepared += (s, e) =>
{
    if (e.ItemInfo.DateTime.Value.DayOfWeek == DayOfWeek.Saturday ||
        e.ItemInfo.DateTime.Value.DayOfWeek == DayOfWeek.Sunday)
    {
        e.ItemInfo.IsEnabled = false;
    }
};

ユースケース 2：予約システム

利用できない日付をブラックアウトする日付ピッカー：

// Mark booked dates as unavailable
var bookedDates = GetBookedDatesFromDatabase();
datePicker.BlackoutDates = new DateTimeOffsetCollection();
foreach (var date in bookedDates)
{
    datePicker.BlackoutDates.Add(new DateTimeOffset(date));
}

ユースケース 3：生年月日の入力

過去の日付を入力するための日付ピッカー：

<editors:SfDatePicker 
    Header="Date of Birth"
    MaxDate="{x:Bind CurrentDate}"
    MinDate="1920-01-01"
    DisplayDateFormat="MMMM dd, yyyy" />

ユースケース 4：多言語アプリケーション

RTL を自動検出するローカライズ済みの日付ピッカー：

// Set based on user's locale
datePicker.Language = currentUser.PreferredLanguage;
datePicker.CalendarIdentifier = currentUser.CalendarType;

ユースケース 5：ブランドに合わせたカスタム UI

色とアイコンをカスタマイズした日付ピッカー：

<editors:SfDatePicker>
    <editors:SfDatePicker.DropDownButtonTemplate>
        <DataTemplate>
            <FontIcon Glyph="&#xE787;" Foreground="Blue" />
        </DataTemplate>
    </editors:SfDatePicker.DropDownButtonTemplate>
</editors:SfDatePicker>

その他のリソース

• NuGet パッケージ： Syncfusion.Editors.WinUI
• 公式ドキュメント： WinUI DatePicker のドキュメント
• GitHub のサンプル： SyncfusionExamples/syncfusion-winui-tools-datepicker-examples

---

次のステップ： 実装のニーズに応じて上記のドキュメントセクションを選ぶか、基本的なセットアップについては「はじめに」ガイドから始めてください。