syncfusion-winui-date-picker

WinUI 日期选择器（SfDatePicker）

关于实现 Syncfusion WinUI DatePicker 控件的综合指南——这是一款直观、触控友好的日期选择控件，支持下拉式滚轮、多种日期格式、日期限制和丰富的自定义选项。

何时使用此技能

在以下情况下使用此技能：

• 向 WinUI 桌面应用程序添加日期输入控件
• 实现带下拉日历滚轮的日期选择器
• 将日期选择限制在特定范围内，或屏蔽某些日期
• 支持多种日历系统（Hebrew、Hijri、Persian 等）
• 自定义日期显示格式和编辑格式
• 实现支持 RTL 的本地化日期选择器
• 创建触控友好的日期选择界面
• 使用自定义规则验证日期输入
• 自定义下拉菜单的外观和行为
• 处理日期选择事件和验证

组件概览

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

主要特点：

• 触控友好的下拉式日期滚轮界面
• 支持多种日期格式（显示格式和编辑格式）
• 日期范围限制（MinDate、MaxDate）
• 用于屏蔽特定日期的黑名单日期
• 多种日历类型（Gregorian、Hebrew、Hijri、Persian 等）
• 支持本地化和 RTL
• 支持掩码和自由格式编辑模式
• 可自定义下拉菜单 UI 和滚轮单元格
• 内置验证和水印文本
• 支持 XAML 和 C# 配置

包： Syncfusion.Editors.WinUI
命名空间： Syncfusion.UI.Xaml.Editors
控件： SfDatePicker

文档与导航指南

入门

📄 阅读： references/getting-started.md

从这里开始，了解初始设置和基本用法：

• 安装 Syncfusion.Editors.WinUI 包
• 在 XAML 和 C# 代码中添加 SfDatePicker
• 设置和获取选定日期（SelectedDate 属性）
• 从下拉菜单中交互式选择日期
• 启用 null 值（AllowNull 属性）
• 添加占位文本（水印）
• 配置标题和说明
• 自定义标题模板
• 处理日期更改事件（SelectedDateChanged）

日期限制

📄 阅读： references/date-restriction.md

了解如何限制和验证日期选择：

• 设置最小和最大日期范围（MinDate、MaxDate）
• 使用 BlackoutDates 集合屏蔽特定日期
• 动态禁用日期（DateFieldItemPrepared 事件）
• 以编程方式屏蔽周末日期
• 隐藏提交按钮以立即选择
• 取消日期更改（SelectedDateChanging 事件）
• 日期验证模式和错误处理

本地化与格式设置

📄 阅读： references/localization-formatting.md

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

• 更改日历类型（CalendarIdentifier：Hebrew、Hijri、Persian 等）
• 为 RTL 语言设置流向
• 使用 Language 属性进行本地化
• 自定义显示格式（DisplayDateFormat）
• 设置日、月、年字段的格式（DayFormat、MonthFormat、YearFormat）
• 带自动修正功能的掩码编辑模式
• 自由格式编辑模式（EditMode）
• 显示/隐藏清除按钮（ShowClearButton）

下拉菜单自定义

📄 阅读： references/dropdown-customization.md

自定义下拉按钮和容器：

• 自定义下拉按钮 UI（DropDownButtonTemplate）
• 隐藏下拉按钮（ShowDropDownButton）
• 更改下拉菜单对齐方式（DropDownPlacement）
• 以编程方式打开下拉菜单（IsOpen 属性）
• 设置下拉菜单高度（DropDownHeight）
• 控制可见项数量（VisibleItemsCount）

下拉列表标题自定义

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

配置下拉列表标题区域：

• 在下拉列表标题中添加提示（DropDownHeader）
• 显示/隐藏下拉列表标题（ShowDropDownHeader）
• 自定义标题 UI（DropDownHeaderTemplate）
• 隐藏列标题（ShowColumnHeaders）
• 标题布局模式

微调器自定义

📄 阅读： references/spinner-customization.md

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

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

快速入门示例

基本 DatePicker 设置

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

常见模式

模式 1：限制日期范围

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

模式 2：屏蔽特定日期

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

模式 3：自定义日期格式

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

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

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

模式 5：支持空值

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

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

<editors:SfDatePicker 
    ShowSubmitButtons="False" />

关键属性参考

日期选择

属性	类型	说明
SelectedDate	DateTimeOffset?	获取或设置所选日期
AllowNull	bool	允许选择空值

日期限制

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

格式设置

属性	类型	说明
DisplayDateFormat	string	编辑器中的显示格式（默认值："d"）
DayFormat	string	微调器中的日期字段格式
MonthFormat	string	微调器中的月份字段格式
YearFormat	string	微调器中的年份字段格式

本地化

属性	类型	说明
CalendarIdentifier	string	日历类型（Gregorian、Hebrew、Hijri 等）
Language	string	本地化所用的语言/区域性

下拉列表配置

属性	类型	说明
DropDownHeader	object	下拉列表中的标题内容
ShowDropDownHeader	bool	显示/隐藏下拉列表标题
ShowColumnHeaders	bool	显示/隐藏微调器列标题
ShowDropDownButton	bool	显示/隐藏下拉列表按钮
IsOpen	bool	以编程方式打开/关闭下拉列表
DropDownHeight	double	下拉微调器的高度
VisibleItemsCount	int	微调器中可见项的数量

微调器项尺寸

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

UI 自定义

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

编辑

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

事件

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

常见用例

用例 1：预约日程

用于选择预约日期的日期选择器，仅显示工作时间：

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

用例 2：预订系统

带有不可用日期禁用设置的日期选择器：

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

用例 3：出生日期输入

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

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

用例 4：多语言应用

可自动检测 RTL 的本地化日期选择器：

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

用例 5：自定义品牌界面

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

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

其他资源

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

---

后续步骤： 根据实现需求选择上方的文档章节，或从入门指南开始了解基本设置。