syncfusion-winui-calendar

WinUI 日历（SfCalendar）

在 Windows 桌面应用程序中实现 Syncfusion WinUI Calendar（SfCalendar）控件以选择日期的综合指南。Calendar 控件支持单选、多选和日期范围选择，并提供丰富的自定义选项、不同视图之间的导航、日期限制和本地化功能。

何时使用此技能

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

• 创建日历控件，以便在 WinUI 桌面应用程序中选择日期
• 选择日期，支持单选、多选或范围模式
• 切换视图，在月、年、十年和世纪视图之间导航
• 限制日期，使用最小/最大日期和不可用日期
• 自定义 UI，使用模板、特殊日期突出显示和样式
• 本地化日历，以适配不同文化和语言
• 显示周数，并使用不同的计算规则
• 处理日期选择事件，用于验证或业务逻辑
• 实现无障碍日期选择器，并支持键盘导航
• 排查日历渲染或数据绑定问题

组件概述

SfCalendar 是 WinUI 桌面应用程序的主要日期选择控件，提供以下功能：

• **选择模式：**单选、多选、范围或无
• **视图导航：**月、年、十年和世纪视图
• **日期限制：**MinDate、MaxDate 和 BlackoutDates 集合
• **自定义：**单元格模板、特殊日期突出显示和主题集成
• **本地化：**支持多种日历类型和文化
• **周数：**可配置周数，支持 ISO 8601
• **键盘支持：**完整的键盘导航和无障碍支持
• **数据绑定：**支持 MVVM，可绑定 SelectedDate 和 SelectedDates

控件结构：

• 带有日期单元格的月视图（默认）
• 带有月份单元格的年视图
• 带有年份单元格的十年视图
• 带有十年单元格的世纪视图
• 用于导航和显示当前视图标题的标题栏
• 用于滚动的导航按钮

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 创建 WinUI 3 桌面应用程序
• 安装 Syncfusion.Calendar.WinUI NuGet 包
• 在 XAML 中添加 Calendar 控件
• 在 C# 中添加 Calendar 控件
• 基本日期选择
• 控件结构概述

选择功能

📄 阅读： references/selection.md

• 选择模式：无、单选、多选、范围
• SelectedDate 属性（单选）
• SelectedDates 集合（多选/范围选择）
• 以编程方式选择日期
• 选择更改事件
• 绑定选定日期

导航和显示

📄 阅读： references/navigation.md

• 显示模式：月、年、十年、世纪
• 在视图之间导航
• 使用 SetDisplayDate 方法将日期显示在视图中
• 最小/最大显示模式限制
• 根据视图限制进行选择
• 导航方向（垂直/水平滚动）

日期限制

📄 阅读： references/date-restrictions.md

• MinDate 和 MaxDate 属性
• 限制可选日期范围
• BlackoutDates 集合
• 禁止选择特定日期
• 验证日期选择
• 设置禁用日期的样式

本地化和格式设置

📄 阅读： references/localization-formatting.md

• 文化和语言支持
• 使用 FormatString 设置自定义日期格式
• 星期和月份的缩写名称
• RTL（从右到左）支持
• FlowDirection 属性
• 日期格式模式

UI 自定义

📄 阅读： references/customization.md

• 单元格模板（DataTemplate）
• 使用图标突出显示特殊日期
• 自定义单元格样式
• 标题栏自定义
• 背景色和前景色
• 边框和外观自定义
• 主题集成

周数

📄 阅读：references/week-numbers.md

• ShowWeekNumbers 属性
• WeekNumberRule 选项
• 周数格式
• FirstDay、FirstFourDayWeek、FirstFullWeek 规则
• 特定区域设置的周数计算

快速入门示例

下面是一个可供入门的最简可运行示例：

1. 添加命名空间

XAML：

<Window xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">

C#：

using Syncfusion.UI.Xaml.Calendar;

2. 创建基本日历（XAML）

<Window
    x:Class="CalendarApp.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    
    <Grid>
        <calendar:SfCalendar x:Name="sfCalendar" />
    </Grid>
</Window>

3. 或以编程方式创建（C#）

using Syncfusion.UI.Xaml.Calendar;

namespace CalendarApp
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
            
            // Create calendar programmatically
            SfCalendar sfCalendar = new SfCalendar();
            this.Content = sfCalendar;
        }
    }
}

4. 选择日期（可选）

// Select today's date
sfCalendar.SelectedDate = DateTimeOffset.Now;

// Or select a specific date
sfCalendar.SelectedDate = new DateTimeOffset(new DateTime(2026, 3, 22));

常见模式

模式 1：选择单个日期

<calendar:SfCalendar 
    x:Name="calendar"
    SelectionMode="Single"
    SelectedDate="{x:Bind ViewModel.SelectedDate, Mode=TwoWay}" />

// Access selected date
DateTimeOffset? selected = calendar.SelectedDate;

模式 2：选择多个日期

<calendar:SfCalendar 
    x:Name="calendar"
    SelectionMode="Multiple"
    SelectedDates="{x:Bind ViewModel.SelectedDates, Mode=TwoWay}" />

// Access multiple selected dates
DateTimeOffsetCollection selectedDates = calendar.SelectedDates;

模式 3：选择日期范围

<calendar:SfCalendar 
    x:Name="calendar"
    SelectionMode="Range" />

