syncfusion-winui-calendar-date-picker

Syncfusion WinUI 日历日期选择器

在 WinUI 3 桌面应用程序中实现日历日期选择器控件的综合指南。SfCalendarDatePicker 提供直观、适合触控的界面，可通过下拉日历选择日期，并支持丰富的自定义选项。

何时使用此技能

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

• 在 WinUI 应用程序中实现带下拉日历的日期输入
• 添加通过可视日历界面选择日期的功能
• 使用最小日期/最大日期或不可选日期限制日期选择
• 自定义日历的外观和行为
• 支持多种日历系统（公历、希伯来历、回历等）
• 在日历中显示周数
• 实现月、年、十年和世纪视图之间的导航
• 为不同区域性创建本地化日期选择器
• 处理日期验证和选择事件
• 禁止选择特定日期（周末、节假日）

组件概述

SfCalendarDatePicker 控件将文本编辑器与下拉日历结合起来，让用户既可以键入日期，也可以从日历中选择日期。它支持多种日期格式、日历类型和丰富的自定义选项。

主要功能：

• 通过下拉日历或键盘输入选择日期
• 最小日期/最大日期限制
• 使用不可选日期防止选择特定日期
• 使用自定义逻辑动态禁用日期
• 支持多种日历系统（公历、希伯来历、回历等）
• 支持不同区域性和语言的本地化
• 根据可配置规则显示周数
• 视图导航（月、年、十年、世纪）
• 可自定义日期格式和显示方式
• 主题和模板自定义
• 适合触控的界面
• 内置验证和事件

文档与导航指南

入门

📄 阅读： references/getting-started.md

从这里开始进行初始实现。内容包括：

• 安装 Syncfusion.Calendar.WinUI NuGet 包
• 创建 WinUI 3 应用程序设置
• 基本 XAML 和 C# 实现
• 以编程方式和交互方式选择日期
• 使用 AllowNull 属性处理空值
• 设置标题和说明
• 水印文本（PlaceholderText）
• SelectedDateChanged 和 SelectedDateChanging 事件
• 编辑模式（Mask 与 Normal/自由格式编辑）
• 下拉按钮的可见性
• 提交按钮配置

日期选择与限制

📄 阅读： references/date-selection-restriction.md

了解如何控制用户可以选择哪些日期：

• 使用 SelectedDate 属性获取/设置日期
• 使用 MinDate 和 MaxDate 限制日期范围
• 使用 BlackoutDates 集合禁止选择特定日期
• 使用 CalendarItemPrepared 事件动态禁用日期
• 禁用周末或节假日
• 为特定日期自定义显示文本
• SelectionHighlightMode（Outline 或 Filled）
• SelectionShape（Circle 或 Rectangle）
• 验证模式和边缘情况

UI 自定义

📄 阅读： references/ui-customization.md

自定义视觉外观和行为：

• 使用 ShowClearButton 显示/隐藏清除按钮
• 使用 DropDownPlacement 设置对齐方式（Left、Right、Top、Bottom、Center）
• 使用 DropDownWidth 和 DropDownHeight 设置尺寸
• 使用 OutOfScopeVisibility 显示/隐藏前置和后置日期
• 使用 AttachedFlyout 和 DropDownFlyout 自定义项模板
• 使用 EventDataConverter 模式突出显示特殊日期
• 自定义主题键（颜色、字体、边框）
• 使用 ContentTemplate 设置 CalendarItem 样式
• 高级模板模式

本地化和格式设置

📄 阅读： references/localization-formatting.md

配置日历类型、语言和日期格式：

• CalendarIdentifier：用于不同的日历系统（Gregorian、Hebrew、Hijri、Korean、Taiwan、Thai、Persian、UmAlQura）
• Language 属性：用于按区域设置显示
• DisplayDateFormat：用于设置编辑器文本格式
• DayFormat、MonthFormat、DayOfWeekFormat：用于设置日历显示格式
• MonthHeaderFormat：用于自定义标题
• FirstDayOfWeek：用于设置一周的起始日
• NumberOfWeeksInView：用于控制可见周数
• DateTimeFormatter 模式

在视图之间导航

📄 阅读： references/navigation.md

控制视图模式和导航行为：

• DisplayMode 属性（Month、Year、Decade、Century）
• MinDisplayMode 和 MaxDisplayMode：用于限制视图范围
• 针对特定用例（例如信用卡有效期）的视图导航模式
• 导航键盘快捷键（Tab、方向键、Ctrl+方向键、PageUp/Down、Home/End）
• 鼠标交互模式
• 根据视图限制进行选择

