syncfusion-winui-calendar-date-range-picker（Synfusion WinUI 日历日期范围选择器）

Implementing Calendar DateRange Picker

The WinUI CalendarDateRangePicker (SfCalendarDateRangePicker) control provides an intuitive, touch-friendly interface to quickly select a date range from a drop-down calendar. It supports different date formats, date range restrictions, preset items, week numbers, localization, and extensive UI customization options.

When to Use This Skill

Use this skill when you need to:

• Implement date range selection - Allow users to select a continuous range of dates (start date and end date) from a calendar
• Add CalendarDateRangePicker to WinUI apps - Install, configure, and use the SfCalendarDateRangePicker control
• Configure range selection - Set selected range programmatically, handle range change events, validate range selection
• Restrict date selection - Apply min/max dates, blackout specific dates, limit range duration, block weekend dates
• Customize calendar UI - Change drop-down alignment, customize item templates, apply themes, modify appearance
• Support localization - Use different calendar types (Gregorian, Hebrew, Hijri, etc.), change languages, apply RTL
• Format date display - Customize how dates and ranges are displayed in the editor and calendar
• Show preset ranges - Display predefined date ranges (This Week, This Month, Last Month, This Year, Custom Range)
• Enable week numbers - Show week numbers in the calendar with customizable rules and formats
• Handle navigation - Control view navigation (month, year, decade, century), keyboard shortcuts
• Validate date ranges - Ensure selected ranges meet minimum/maximum duration requirements

Component Overview

The CalendarDateRangePicker control consists of:

• Editor - Text input displaying the selected date range
• Drop-down button - Opens the calendar drop-down
• Drop-down calendar - Interactive calendar for range selection with month/year/decade/century views
• Preset items panel - Optional list of predefined date ranges
• Submit buttons - Optional OK/Cancel buttons for range confirmation
• Week numbers column - Optional display of week numbers
• Header and description - Optional title and helper text

Key capabilities:

• Touch-friendly range selection
• Multiple calendar systems (Gregorian, Hebrew, Hijri, Korean, etc.)
• Customizable date formats
• Date range restrictions and validation
• Blackout dates support
• Preset date ranges
• Week number display
• Keyboard navigation
• Theme customization

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

Use when:

• Installing the CalendarDateRangePicker control for the first time
• Adding the control to XAML or C# code
• Setting the selected range programmatically or interactively
• Configuring header, description, and placeholder text
• Handling selection changed events (SelectedDateRangeChanged)
• Showing or hiding the drop-down button
• Configuring submit buttons (OK/Cancel)
• Understanding basic control structure and setup

UI Customization

📄 Read: references/ui-customization.md

Use when:

• Changing drop-down alignment (top, bottom, left, right, center)
• Customizing drop-down calendar size
• Creating custom calendar item templates
• Highlighting special dates with custom styling
• Applying theme keys for colors and fonts
• Customizing day, week, and header appearance
• Using AttachedFlyout and DropDownFlyout for advanced customization
• Styling the CalendarItem control
• Creating event-based date decorations

Localization and Formatting

📄 Read: references/localization-formatting.md

Use when:

• Using different calendar types (Hebrew, Hijri, Korean, Thai, Persian, etc.)
• Changing the display language (Arabic, French, Japanese, etc.)
• Customizing editor display format (DisplayDateFormat)
• Formatting calendar days, months, and headers
• Changing the first day of the week
• Implementing right-to-left (RTL) flow direction
• Applying locale-specific date formatting
• Supporting international date conventions

Navigation Between Views

📄 Read: references/navigation.md

Use when:

• Enabling navigation between month, year, decade, and century views
• Restricting navigation with MinDisplayMode and MaxDisplayMode
• Implementing view-based selection (e.g., month/year for credit cards)
• Understanding keyboard navigation shortcuts
• Controlling which views users can access
• Navigating to specific dates or view levels
• Handling view switching in code

Restricting Date Range Selection

📄 Read: references/date-restrictions.md

Use when:

• Setting minimum and maximum selectable dates (MinDate, MaxDate)
• Blocking specific dates using BlackoutDates collection
• Disabling weekend dates or holidays dynamically
• Using ItemPrepared event for custom date restrictions
• Limiting range duration (MinDatesCountInRange, MaxDatesCountInRange)
• Validating selected date ranges
• Preventing invalid date range selection
• Customizing display text for blocked dates

