syncfusion-winui-calendar-date-range-picker

CalendarDateRangePicker の実装

WinUI CalendarDateRangePicker（SfCalendarDateRangePicker）コントロールは、ドロップダウンカレンダーから日付範囲をすばやく選択できる、直感的でタッチ操作に適したインターフェイスを提供します。さまざまな日付形式、日付範囲の制限、プリセット項目、週番号、ローカライズ、豊富な UI カスタマイズオプションに対応しています。

このスキルを使う場面

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

• 日付範囲の選択を実装する - ユーザーがカレンダーから連続した日付範囲（開始日と終了日）を選択できるようにする
• WinUI アプリに CalendarDateRangePicker を追加する - SfCalendarDateRangePicker コントロールをインストール、構成、使用する
• 範囲選択を構成する - 選択した範囲をプログラムで設定し、範囲変更イベントを処理し、範囲選択を検証する
• 日付選択を制限する - 最小日付／最大日付を適用し、特定の日付を選択不可にし、範囲の期間を制限し、週末の日付をブロックする
• カレンダー UI をカスタマイズする - ドロップダウンの配置を変更し、項目テンプレートをカスタマイズし、テーマを適用し、外観を変更する
• ローカライズに対応する - さまざまなカレンダー形式（グレゴリオ暦、ヘブライ暦、ヒジュラ暦など）を使用し、言語を変更し、RTL を適用する
• 日付表示形式を設定する - エディターとカレンダーで日付や範囲をどのように表示するかをカスタマイズする
• プリセット範囲を表示する - 事前定義された日付範囲（今週、今月、先月、今年、カスタム範囲）を表示する
• 週番号を有効にする - カスタマイズ可能な規則と形式で、カレンダーに週番号を表示する
• ナビゲーションを処理する - ビューの移動（月、年、10 年、世紀）やキーボードショートカットを制御する
• 日付範囲を検証する - 選択した範囲が最小／最大期間の要件を満たしていることを確認する

コンポーネントの概要

CalendarDateRangePicker コントロールは、次の要素で構成されています。

• エディター - 選択した日付範囲を表示するテキスト入力欄
• ドロップダウンボタン - カレンダーのドロップダウンを開く
• ドロップダウンカレンダー - 範囲選択に使用する、月／年／10 年／世紀ビューを備えたインタラクティブなカレンダー
• プリセット項目パネル - 事前定義された日付範囲のオプションリスト
• 確定ボタン - 範囲を確定するための OK／キャンセルボタン（任意）
• 週番号列 - 週番号の表示（任意）
• ヘッダーと説明 - タイトルと補足テキスト（任意）

主な機能：

• タッチ操作に適した範囲選択
• 複数のカレンダーシステム（グレゴリオ暦、ヘブライ暦、ヒジュラ暦、韓国暦など）
• カスタマイズ可能な日付形式
• 日付範囲の制限と検証
• 選択不可日付への対応
• プリセット日付範囲
• 週番号の表示
• キーボードナビゲーション
• テーマのカスタマイズ

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

はじめに

📄 参照： references/getting-started.md

次のような場合に使用します。

• CalendarDateRangePicker コントロールを初めてインストールする
• XAML または C# コードにコントロールを追加する
• 選択範囲をプログラムまたはユーザー操作で設定する
• ヘッダー、説明、プレースホルダーテキストを構成する
• 選択変更イベント（SelectedDateRangeChanged）を処理する
• ドロップダウンボタンを表示または非表示にする
• 確定ボタン（OK／キャンセル）を構成する
• 基本的なコントロールの構造とセットアップを理解する

UI のカスタマイズ

📄 参照： references/ui-customization.md

次のような場合に使用します。

• ドロップダウンの配置（上、下、左、右、中央）を変更する
• ドロップダウンカレンダーのサイズをカスタマイズする
• カレンダー項目のカスタムテンプレートを作成する
• 特別な日付をカスタムスタイルで強調表示する
• 色やフォントにテーマキーを適用する
• 日、週、ヘッダーの外観をカスタマイズする
• 高度なカスタマイズに AttachedFlyout と DropDownFlyout を使用する
• CalendarItem コントロールのスタイルを設定する
• イベントベースの日付装飾を作成する

ローカライズと書式設定