周数

📄 阅读： references/week-numbers.md

显示和自定义周数：

• ShowWeekNumbers 属性：启用周数显示
• WeekNumberRule（FirstDay、FirstFourDayWeek、FirstFullWeek）
• WeekNumberFormat：使用前缀/后缀进行自定义格式设置
• WeekNumberTemplate：进行完全自定义
• WeekNameTemplate：自定义日名称
• CalendarItemTemplateSelector 的用法

快速入门示例

安装

安装 NuGet 包：

Install-Package Syncfusion.Calendar.WinUI

基本实现

XAML：

<Window
    xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    
    <Grid>
        <calendar:SfCalendarDatePicker 
            x:Name="calendarDatePicker"
            Header="Select Date"
            PlaceholderText="Choose a date"
            SelectedDate="{x:Bind ViewModel.SelectedDate, Mode=TwoWay}"
            MinDate="2024-01-01"
            MaxDate="2024-12-31"
            DisplayDateFormat="MM/dd/yyyy" />
    </Grid>
</Window>

C#：

using Syncfusion.UI.Xaml.Calendar;

// Create instance
SfCalendarDatePicker datePicker = new SfCalendarDatePicker();

// Configure properties
datePicker.Header = "Select Date";
datePicker.PlaceholderText = "Choose a date";
datePicker.SelectedDate = DateTimeOffset.Now;
datePicker.MinDate = new DateTimeOffset(new DateTime(2024, 1, 1));
datePicker.MaxDate = new DateTimeOffset(new DateTime(2024, 12, 31));
datePicker.DisplayDateFormat = "MM/dd/yyyy";

// Handle selection changed
datePicker.SelectedDateChanged += (s, e) =>
{
    var oldDate = e.OldDate;
    var newDate = e.NewDate;
    // Process date change
};

this.Content = datePicker;

常见模式

模式 1：日期范围限制

限制用户只能选择特定范围内的日期：

// Only allow dates in current year
datePicker.MinDate = new DateTimeOffset(new DateTime(DateTime.Now.Year, 1, 1));
datePicker.MaxDate = new DateTimeOffset(new DateTime(DateTime.Now.Year, 12, 31));

模式 2：屏蔽周末

禁止选择周末日期：

datePicker.CalendarItemPrepared += (s, 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:SfCalendarDatePicker 
    MinDisplayMode="Year"
    MaxDisplayMode="Decade"
    DisplayDateFormat="MM/yyyy" />

模式 4：本地化日期选择器

为特定区域设置创建日期选择器：

datePicker.CalendarIdentifier = "HebrewCalendar";
datePicker.Language = "he-IL";
datePicker.FirstDayOfWeek = DayOfWeek.Sunday;

主要属性一览

日期选择

• SelectedDate - 获取或设置当前选中的日期
• AllowNull - 未选择日期时允许使用 null 值

日期限制

• MinDate - 可选日期下限（默认值：1/1/1920）
• MaxDate - 可选日期上限（默认值：12/31/2120）
• BlackoutDates - 禁止选择的日期集合

显示和格式设置

• DisplayDateFormat - 编辑器显示格式字符串（默认值："d"）
• DayFormat - 日历中日期数字的格式
• MonthFormat - 月份名称的格式
• DayOfWeekFormat - 星期标题的格式
• MonthHeaderFormat - 月/年标题的格式

日历配置

• CalendarIdentifier - 日历系统（Gregorian、Hebrew、Hijri 等）
• FirstDayOfWeek - 一周的第一天（默认值：Sunday）
• NumberOfWeeksInView - 月视图中显示的周数（默认值：6）

导航和视图

• DisplayMode - 当前视图模式（Month、Year、Decade、Century）
• MinDisplayMode - 允许的最低视图模式
• MaxDisplayMode - 允许的最高视图模式

周数

• ShowWeekNumbers - 显示周数（默认值：false）
• WeekNumberRule - 年中第一周的规则（FirstDay、FirstFourDayWeek、FirstFullWeek）
• WeekNumberFormat - 周数的格式字符串（默认值："#"）

UI 自定义

• PlaceholderText - 未选择日期时显示的水印文本
• OutOfScopeVisibility - 显示/隐藏范围外的日期（Enabled、Hidden）
• DropDownWidth - 下拉日历的宽度
• DropDownHeight - 下拉日历的高度
• SelectionHighlightMode - 高亮样式（Outline、Filled）
• SelectionShape - 选中形状（Circle、Rectangle）

附加资源

• Syncfusion WinUI Calendar Date Picker 文档
• GitHub 示例
• API 参考