Preset Items

📄 Read: references/preset-items.md

Use when:

• Showing predefined date ranges (This Week, This Month, Last Month, This Year)
• Creating custom preset items collection
• Implementing PresetTemplate for custom preset UI
• Handling preset selection events
• Hiding calendar when preset is selected (ShowCalendar)
• Calculating date ranges for preset items
• Allowing custom range selection alongside presets

Week Numbers

📄 Read: references/week-numbers.md

Use when:

• Enabling week number display (ShowWeekNumbers)
• Configuring week number rules (FirstDay, FirstFourDayWeek, FirstFullWeek)
• Customizing week number format with prefix/suffix
• Using WeekNumberTemplate for custom week number appearance
• Customizing WeekNameTemplate for day-of-week headers
• Understanding CalendarWeekRule options
• Applying week-based business logic

Quick Start

Basic Implementation

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;

Setting Selected Range Programmatically

// 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;

Handling Selection Changes

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");
    }
};

Common Patterns

Pattern 1: Date Range with Restrictions

// 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

Pattern 2: Blocking Weekend Dates

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;
    }
};

Pattern 3: With Header and Description

<calendar:SfCalendarDateRangePicker
    Header="Travel Dates"
    Description="Select your departure and return dates"
    PlaceholderText="Choose dates"
    Width="300" />

Pattern 4: Custom Display Format

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

Pattern 5: Localized Calendar

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

Key Properties

Selection Properties

• SelectedRange - Gets or sets the selected date range (DateTimeOffsetRange)
• MinDatesCountInRange - Minimum number of dates in the selected range
• MaxDatesCountInRange - Maximum number of dates in the selected range

Restriction Properties

• MinDate - Minimum selectable date (default: 1/1/1920)
• MaxDate - Maximum selectable date (default: 12/31/2120)
• BlackoutDates - Collection of dates to disable

Display Properties

• DisplayDateFormat - Format for displaying the selected range in the editor (default: "{0:d}-{1:d}")
• PlaceholderText - Watermark text when no range is selected
• Header - Title above the control
• HeaderTemplate - Custom template for the header
• Description - Helper text below the control

Calendar Properties

• CalendarIdentifier - Calendar system (Gregorian, Hebrew, Hijri, etc.)
• FirstDayOfWeek - Starting day of the week
• ShowWeekNumbers - Display week numbers
• WeekNumberRule - Rule for determining first week (FirstDay, FirstFourDayWeek, FirstFullWeek)
• WeekNumberFormat - Format for week numbers (default: "#")

Format Properties

• DayFormat - Format for day numbers in calendar
• MonthFormat - Format for month names in year view
• MonthHeaderFormat - Format for month/year header
• DayOfWeekFormat - Format for day-of-week names

Navigation Properties

• MinDisplayMode - Minimum view level (Month, Year, Decade, Century)
• MaxDisplayMode - Maximum view level (Month, Year, Decade, Century)

Drop-down Properties

• ShowDropDownButton - Show or hide the drop-down button
• ShowSubmitButtons - Show or hide OK/Cancel buttons
• ShowCalendar - Show or hide the calendar in drop-down
• DropDownPlacement - Alignment of drop-down (Bottom, Top, Left, Right, Center)
• DropDownHeight - Height of the drop-down calendar

Preset Properties

• Preset - Collection of preset date ranges
• PresetTemplate - Template for displaying preset items
• PresetPosition - Position of preset items (Left, Right, Top, Bottom)

Common Use Cases

1. Booking Systems - Hotel reservations, flight bookings, rental services
2. Reporting Tools - Select date ranges for reports and analytics
3. Project Management - Define project start and end dates, sprint planning
4. Calendar Applications - Event scheduling, meeting planning
5. Financial Applications - Select statement periods, transaction date ranges
6. HR Systems - Leave management, vacation planning, time tracking
7. E-commerce - Delivery date selection, promotional period setup
8. Healthcare - Appointment scheduling, treatment duration planning

Related Skills

• Calendar - For single date selection
• CalendarDatePicker - For single date picker with drop-down