📄 参照： references/localization-formatting.md

次の場合に使用します：

• 異なる暦（ヘブライ暦、ヒジュラ暦、韓国暦、タイ暦、ペルシャ暦など）を使用する
• 表示言語（アラビア語、フランス語、日本語など）を変更する
• エディターの表示形式（DisplayDateFormat）をカスタマイズする
• カレンダーの日付、月、ヘッダーを書式設定する
• 週の開始日を変更する
• 右から左（RTL）の表示方向を実装する
• ロケール固有の日付書式を適用する
• 国際的な日付表記規則に対応する

ビュー間の移動

📄 参照： references/navigation.md

次の場合に使用します：

• 月、年、10年、世紀の各ビュー間の移動を有効にする
• MinDisplayMode と MaxDisplayMode を使用して移動を制限する
• ビューに基づく選択（例：クレジットカードの有効期限の月／年）を実装する
• キーボード操作のショートカットを理解する
• ユーザーがアクセスできるビューを制御する
• 特定の日付またはビュー階層に移動する
• コードでビューの切り替えを処理する

日付範囲の選択制限

📄 参照： references/date-restrictions.md

次の場合に使用します：

• 選択可能な日付の最小値と最大値（MinDate、MaxDate）を設定する
• BlackoutDates コレクションを使用して特定の日付をブロックする
• 週末または祝日を動的に無効にする
• カスタムの日付制限に ItemPrepared イベントを使用する
• 範囲の期間（MinDatesCountInRange、MaxDatesCountInRange）を制限する
• 選択した日付範囲を検証する
• 無効な日付範囲の選択を防止する
• ブロックされた日付の表示テキストをカスタマイズする

プリセット項目

📄 参照： references/preset-items.md

次の場合に使用します：

• 定義済みの日付範囲（今週、今月、先月、今年）を表示する
• カスタムのプリセット項目コレクションを作成する
• カスタムのプリセット UI に PresetTemplate を実装する
• プリセット選択イベントを処理する
• プリセット選択時にカレンダーを非表示にする（ShowCalendar）
• プリセット項目の日付範囲を計算する
• プリセットと併せてカスタム範囲の選択を可能にする

週番号

📄 参照： references/week-numbers.md

次の場合に使用します：

• 週番号の表示（ShowWeekNumbers）を有効にする
• 週番号の規則（FirstDay、FirstFourDayWeek、FirstFullWeek）を設定する
• 接頭辞／接尾辞を使って週番号の形式をカスタマイズする
• カスタムの週番号表示に WeekNumberTemplate を使用する
• 曜日ヘッダーをカスタマイズするために WeekNameTemplate を使用する
• CalendarWeekRule のオプションを理解する
• 週単位のビジネスロジックを適用する

クイックスタート

基本的な実装

XAML：

<Window xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <Grid>
        <calendar:SfCalendarDateRangePicker 
            x:Name="sfCalendarDateRangePicker"
            HorizontalAlignment="Center"
            VerticalAlignment="Center"
            PlaceholderText="Select a date range" />
    </Grid>
</Window>

C#：

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDateRangePicker sfCalendarDateRangePicker = new SfCalendarDateRangePicker();
sfCalendarDateRangePicker.PlaceholderText = "Select a date range";
this.Content = sfCalendarDateRangePicker;

プログラムから選択範囲を設定する

// Set a date range
sfCalendarDateRangePicker.SelectedRange = new DateTimeOffsetRange(
    new DateTimeOffset(new DateTime(2026, 3, 1)), 
    new DateTimeOffset(new DateTime(2026, 3, 15))
);

// Clear selection
sfCalendarDateRangePicker.SelectedRange = null;

選択内容の変更を処理する

sfCalendarDateRangePicker.SelectedDateRangeChanged += (sender, e) =>
{
    var startOld = e.RangeStartOldValue;
    var startNew = e.RangeStartNewValue;
    var endOld = e.RangeEndOldValue;
    var endNew = e.RangeEndNewValue;
    
    // Process the new range
    if (startNew.HasValue && endNew.HasValue)
    {
        TimeSpan duration = endNew.Value - startNew.Value;
        Debug.WriteLine($"Selected range: {duration.Days} days");
    }
};

よく使われるパターン

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

