syncfusion-winui-date-picker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

这是一份实现Syncfusion WinUI DatePicker控件的全面指南，该控件是直观、适配触控的日期选择控件，支持下拉微调器、多种日期格式、日期限制以及丰富的自定义选项。

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

当你需要实现以下需求时可使用本技能：

为WinUI桌面应用添加日期输入控件
实现带下拉日历微调器的日期选择器
限制日期只能在指定范围选择或屏蔽特定日期
支持多种日历系统（希伯来历、回历、波斯历等）
自定义日期展示和编辑格式
实现支持RTL的本地化日期选择器
创建适配触控的日期选择界面
通过自定义规则验证日期输入
自定义下拉框的外观和行为
处理日期选择事件和验证逻辑

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

SfDatePicker控件为WinUI 3桌面应用提供现代化的日期输入体验。它将可编辑文本框与下拉日期微调器结合，支持多种日期格式、日历类型和验证规则。

核心特性：

适配触控的下拉日期微调器界面
支持多种日期格式（展示格式和编辑格式）
日期范围限制（MinDate、MaxDate）
支持配置不可选日期来屏蔽特定日期
多种日历类型（公历、希伯来历、回历、波斯历等）
本地化和RTL支持
掩码编辑和自由编辑两种模式
可自定义下拉UI和微调器单元格
内置验证和占位水印文本
支持XAML和C#两种配置方式

包名：

Syncfusion.Editors.WinUI

命名空间：

Syncfusion.UI.Xaml.Editors

控件名：

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)

📄 阅读： references/getting-started.md

从这里开始了解初始化配置和基础用法：

安装Syncfusion.Editors.WinUI包
在XAML和C#代码中添加SfDatePicker
设置和获取选中日期（SelectedDate属性）
从下拉框交互选择日期
启用空值支持（AllowNull属性）
添加占位文本（水印）
配置表头和描述信息
自定义表头模板
处理日期变更事件（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

📄 阅读： references/date-restriction.md

学习如何限制和验证日期选择：

设置最小和最大日期范围（MinDate、MaxDate）
通过BlackoutDates集合屏蔽特定日期
动态禁用日期（DateFieldItemPrepared事件）
用代码方式屏蔽周末日期
隐藏提交按钮实现即时选择
取消日期变更（SelectedDateChanging事件）
日期验证模式和错误处理

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)

📄 阅读： references/localization-formatting.md

配置日历类型、格式和本地化：

切换日历类型（CalendarIdentifier：希伯来历、回历、波斯历等）
为RTL语言设置流方向
通过Language属性实现本地化
自定义展示格式（DisplayDateFormat）
格式化日、月、年字段（DayFormat、MonthFormat、YearFormat）
带自动纠错的掩码编辑模式
自由编辑模式（EditMode）
显示/隐藏清除按钮（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)

📄 阅读： references/dropdown-customization.md

自定义下拉按钮和容器：

自定义下拉按钮UI（DropDownButtonTemplate）
隐藏下拉按钮（ShowDropDownButton）
修改下拉框对齐方式（DropDownPlacement）
用代码方式打开下拉框（IsOpen属性）
设置下拉框高度（DropDownHeight）
控制可见项数量（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

📄 阅读： references/dropdown-header-customization.md

配置下拉框表头区域：

在下拉框表头添加提示信息（DropDownHeader）
显示/隐藏下拉框表头（ShowDropDownHeader）
自定义表头UI（DropDownHeaderTemplate）
隐藏列头（ShowColumnHeaders）
表头布局模式

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

📄 阅读： references/spinner-customization.md

自定义日期微调器单元格和列：

设置单元格尺寸（ItemWidth、ItemHeight）
限制单元格宽度（MinItemWidth、MaxItemWidth）
为微调器单元格设置样式（ItemContainerStyle）
自定义单元格模板（ItemTemplate）
条件化设置单元格外观（ItemTemplateSelector）
自定义列（DateFieldPrepared事件）
格式化单个日期字段
启用微调器日期循环滚动

Quick Start Example

快速入门示例

Basic DatePicker Setup

基础DatePicker配置

XAML:

xml

<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#:

csharp

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

XAML:

xml

<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#:

csharp

using Syncfusion.UI.Xaml.Editors;

