syncfusion-winui-calendar

用途

本技能用于在 WinUI 桌面应用中实现 Syncfusion WinUI Calendar（SfCalendar）日期选择控件。适用于构建日期选择器、日程安排、预约、假期申请、日期范围筛选等需要日期选择的界面。

主要能力

选择模式：None、Single、Multiple、Range。
视图导航：月、年、十年、世纪视图之间切换。
日期限制：MinDate、MaxDate 以及 BlackoutDates 集合。
定制：单元格模板、特殊日期高亮、主题集成。
本地化：支持多种日历类型与文化。
周数：可配置周编号规则，支持 ISO 8601。
键盘支持：完整的键盘导航与无障碍访问。
数据绑定：支持 MVVM，可绑定 SelectedDate 与 SelectedDates。

控件结构包括：月视图（日单元格，默认）、年视图（月单元格）、十年视图（年单元格）、世纪视图（十年单元格）、导航与当前视图标题的头部、滚动导航按钮。

使用方式

入门

创建 WinUI 3 桌面应用。
安装 Syncfusion.Calendar.WinUI NuGet 包。
在 XAML 或 C# 中添加 Calendar 控件。

XAML 命名空间：

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

C# 命名空间：

using Syncfusion.UI.Xaml.Calendar;

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>

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

选择日期：

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

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

常用模式

单选：

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

DateTimeOffset? selected = calendar.SelectedDate;

多选：

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

DateTimeOffsetCollection selectedDates = calendar.SelectedDates;

范围选择：

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

限制日期范围：

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

calendar.MinDate = new DateTimeOffset(new DateTime(2026, 1, 1));
calendar.MaxDate = new DateTimeOffset(new DateTime(2026, 12, 31));

屏蔽特定日期：

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;

导航到指定月份：

calendar.SetDisplayDate(new DateTimeOffset(new DateTime(2026, 6, 15)));

限制导航到年视图：

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

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）、RTL 语言和文化特定格式。
日期范围筛选：为报表、分析仪表板或交易查询选择日期范围，带最小/最大日期边界。
信用卡有效期选择器：通过仅限制导航到年和十年视图，实现仅月/年选择器。

限制

资料未提供关于性能上限、并发限制、授权许可、价格或平台版本兼容性的具体说明，暂未提供。