// Restrict to future dates within 90 days
sfCalendarDateRangePicker.MinDate = DateTimeOffset.Now;
sfCalendarDateRangePicker.MaxDate = DateTimeOffset.Now.AddDays(90);
sfCalendarDateRangePicker.MinDatesCountInRange = 3;  // Minimum 3 days
sfCalendarDateRangePicker.MaxDatesCountInRange = 14; // Maximum 14 days

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

sfCalendarDateRangePicker.ItemPrepared += (sender, 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:SfCalendarDateRangePicker 
    Header="Travel Dates"
    Description="Select your departure and return dates"
    PlaceholderText="Choose dates"
    Width="300" />

パターン 4：カスタム表示形式

// Display as full date names
sfCalendarDateRangePicker.DisplayDateFormat = "{0:D} - {1:D}";
// Example: "Saturday, March 1, 2026 - Sunday, March 15, 2026"

パターン 5：ローカライズされたカレンダー

// Hebrew calendar with RTL support
sfCalendarDateRangePicker.CalendarIdentifier = "HebrewCalendar";
sfCalendarDateRangePicker.Language = "he-IL";
sfCalendarDateRangePicker.FlowDirection = FlowDirection.RightToLeft;

主なプロパティ

選択プロパティ

• SelectedRange - 選択された日付範囲を取得または設定します（DateTimeOffsetRange）
• MinDatesCountInRange - 選択範囲内の日付の最小数
• MaxDatesCountInRange - 選択範囲内の日付の最大数

制限プロパティ

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

表示プロパティ

• DisplayDateFormat - エディターで選択範囲を表示する形式（既定値：「{0:d}-{1:d}」）
• PlaceholderText - 範囲が選択されていないときに表示するウォーターマークテキスト
• Header - コントロールの上に表示するタイトル
• HeaderTemplate - ヘッダー用のカスタムテンプレート
• Description - コントロールの下に表示する補足テキスト

Calendar のプロパティ

• CalendarIdentifier - カレンダーの種類（Gregorian、Hebrew、Hijri など）
• FirstDayOfWeek - 週の開始曜日
• ShowWeekNumbers - 週番号を表示します
• WeekNumberRule - 第 1 週の決定ルール（FirstDay、FirstFourDayWeek、FirstFullWeek）
• WeekNumberFormat - 週番号の書式（既定値：「#」）

書式のプロパティ

• DayFormat - カレンダーの日付の書式
• MonthFormat - 年表示での月名の書式
• MonthHeaderFormat - 月／年ヘッダーの書式
• DayOfWeekFormat - 曜日名の書式

ナビゲーションのプロパティ

• MinDisplayMode - 最小の表示レベル（Month、Year、Decade、Century）
• MaxDisplayMode - 最大の表示レベル（Month、Year、Decade、Century）

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

• ShowDropDownButton - ドロップダウンボタンを表示または非表示にします
• ShowSubmitButtons - OK／Cancel ボタンを表示または非表示にします
• ShowCalendar - ドロップダウン内のカレンダーを表示または非表示にします
• DropDownPlacement - ドロップダウンの配置（Bottom、Top、Left、Right、Center）
• DropDownHeight - ドロップダウンカレンダーの高さ

プリセットのプロパティ

• Preset - 日付範囲のプリセットのコレクション
• PresetTemplate - プリセット項目の表示用テンプレート
• PresetPosition - プリセット項目の位置（Left、Right、Top、Bottom）

よくある使用例

1. 予約システム - ホテルの予約、航空券の予約、レンタルサービス
2. レポートツール - レポートや分析用の日付範囲の選択
3. プロジェクト管理 - プロジェクトの開始日と終了日の設定、スプリント計画
4. カレンダーアプリケーション - イベントのスケジュール設定、会議の計画
5. 金融アプリケーション - 明細期間、取引日範囲の選択
6. 人事システム - 休暇管理、バケーション計画、時間の記録
7. E コマース - 配達日の選択、プロモーション期間の設定
8. ヘルスケア - 予約のスケジュール設定、治療期間の計画

関連するスキル

• Calendar - 単一の日付を選択する場合
• CalendarDatePicker - ドロップダウン付きの日付選択ツールを使用して、単一の日付を選択する場合