模式 4：限制日期范围

<calendar:SfCalendar 
    x:Name="calendar"
    MinDate="2026-01-01"
    MaxDate="2026-12-31" />

// Set date restrictions in code
calendar.MinDate = new DateTimeOffset(new DateTime(2026, 1, 1));
calendar.MaxDate = new DateTimeOffset(new DateTime(2026, 12, 31));

模式 5：屏蔽特定日期

// Create blackout dates collection
DateTimeOffsetCollection blackoutDates = new DateTimeOffsetCollection();
blackoutDates.Add(new DateTimeOffset(new DateTime(2026, 3, 25))); // Holiday
blackoutDates.Add(new DateTimeOffset(new DateTime(2026, 12, 25))); // Christmas

calendar.BlackoutDates = blackoutDates;

模式 6：导航到指定月份

// Navigate to a specific date's month
calendar.SetDisplayDate(new DateTimeOffset(new DateTime(2026, 6, 15)));

模式 7：将导航限制为年份视图

<calendar:SfCalendar 
    x:Name="calendar"
    MinDisplayMode="Month"
    MaxDisplayMode="Year" />

模式 8：ViewModel 数据绑定

public class CalendarViewModel : INotifyPropertyChanged
{
    private DateTimeOffset? selectedDate;
    
    public DateTimeOffset? SelectedDate
    {
        get => selectedDate;
        set
        {
            selectedDate = value;
            OnPropertyChanged(nameof(SelectedDate));
        }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

<calendar:SfCalendar 
    SelectedDate="{x:Bind ViewModel.SelectedDate, Mode=TwoWay}" />

关键属性参考

选择属性

属性	类型	说明
SelectedDate	DateTimeOffset?	获取或设置选中的日期（单选模式）
SelectedDates	DateTimeOffsetCollection	获取或设置选中日期的集合（多选／范围模式）
SelectedRange	DateTimeOffsetRange	当 SelectionMode 为 Range 时，获取选中的日期范围
SelectionMode	CalendarSelectionMode	日期选择模式：None、Single、Multiple、Range
SelectionHighlightMode	SelectionHighlightMode	选中日期的突出显示样式：Outline、Filled
SelectionShape	SelectionShape	选择指示器的形状：Circle、Rectangle

日期限制属性

属性	类型	说明
MinDate	DateTimeOffset	最早可选日期（默认值：1/1/1920）
MaxDate	DateTimeOffset	最晚可选日期（默认值：12/31/2120）
BlackoutDates	DateTimeOffsetCollection	不可选择（已屏蔽）日期的集合

显示和导航属性

属性	类型	说明
DisplayMode	CalendarDisplayMode	当前视图：Month、Year、Decade、Century
MinDisplayMode	CalendarDisplayMode	用户可导航到的最低视图级别
MaxDisplayMode	CalendarDisplayMode	用户可导航到的最高视图级别
NavigationDirection	CalendarNavigationDirection	视图内的滚动方向：Vertical、Horizontal
OutOfScopeVisibility	OutOfScopeVisibility	显示／隐藏相邻月份的日期：Enabled、Hidden
HeaderInfo	object	日历的自定义标题内容

本地化和格式属性

属性	类型	说明
CalendarIdentifier	string	日历系统类型：GregorianCalendar、HijriCalendar、HebrewCalendar 等
FirstDayOfWeek	FirstDayOfWeek	一周的第一天：Sunday、Monday、Tuesday 等
DayFormat	string	日期数字的格式模式（例如，“{day.integer(2)}”）
MonthFormat	string	月份名称的格式模式（例如，“{month.full}”）
DayOfWeekFormat	string	星期标题的格式模式（例如，“{dayofweek.abbreviated(3)}”）
MonthHeaderFormat	string	月／年标题的格式模式（例如，“{month.full} {year.full}”）
NumberOfWeeksInView	int	月视图中显示的周行数（默认值：6）

周数属性

属性	类型	说明
ShowWeekNumbers	bool	显示周数列（默认值：false）
WeekNumberRule	CalendarWeekRule	周数计算规则：FirstDay、FirstFourDayWeek、FirstFullWeek
WeekNumberFormat	string	周数格式（使用 # 作为占位符，例如，“W #”）

常见用例

活动日程安排应用

创建活动日程安排界面，让用户为预约、会议或提醒选择单个日期，并限制可选的未来日期及筛选工作日。

休假申请系统

构建休假管理系统，支持选择多个日期、设置公司节假日等不可选日期，并选择连续休假日期范围。

预约日历

实现预约系统，支持动态日期可用性、将不可用时段设为不可选日期，并通过 ItemPrepared 事件实时检查可用性。

国际化日期选择器

开发多语言应用，提供本地化日历，支持不同日历类型（Hijri、Hebrew、Persian）、从右向左书写的语言以及特定文化的格式。

日期范围筛选

创建数据筛选界面，让用户为报告、分析仪表板或交易查询选择日期范围，并设置最小/最大日期边界。

信用卡到期日期选择器

实现仅选择月份/年份的选择器，仅允许导航至 Year 和 Decade 视图，以选择信用卡到期日期。

---

后续步骤： 根据要实现的内容阅读上述参考文档。首先阅读 getting-started.md 进行初始设置，然后按需了解具体功能。