syncfusion-winui-calendar-date-picker

Syncfusion WinUI Calendar Date Picker

WinUI 3 デスクトップアプリケーションで Calendar Date Picker コントロールを実装するための包括的なガイドです。SfCalendarDatePicker は、豊富なカスタマイズオプションを備えたドロップダウンカレンダーから日付を選択できる、直感的でタッチ操作に適したインターフェイスを提供します。

このスキルを使う場面

次のような場合にこのスキルを使用します。

• WinUI アプリケーションで、カレンダーのドロップダウンを使った日付入力を実装する
• 視覚的なカレンダーインターフェイスで日付を選択できるようにする
• 最小日付／最大日付または選択不可日を使って日付の選択を制限する
• カレンダーの外観と動作をカスタマイズする
• 複数の暦法（グレゴリオ暦、ヘブライ暦、ヒジュラ暦など）をサポートする
• カレンダーに週番号を表示する
• 月／年／10年／世紀単位のビュー間の移動を実装する
• さまざまなカルチャに対応したローカライズ済みの日付ピッカーを作成する
• 日付の検証と選択イベントを処理する
• 特定の日付（週末、祝日など）を選択できないようにする

コンポーネントの概要

SfCalendarDatePicker コントロールは、テキストエディターとドロップダウンカレンダーを組み合わせており、ユーザーは日付を入力するか、カレンダーから選択できます。さまざまな日付形式や暦法に対応し、豊富なカスタマイズオプションを備えています。

主な機能：

• ドロップダウンカレンダーまたはキーボード入力による日付選択
• 最小日付／最大日付による制限
• 特定の日付を選択できないようにする選択不可日の設定
• カスタムロジックによる動的な日付のブロック
• 複数の暦法への対応（グレゴリオ暦、ヘブライ暦、ヒジュラ暦など）
• さまざまなカルチャと言語へのローカライズ
• 設定可能なルールによる週番号の表示
• ビュー間の移動（月、年、10年、世紀）
• 日付形式と表示のカスタマイズ
• テーマとテンプレートのカスタマイズ
• タッチ操作に適したインターフェイス
• 組み込みの検証機能とイベント

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

はじめに

📄 参照： references/getting-started.md

初期実装はここから始めてください。次の内容を説明します。

• Syncfusion.Calendar.WinUI NuGet パッケージのインストール
• WinUI 3 アプリケーションのセットアップ
• 基本的な XAML と C# の実装
• プログラムによる日付選択とユーザー操作による日付選択
• AllowNull プロパティを使った null 値の処理
• ヘッダーと説明の設定
• ウォーターマークテキスト（PlaceholderText）
• SelectedDateChanged イベントと SelectedDateChanging イベント
• 編集モード（Mask または Normal／自由形式の編集）
• ドロップダウンボタンの表示／非表示
• 送信ボタンの設定

日付の選択と制限

📄 参照： references/date-selection-restriction.md

ユーザーが選択できる日付を制御する方法を説明します。

• SelectedDate プロパティによる日付の取得／設定
• MinDate と MaxDate による日付範囲の制限
• BlackoutDates コレクションによる特定の日付のブロック
• CalendarItemPrepared イベントによる動的な日付のブロック
• 週末や祝日のブロック
• 特定の日付に表示するカスタムテキスト
• SelectionHighlightMode（Outline または Filled）
• SelectionShape（Circle または Rectangle）
• 検証パターンとエッジケース

UI のカスタマイズ

📄 参照： references/ui-customization.md

外観と動作をカスタマイズします。

• ShowClearButton によるクリアボタンの表示／非表示
• DropDownPlacement による配置（Left、Right、Top、Bottom、Center）
• サイズを設定する DropDownWidth と DropDownHeight
• OutOfScopeVisibility による前後の日付の表示／非表示
• AttachedFlyout と DropDownFlyout を使ったカスタム項目テンプレート
• 特別な日付を強調表示する EventDataConverter パターン
• テーマキーのカスタマイズ（色、フォント、境界線）
• ContentTemplate を使った CalendarItem のスタイル設定
• 高度なテンプレートパターン

ローカライズと書式設定

📄 参照： references/localization-formatting.md

カレンダーの種類、言語、日付形式を設定します。

• CalendarIdentifier：さまざまな暦法（グレゴリオ暦、ヘブライ暦、ヒジュラ暦、韓国暦、台湾暦、タイ暦、ペルシャ暦、ウム・アル・クラー暦）を指定します
• Language プロパティ：文化圏に応じた表示に使用します
• DisplayDateFormat：エディターのテキスト形式を指定します
• DayFormat、MonthFormat、DayOfWeekFormat：カレンダーの表示形式を指定します
• MonthHeaderFormat：ヘッダーの形式をカスタマイズします
• FirstDayOfWeek：週の開始曜日を設定します
• NumberOfWeeksInView：表示する週数を設定します
• DateTimeFormatter のパターン

ビュー間の移動

📄 参照： references/navigation.md

ビューのモードと移動動作を制御します。

• DisplayMode プロパティ（月、年、10年、世紀）
• MinDisplayMode と MaxDisplayMode によるビューの制限
• 特定のユースケース（クレジットカードの有効期限など）に応じたビュー移動パターン
• 移動用のキーボードショートカット（Tab、矢印キー、Ctrl+矢印、PageUp/Down、Home/End）
• マウス操作のパターン
• ビューの制限に基づく選択

