syncfusion-winui-calendar-date-picker
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSyncfusion WinUI Calendar Date Picker
Syncfusion WinUI 日历日期选择器
Comprehensive guide for implementing the Calendar Date Picker control in WinUI 3 desktop applications. The provides an intuitive, touch-friendly interface for selecting dates from a drop-down calendar with extensive customization options.
SfCalendarDatePicker本指南全面介绍如何在WinUI 3桌面应用中实现日历日期选择器控件。 提供了直观、适配触屏操作的界面，用户可从下拉日历中选择日期，同时支持丰富的自定义选项。
SfCalendarDatePickerWhen to Use This Skill
何时使用本技能
Use this skill when you need to:
- Implement date input with calendar drop-down in WinUI applications
- Add date selection with visual calendar interface
- Restrict date selection using min/max dates or blackout dates
- Customize calendar appearance and behavior
- Support multiple calendar systems (Gregorian, Hebrew, Hijri, etc.)
- Display week numbers in calendar
- Implement navigation between month/year/decade/century views
- Create localized date pickers for different cultures
- Handle date validation and selection events
- Block specific dates (weekends, holidays) from selection
当你需要实现以下需求时可使用本技能：
- 在WinUI应用中实现带下拉日历的日期输入功能
- 新增带可视化日历界面的日期选择功能
- 通过最小/最大日期或禁用日期限制可选日期范围
- 自定义日历的外观和行为
- 支持多种日历系统（公历、希伯来历、回历等）
- 在日历中显示周数
- 实现月/年/十年/世纪视图之间的导航
- 为不同文化区域创建本地化日期选择器
- 处理日期校验和选择事件
- 阻止特定日期（周末、节假日）被选中
Component Overview
组件概览
The control combines a text editor with a drop-down calendar, allowing users to select dates either by typing or by choosing from the calendar. It supports various date formats, calendar types, and extensive customization options.
SfCalendarDatePickerKey Features:
- Date selection via drop-down calendar or keyboard input
- Min/max date restrictions
- Blackout dates to prevent specific date selection
- Dynamic date blocking with custom logic
- Multiple calendar systems support (Gregorian, Hebrew, Hijri, etc.)
- Localization for different cultures and languages
- Week number display with configurable rules
- View navigation (month, year, decade, century)
- Customizable date formats and display
- Theme and template customization
- Touch-friendly interface
- Built-in validation and events
SfCalendarDatePicker核心特性：
- 通过下拉日历或键盘输入选择日期
- 最小/最大日期限制
- 禁用日期设置，阻止特定日期被选中
- 支持通过自定义逻辑动态禁用日期
- 支持多种日历系统（公历、希伯来历、回历等）
- 适配不同文化和语言的本地化能力
- 周数显示，支持自定义周数计算规则
- 视图导航（月、年、十年、世纪）
- 可自定义的日期格式和显示效果
- 主题和模板自定义
- 适配触屏操作的界面
- 内置校验和事件机制
Documentation and Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
Start here for initial implementation. This covers:
- Installing the Syncfusion.Calendar.WinUI NuGet package
- Creating WinUI 3 application setup
- Basic XAML and C# implementation
- Programmatic and interactive date selection
- Null value handling with AllowNull property
- Header and description setup
- Watermark text (PlaceholderText)
- SelectedDateChanged and SelectedDateChanging events
- Edit modes (Mask vs Normal/free form editing)
- Drop-down button visibility
- Submit buttons configuration
📄 阅读： references/getting-started.md
从这里开始进行初始实现，内容涵盖：
- 安装Syncfusion.Calendar.WinUI NuGet包
- WinUI 3应用的初始化搭建
- 基础XAML和C#实现
- 程序化和交互性日期选择
- 通过AllowNull属性处理空值
- 头部和描述信息设置
- 水印文本（PlaceholderText）配置
- SelectedDateChanged和SelectedDateChanging事件
- 编辑模式（掩码编辑 vs 普通/自由编辑）
- 下拉按钮可见性设置
- 提交按钮配置
Date Selection and Restriction
日期选择与限制
📄 Read: references/date-selection-restriction.md
Learn how to control which dates users can select:
- SelectedDate property for getting/setting dates
- MinDate and MaxDate for date range restrictions
- BlackoutDates collection for blocking specific dates
- Dynamic date blocking using CalendarItemPrepared event
- Blocking weekend days or holidays
- Custom display text for specific dates
- SelectionHighlightMode (Outline vs Filled)
- SelectionShape (Circle vs Rectangle)
- Validation patterns and edge cases
📄 阅读： references/date-selection-restriction.md
学习如何控制用户可选择的日期范围：
- 通过SelectedDate属性获取/设置日期
- 通过MinDate和MaxDate限制可选日期范围
- 通过BlackoutDates集合禁用特定日期
- 使用CalendarItemPrepared事件动态禁用日期
- 禁用周末或节假日
- 为特定日期设置自定义显示文本
- SelectionHighlightMode（轮廓 vs 填充）
- SelectionShape（圆形 vs 矩形）
- 校验规则和边界场景处理
UI Customization
UI自定义
📄 Read: references/ui-customization.md
Customize the visual appearance and behavior:
- ShowClearButton to show/hide the clear button
- DropDownPlacement for alignment (Left, Right, Top, Bottom, Center)
- DropDownWidth and DropDownHeight for sizing
- OutOfScopeVisibility to show/hide leading and trailing dates
- Custom item templates using AttachedFlyout and DropDownFlyout
- EventDataConverter pattern for highlighting special dates
- Theme key customization (colors, fonts, borders)
- CalendarItem styling with ContentTemplate
- Advanced template patterns
📄 阅读： references/ui-customization.md
自定义视觉外观和行为：
- 通过ShowClearButton显示/隐藏清除按钮
- DropDownPlacement设置对齐方式（左、右、上、下、居中）
- DropDownWidth和DropDownHeight设置下拉框尺寸
- OutOfScopeVisibility设置显示/隐藏非当月日期
- 使用AttachedFlyout和DropDownFlyout自定义项模板
- 使用EventDataConverter模式高亮特殊日期
- 主题键自定义（颜色、字体、边框）
- 通过ContentTemplate自定义CalendarItem样式
- 高级模板用法
Localization and Formatting
本地化与格式化
📄 Read: references/localization-formatting.md
Configure calendar types, languages, and date formats:
- CalendarIdentifier for different calendar systems (Gregorian, Hebrew, Hijri, Korean, Taiwan, Thai, Persian, UmAlQura)
- Language property for culture-specific display
- DisplayDateFormat for editor text format
- DayFormat, MonthFormat, DayOfWeekFormat for calendar display
- MonthHeaderFormat for header customization
- FirstDayOfWeek to set week start day
- NumberOfWeeksInView to control visible weeks
- DateTimeFormatter patterns
📄 阅读： references/localization-formatting.md
配置日历类型、语言和日期格式：
- CalendarIdentifier设置不同日历系统（公历、希伯来历、回历、 Korean、台湾日历、泰历、波斯历、UmAlQura历）
- Language属性设置文化区域特定显示
- DisplayDateFormat设置编辑器文本格式
- DayFormat、MonthFormat、DayOfWeekFormat设置日历显示格式
- MonthHeaderFormat自定义头部格式
- FirstDayOfWeek设置每周起始日
- NumberOfWeeksInView控制可见周数
- DateTimeFormatter格式规则
Navigation Between Views
视图间导航
📄 Read: references/navigation.md
Control view modes and navigation behavior:
- DisplayMode property (Month, Year, Decade, Century)
- MinDisplayMode and MaxDisplayMode for view restrictions
- View navigation patterns for specific use cases (e.g., credit card expiry)
- Keyboard shortcuts for navigation (Tab, Arrow keys, Ctrl+Arrow, PageUp/Down, Home/End)
- Mouse interaction patterns
- Selection based on view restrictions
📄 阅读： references/navigation.md
控制视图模式和导航行为：
- DisplayMode属性（月、年、十年、世纪）
- MinDisplayMode和MaxDisplayMode限制视图范围
- 适配特定场景的视图导航模式（例如信用卡有效期选择）
- 导航快捷键（Tab、方向键、Ctrl+方向键、PageUp/PageDown、Home/End）
- 鼠标交互规则
- 基于视图限制的选择逻辑
Week Numbers
周数
📄 Read: references/week-numbers.md
Display and customize week numbers:
- ShowWeekNumbers property to enable week display
- WeekNumberRule (FirstDay, FirstFourDayWeek, FirstFullWeek)
- WeekNumberFormat for custom formatting with prefix/suffix
- WeekNumberTemplate for complete customization
- WeekNameTemplate for day name customization
- CalendarItemTemplateSelector usage
📄 阅读： references/week-numbers.md
显示和自定义周数：
- 通过ShowWeekNumbers属性启用周数显示
- WeekNumberRule（首日规则、首周四天规则、首整周规则）
- WeekNumberFormat自定义周数前后缀格式
- WeekNumberTemplate完全自定义周数显示
- WeekNameTemplate自定义星期名称显示
- CalendarItemTemplateSelector用法
Quick Start Example
快速入门示例
Installation
安装
Install the NuGet package:
powershell
Install-Package Syncfusion.Calendar.WinUI安装NuGet包：
powershell
Install-Package Syncfusion.Calendar.WinUIBasic Implementation
基础实现
XAML:
xml
<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#:
csharp
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;XAML：
xml
<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#：
csharp
using Syncfusion.UI.Xaml.Calendar;
// 创建实例
SfCalendarDatePicker datePicker = new SfCalendarDatePicker();
// 配置属性
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";
// 处理选择变更事件
datePicker.SelectedDateChanged += (s, e) =>
{
var oldDate = e.OldDate;
var newDate = e.NewDate;
// 处理日期变更
};
this.Content = datePicker;Common Patterns
常用场景
Pattern 1: Date Range Restriction
场景1：日期范围限制
Restrict users to select dates within a specific range:
csharp
// 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));限制用户只能选择特定范围内的日期：
csharp
// 仅允许选择当年的日期
datePicker.MinDate = new DateTimeOffset(new DateTime(DateTime.Now.Year, 1, 1));
datePicker.MaxDate = new DateTimeOffset(new DateTime(DateTime.Now.Year, 12, 31));Pattern 2: Block Weekend Days
场景2：禁用周末
Prevent selection of weekend days:
csharp
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;
}
};阻止用户选择周末日期：
csharp
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;
}
};Pattern 3: Credit Card Expiry Date Selection
场景3：信用卡有效期选择
Allow only month and year selection:
xml
<calendar:SfCalendarDatePicker
MinDisplayMode="Year"
MaxDisplayMode="Decade"
DisplayDateFormat="MM/yyyy" />仅允许选择月份和年份：
xml
<calendar:SfCalendarDatePicker
MinDisplayMode="Year"
MaxDisplayMode="Decade"
DisplayDateFormat="MM/yyyy" />Pattern 4: Localized Date Picker
场景4：本地化日期选择器
Create a date picker for a specific culture:
csharp
datePicker.CalendarIdentifier = "HebrewCalendar";
datePicker.Language = "he-IL";
datePicker.FirstDayOfWeek = DayOfWeek.Sunday;为特定文化区域创建日期选择器：
csharp
datePicker.CalendarIdentifier = "HebrewCalendar";
datePicker.Language = "he-IL";
datePicker.FirstDayOfWeek = DayOfWeek.Sunday;Key Properties at a Glance
核心属性速览
Date Selection
日期选择相关
- SelectedDate - Gets or sets the currently selected date
- AllowNull - Allows null value when no date is selected
- SelectedDate - 获取或设置当前选中的日期
- AllowNull - 允许未选择日期时为空值
Date Restrictions
日期限制相关
- MinDate - Minimum selectable date (default: 1/1/1920)
- MaxDate - Maximum selectable date (default: 12/31/2120)
- BlackoutDates - Collection of dates to block from selection
- MinDate - 最小可选日期（默认：1/1/1920）
- MaxDate - 最大可选日期（默认：12/31/2120）
- BlackoutDates - 禁止选择的日期集合
Display and Formatting
显示与格式化相关
- DisplayDateFormat - Format string for editor display (default: "d")
- DayFormat - Format for day numbers in calendar
- MonthFormat - Format for month names
- DayOfWeekFormat - Format for day-of-week headers
- MonthHeaderFormat - Format for month/year header
- DisplayDateFormat - 编辑器显示的格式字符串（默认："d"）
- DayFormat - 日历中日数字的格式
- MonthFormat - 月份名称的格式
- DayOfWeekFormat - 星期头部的格式
- MonthHeaderFormat - 月/年头部的格式
Calendar Configuration
日历配置相关
- CalendarIdentifier - Calendar system (Gregorian, Hebrew, Hijri, etc.)
- FirstDayOfWeek - First day of the week (default: Sunday)
- NumberOfWeeksInView - Number of weeks shown in month view (default: 6)
- CalendarIdentifier - 日历系统（公历、希伯来历、回历等）
- FirstDayOfWeek - 每周的起始日（默认：周日）
- NumberOfWeeksInView - 月视图中显示的周数（默认：6）
Navigation and Views
导航与视图相关
- DisplayMode - Current view mode (Month, Year, Decade, Century)
- MinDisplayMode - Minimum allowed view mode
- MaxDisplayMode - Maximum allowed view mode
- DisplayMode - 当前视图模式（月、年、十年、世纪）
- MinDisplayMode - 允许的最小视图模式
- MaxDisplayMode - 允许的最大视图模式
Week Numbers
周数相关
- ShowWeekNumbers - Displays week numbers (default: false)
- WeekNumberRule - Rule for first week of year (FirstDay, FirstFourDayWeek, FirstFullWeek)
- WeekNumberFormat - Format string for week numbers (default: "#")
- ShowWeekNumbers - 显示周数（默认：false）
- WeekNumberRule - 一年第一周的计算规则（首日、首周四天、首整周）
- WeekNumberFormat - 周数的格式字符串（默认："#"）
UI Customization
UI自定义相关
- PlaceholderText - Watermark text when no date is selected
- OutOfScopeVisibility - Show/hide out-of-scope dates (Enabled, Hidden)
- DropDownWidth - Width of drop-down calendar
- DropDownHeight - Height of drop-down calendar
- SelectionHighlightMode - Highlight style (Outline, Filled)
- SelectionShape - Selection shape (Circle, Rectangle)
- PlaceholderText - 未选择日期时的水印文本
- OutOfScopeVisibility - 显示/隐藏非当月日期（启用、隐藏）
- DropDownWidth - 下拉日历的宽度
- DropDownHeight - 下拉日历的高度
- SelectionHighlightMode - 选中高亮样式（轮廓、填充）
- SelectionShape - 选中区域形状（圆形、矩形）