namespace DatePickerDemo
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
            
            // 创建Date Picker控件实例
            SfDatePicker sfDatePicker = new SfDatePicker();
            this.Content = sfDatePicker;
        }
    }
}

Common Patterns

常用实现模式

Pattern 1: Date Range Restriction

模式1：日期范围限制

xml

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

xml

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

Pattern 2: Blocking Specific Dates

模式2：屏蔽特定日期

csharp

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

xml

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

csharp

// 在ViewModel或代码后置中
public DateTimeOffsetCollection BlockedDates { get; set; }

public void InitializeBlockedDates()
{
    BlockedDates = new DateTimeOffsetCollection();
    BlockedDates.Add(new DateTimeOffset(new DateTime(2026, 12, 25))); // 圣诞节
    BlockedDates.Add(new DateTimeOffset(new DateTime(2026, 1, 1)));   // 新年
}

xml

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

Pattern 3: Custom Date Format

模式3：自定义日期格式

xml

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

xml

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

Pattern 4: Localized DatePicker with Calendar Type

模式4：带日历类型的本地化DatePicker

xml

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

xml

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

Pattern 5: Null Value Support

模式5：空值支持

xml

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

xml

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

Pattern 6: Immediate Selection (No Submit Button)

模式6：即时选择（无提交按钮）

xml

<editors:SfDatePicker 
    ShowSubmitButtons="False" />

xml

<editors:SfDatePicker 
    ShowSubmitButtons="False" />

Key Properties Reference

核心属性参考

Date Selection

日期选择

Property	Type	Description
`SelectedDate`	`DateTimeOffset?`	Gets or sets the selected date
`AllowNull`	`bool`	Allows null value selection

属性	类型	描述
`SelectedDate`	`DateTimeOffset?`	获取或设置选中的日期
`AllowNull`	`bool`	是否允许选择空值

Date Restriction

日期限制

Property	Type	Description
`MinDate`	`DateTimeOffset`	Minimum selectable date (default: 1/1/1921)
`MaxDate`	`DateTimeOffset`	Maximum selectable date (default: 12/31/2121)
`BlackoutDates`	`DateTimeOffsetCollection`	Collection of blocked dates

属性	类型	描述
`MinDate`	`DateTimeOffset`	最小可选日期（默认值：1/1/1921）
`MaxDate`	`DateTimeOffset`	最大可选日期（默认值：12/31/2121）
`BlackoutDates`	`DateTimeOffsetCollection`	被屏蔽的日期集合

Formatting

格式化

Property	Type	Description
`DisplayDateFormat`	`string`	Display format in editor (default: "d")
`DayFormat`	`string`	Day field format in spinner
`MonthFormat`	`string`	Month field format in spinner
`YearFormat`	`string`	Year field format in spinner

属性	类型	描述
`DisplayDateFormat`	`string`	编辑器中的展示格式（默认值："d"）
`DayFormat`	`string`	微调器中日字段的格式
`MonthFormat`	`string`	微调器中月字段的格式
`YearFormat`	`string`	微调器中年字段的格式

Localization

本地化

Property	Type	Description
`CalendarIdentifier`	`string`	Calendar type (Gregorian, Hebrew, Hijri, etc.)
`Language`	`string`	Language/culture for localization

属性	类型	描述
`CalendarIdentifier`	`string`	日历类型（公历、希伯来历、回历等）
`Language`	`string`	本地化使用的语言/文化

Dropdown Configuration

下拉框配置

Property	Type	Description
`DropDownHeader`	`object`	Header content in dropdown
`ShowDropDownHeader`	`bool`	Shows/hides dropdown header
`ShowColumnHeaders`	`bool`	Shows/hides spinner column headers
`ShowDropDownButton`	`bool`	Shows/hides dropdown button
`IsOpen`	`bool`	Opens/closes dropdown programmatically
`DropDownHeight`	`double`	Height of dropdown spinner
`VisibleItemsCount`	`int`	Number of visible items in spinner

属性	类型	描述
`DropDownHeader`	`object`	下拉框中的表头内容
`ShowDropDownHeader`	`bool`	显示/隐藏下拉框表头
`ShowColumnHeaders`	`bool`	显示/隐藏微调器列头
`ShowDropDownButton`	`bool`	显示/隐藏下拉按钮
`IsOpen`	`bool`	通过代码控制下拉框展开/收起
`DropDownHeight`	`double`	下拉微调器的高度
`VisibleItemsCount`	`int`	微调器中可见项的数量