週番号

📄 参照： references/week-numbers.md

週番号を表示し、カスタマイズします。

• ShowWeekNumbers プロパティで週番号の表示を有効にします
• WeekNumberRule（FirstDay、FirstFourDayWeek、FirstFullWeek）
• WeekNumberFormat：接頭辞と接尾辞を使ったカスタム書式
• WeekNumberTemplate：表示を全面的にカスタマイズします
• WeekNameTemplate：曜日名をカスタマイズします
• CalendarItemTemplateSelector の使用

クイックスタートの例

インストール

NuGet パッケージをインストールします。

Install-Package Syncfusion.Calendar.WinUI

基本的な実装

XAML：

<Window
    xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    
    <Grid>
        <calendar:SfCalendarDatePicker 
            x:Name="calendarDatePicker"
            Header="Select Date"
            PlaceholderText="Choose a date"
            SelectedDate="{x:Bind ViewModel.SelectedDate, Mode=TwoWay}"
            MinDate="2024-01-01"
            MaxDate="2024-12-31"
            DisplayDateFormat="MM/dd/yyyy" />
    </Grid>
</Window>

C#：

using Syncfusion.UI.Xaml.Calendar;

// Create instance
SfCalendarDatePicker datePicker = new SfCalendarDatePicker();

// Configure properties
datePicker.Header = "Select Date";
datePicker.PlaceholderText = "Choose a date";
datePicker.SelectedDate = DateTimeOffset.Now;
datePicker.MinDate = new DateTimeOffset(new DateTime(2024, 1, 1));
datePicker.MaxDate = new DateTimeOffset(new DateTime(2024, 12, 31));
datePicker.DisplayDateFormat = "MM/dd/yyyy";

// Handle selection changed
datePicker.SelectedDateChanged += (s, e) =>
{
    var oldDate = e.OldDate;
    var newDate = e.NewDate;
    // Process date change
};

this.Content = datePicker;

よく使われるパターン

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

ユーザーが特定の範囲内の日付のみを選択できるようにします。

// Only allow dates in current year
datePicker.MinDate = new DateTimeOffset(new DateTime(DateTime.Now.Year, 1, 1));
datePicker.MaxDate = new DateTimeOffset(new DateTime(DateTime.Now.Year, 12, 31));

パターン 2：週末の日をブロック

週末の日を選択できないようにします。

datePicker.CalendarItemPrepared += (s, e) =>
{
    if (e.ItemInfo.ItemType == CalendarItemType.Day &&
        (e.ItemInfo.Date.DayOfWeek == DayOfWeek.Saturday ||
         e.ItemInfo.Date.DayOfWeek == DayOfWeek.Sunday))
    {
        e.ItemInfo.IsBlackout = true;
    }
};

パターン 3：クレジットカードの有効期限の選択

月と年のみを選択できるようにします。

<calendar:SfCalendarDatePicker 
    MinDisplayMode="Year"
    MaxDisplayMode="Decade"
    DisplayDateFormat="MM/yyyy" />

パターン 4：ローカライズされた日付ピッカー

特定の文化圏向けの日付ピッカーを作成します。

datePicker.CalendarIdentifier = "HebrewCalendar";
datePicker.Language = "he-IL";
datePicker.FirstDayOfWeek = DayOfWeek.Sunday;

主なプロパティ一覧

日付の選択

• SelectedDate - 現在選択されている日付を取得または設定します
• AllowNull - 日付が選択されていない場合に null 値を許可します

日付の制限

• MinDate - 選択可能な最小日付（既定値：1/1/1920）
• MaxDate - 選択可能な最大日付（既定値：12/31/2120）
• BlackoutDates - 選択対象から除外する日付のコレクション

表示と書式設定

• DisplayDateFormat - エディター表示の書式文字列（既定値："d"）
• DayFormat - カレンダーの日付番号の書式
• MonthFormat - 月名の書式
• DayOfWeekFormat - 曜日ヘッダーの書式
• MonthHeaderFormat - 月／年ヘッダーの書式

カレンダーの設定

• CalendarIdentifier - 暦法（グレゴリオ暦、ヘブライ暦、ヒジュラ暦など）
• FirstDayOfWeek - 週の初日（既定値：日曜日）
• NumberOfWeeksInView - 月表示に表示する週数（既定値：6）

移動とビュー

• DisplayMode - 現在のビューのモード（月、年、10年、世紀）
• MinDisplayMode - 許可される最小のビューのモード
• MaxDisplayMode - 許可される最大のビューのモード

週番号

• ShowWeekNumbers - 週番号を表示します（既定値：false）
• WeekNumberRule - 年の第1週の規則（FirstDay、FirstFourDayWeek、FirstFullWeek）
• WeekNumberFormat - 週番号の書式文字列（既定値："#"）

UI のカスタマイズ

• PlaceholderText - 日付が選択されていない場合に表示する透かしテキスト
• OutOfScopeVisibility - 範囲外の日付の表示／非表示（Enabled、Hidden）
• DropDownWidth - ドロップダウンカレンダーの幅
• DropDownHeight - ドロップダウンカレンダーの高さ
• SelectionHighlightMode - 選択箇所の強調表示スタイル（Outline、Filled）
• SelectionShape - 選択箇所の形状（Circle、Rectangle）

その他のリソース

• Syncfusion WinUI Calendar Date Picker のドキュメント
• GitHub のサンプル
• API リファレンス