syncfusion-winui-date-picker（Synfusion WinUI 日期选择器）

WinUI DatePicker (SfDatePicker)

A comprehensive guide for implementing the Syncfusion WinUI DatePicker control - an intuitive, touch-friendly date selection control with dropdown spinner, multiple date formats, date restrictions, and extensive customization options.

When to Use This Skill

Use this skill when you need to:

• Add date input controls to WinUI desktop applications
• Implement date pickers with dropdown calendar spinners
• Restrict date selection to specific ranges or block certain dates
• Support multiple calendar systems (Hebrew, Hijri, Persian, etc.)
• Customize date display and edit formats
• Implement localized date pickers with RTL support
• Create touch-friendly date selection interfaces
• Validate date input with custom rules
• Customize dropdown appearance and behavior
• Handle date selection events and validation

Component Overview

The SfDatePicker control provides a modern date input experience for WinUI 3 desktop applications. It combines an editable text field with a dropdown date spinner, supporting various date formats, calendar types, and validation rules.

Key Characteristics:

• Touch-friendly dropdown date spinner interface
• Multiple date format support (display and edit formats)
• Date range restrictions (MinDate, MaxDate)
• Blackout dates for blocking specific dates
• Multiple calendar types (Gregorian, Hebrew, Hijri, Persian, etc.)
• Localization and RTL support
• Mask and free-form editing modes
• Customizable dropdown UI and spinner cells
• Built-in validation and watermark text
• XAML and C# configuration support

Package: Syncfusion.Editors.WinUI Namespace: Syncfusion.UI.Xaml.Editors Control: SfDatePicker

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

Start here for initial setup and basic usage:

• Installing Syncfusion.Editors.WinUI package
• Adding SfDatePicker to XAML and C# code
• Setting and getting selected date (SelectedDate property)
• Interactive date selection from dropdown
• Enabling null values (AllowNull property)
• Adding placeholder text (watermark)
• Configuring header and description
• Customizing header template
• Handling date changed events (SelectedDateChanged)

Date Restriction

📄 Read: references/date-restriction.md

Learn how to restrict and validate date selection:

• Setting minimum and maximum date ranges (MinDate, MaxDate)
• Blocking specific dates with BlackoutDates collection
• Dynamically disabling dates (DateFieldItemPrepared event)
• Blocking weekend dates programmatically
• Hiding submit buttons for immediate selection
• Canceling date changes (SelectedDateChanging event)
• Date validation patterns and error handling

Localization and Formatting

📄 Read: references/localization-formatting.md

Configure calendar types, formats, and localization:

• Changing calendar type (CalendarIdentifier: Hebrew, Hijri, Persian, etc.)
• Setting flow direction for RTL languages
• Localizing with Language property
• Customizing display format (DisplayDateFormat)
• Formatting day, month, year fields (DayFormat, MonthFormat, YearFormat)
• Mask editing mode with auto-correction
• Free-form editing mode (EditMode)
• Showing/hiding clear button (ShowClearButton)

Dropdown Customization

📄 Read: references/dropdown-customization.md

Customize the dropdown button and container:

• Customizing dropdown button UI (DropDownButtonTemplate)
• Hiding dropdown button (ShowDropDownButton)
• Changing dropdown alignment (DropDownPlacement)
• Opening dropdown programmatically (IsOpen property)
• Setting dropdown height (DropDownHeight)
• Controlling visible items count (VisibleItemsCount)

Dropdown Header Customization

📄 Read: references/dropdown-header-customization.md

Configure the dropdown header area:

• Adding hints in dropdown header (DropDownHeader)
• Showing/hiding dropdown header (ShowDropDownHeader)
• Customizing header UI (DropDownHeaderTemplate)
• Hiding column headers (ShowColumnHeaders)
• Header layout patterns

Spinner Customization

📄 Read: references/spinner-customization.md

Customize the date spinner cells and columns:

• Setting cell dimensions (ItemWidth, ItemHeight)
• Restricting cell width (MinItemWidth, MaxItemWidth)
• Styling spinner cells (ItemContainerStyle)
• Custom cell templates (ItemTemplate)
• Conditional cell appearance (ItemTemplateSelector)
• Customizing columns (DateFieldPrepared event)
• Formatting individual date fields
• Enabling date looping in spinner

Quick Start Example

Basic DatePicker Setup

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

Common Patterns

Pattern 1: Date Range Restriction

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

Pattern 2: Blocking Specific Dates

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

Pattern 3: Custom Date Format

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

Pattern 4: Localized DatePicker with Calendar Type

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

Pattern 5: Null Value Support

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

Pattern 6: Immediate Selection (No Submit Button)

<editors:SfDatePicker
    ShowSubmitButtons="False" />

Key Properties Reference

Date Selection

Date Restriction

Formatting

Localization

Dropdown Configuration

Spinner Item Sizing

UI Customization

Editing

Events

Common Use Cases

Use Case 1: Appointment Scheduler

Date picker for selecting appointment dates with working hours only:

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

Use Case 2: Booking System

Date picker with blackout dates for unavailable dates:

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

Use Case 3: Birth Date Entry

Date picker for entering historical dates:

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

Use Case 4: Multi-Language Application

Localized date picker with automatic RTL detection:

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

Use Case 5: Custom Branded UI

Date picker with custom colors and icons:

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

Additional Resources

• NuGet Package: Syncfusion.Editors.WinUI
• Official Documentation: WinUI DatePicker Docs
• GitHub Examples: SyncfusionExamples/syncfusion-winui-tools-datepicker-examples

Next Steps: Choose a documentation section above based on your implementation needs, or start with the Getting Started guide for basic setup.