Spinner Item Sizing

微调器项尺寸

Property	Type	Description
`ItemWidth`	`double`	Width of spinner cells (default: 80)
`ItemHeight`	`double`	Height of spinner cells (default: 40)
`MinItemWidth`	`double`	Minimum cell width
`MaxItemWidth`	`double`	Maximum cell width

属性	类型	描述
`ItemWidth`	`double`	微调器单元格宽度（默认值：80）
`ItemHeight`	`double`	微调器单元格高度（默认值：40）
`MinItemWidth`	`double`	单元格最小宽度
`MaxItemWidth`	`double`	单元格最大宽度

UI Customization

UI自定义

Property	Type	Description
`PlaceholderText`	`string`	Watermark text when no date selected
`Header`	`object`	Header content above control
`Description`	`object`	Description text below control
`ItemTemplate`	`DataTemplate`	Template for spinner cells
`ItemTemplateSelector`	`DataTemplateSelector`	Conditional cell templates
`ItemContainerStyle`	`Style`	Style for spinner cells
`ShowClearButton`	`bool`	Shows/hides clear button in editor
`ShowSubmitButtons`	`bool`	Shows/hides OK/Cancel buttons

属性	类型	描述
`PlaceholderText`	`string`	未选中日期时的水印文本
`Header`	`object`	控件上方的表头内容
`Description`	`object`	控件下方的描述文本
`ItemTemplate`	`DataTemplate`	微调器单元格的模板
`ItemTemplateSelector`	`DataTemplateSelector`	条件化单元格模板
`ItemContainerStyle`	`Style`	微调器单元格的样式
`ShowClearButton`	`bool`	显示/隐藏编辑器中的清除按钮
`ShowSubmitButtons`	`bool`	显示/隐藏确定/取消按钮

Editing

编辑

Property	Type	Description
`EditMode`	`DateTimeEditMode`	Mask or Normal editing mode

属性	类型	描述
`EditMode`	`DateTimeEditMode`	掩码编辑或普通编辑模式

Events

事件

Event	Description
`SelectedDateChanged`	Fires when selected date changes
`SelectedDateChanging`	Fires before date changes (cancelable)
`DateFieldItemPrepared`	Fires for each spinner item (for customization)
`DateFieldPrepared`	Fires for each spinner column (for customization)

事件	描述
`SelectedDateChanged`	选中日期变更时触发
`SelectedDateChanging`	日期变更前触发（可取消）
`DateFieldItemPrepared`	每个微调器项生成时触发（用于自定义）
`DateFieldPrepared`	每个微调器列生成时触发（用于自定义）

Common Use Cases

常见使用场景

Use Case 1: Appointment Scheduler

场景1：预约调度器

Date picker for selecting appointment dates with working hours only:

csharp

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

仅支持选择工作日的预约日期选择器：

csharp

// 屏蔽周末，仅允许选择工作日
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

场景2：预订系统

Date picker with blackout dates for unavailable dates:

csharp

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

标记不可用日期的日期选择器：

csharp

// 将已预订的日期标记为不可用
var bookedDates = GetBookedDatesFromDatabase();
datePicker.BlackoutDates = new DateTimeOffsetCollection();
foreach (var date in bookedDates)
{
    datePicker.BlackoutDates.Add(new DateTimeOffset(date));
}

Use Case 3: Birth Date Entry

场景3：出生日期输入

Date picker for entering historical dates:

xml

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

用于选择历史日期的日期选择器：

xml

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

Use Case 4: Multi-Language Application

场景4：多语言应用

Localized date picker with automatic RTL detection:

csharp

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

自动适配RTL的本地化日期选择器：

csharp

// 根据用户的区域设置配置
datePicker.Language = currentUser.PreferredLanguage;
datePicker.CalendarIdentifier = currentUser.CalendarType;

Use Case 5: Custom Branded UI

场景5：自定义品牌UI

Date picker with custom colors and icons:

xml

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

自定义颜色和图标的日期选择器：

xml

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

NuGet包： Syncfusion.Editors.WinUI
官方文档： WinUI DatePicker Docs
GitHub示例： SyncfusionExamples/syncfusion-winui-tools-datepicker-examples

下一步： 根据你的实现需求选择上方的文档模块，或者从入门指南开始学习基础配置。