syncfusion-winui-calendar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WinUI Calendar (SfCalendar)

Comprehensive guide for implementing the Syncfusion WinUI Calendar (SfCalendar) control for date selection in Windows desktop applications. The Calendar control supports single, multiple, and range date selection with extensive customization options, navigation between different views, date restrictions, and localization.

这是一份在Windows桌面应用中实现Syncfusion WinUI Calendar (SfCalendar)日期选择控件的全面指南。该日历控件支持单选、多选和范围日期选择，拥有丰富的自定义选项、多视图间导航、日期限制和本地化能力。

When to Use This Skill

什么时候使用该技能

Use this skill when you need to:

Create calendar controls for date selection in WinUI desktop applications
Select dates in single, multiple, or range modes
Navigate views between month, year, decade, and century
Restrict dates using min/max dates and blackout dates
Customize UI with templates, special date highlighting, and styling
Localize calendars for different cultures and languages
Display week numbers with various calculation rules
Handle date selection events for validation or business logic
Implement accessible date pickers with keyboard navigation
Troubleshoot calendar rendering or data binding issues

当你需要完成以下需求时可以使用本技能：

为WinUI桌面应用创建日历控件实现日期选择功能
实现单选、多选或范围模式的日期选择能力
实现月、年、十年、世纪视图间的导航切换
通过最小/最大日期和禁用日期限制可选日期范围
通过模板、特殊日期高亮和样式自定义UI
针对不同文化和语言本地化日历
按多种计算规则显示周数
处理日期选择事件用于校验或业务逻辑
实现支持键盘导航的无障碍日期选择器
排查日历渲染或数据绑定相关问题

Component Overview

组件概览

SfCalendar is the primary date selection control for WinUI desktop applications, offering:

Selection Modes: Single, Multiple, Range, or None
View Navigation: Month, Year, Decade, and Century views
Date Restrictions: MinDate, MaxDate, and BlackoutDates collections
Customization: Cell templates, special date highlighting, and theme integration
Localization: Support for multiple calendar types and cultures
Week Numbers: Configurable week numbering with ISO 8601 support
Keyboard Support: Full keyboard navigation and accessibility
Data Binding: MVVM-friendly with SelectedDate and SelectedDates binding

Control Structure:

Month view with day cells (default)
Year view with month cells
Decade view with year cells
Century view with decade cells
Header for navigation and current view title
Navigation buttons for scrolling

SfCalendar是WinUI桌面应用的核心日期选择控件，提供以下能力：

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

控件结构：

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

Documentation and Navigation Guide

文档和导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Creating a WinUI 3 desktop application
Installing Syncfusion.Calendar.WinUI NuGet package
Adding Calendar control in XAML
Adding Calendar control in C#
Basic date selection
Control structure overview

📄 阅读： references/getting-started.md

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

Selection Features

选择功能

📄 Read: references/selection.md

Selection modes: None, Single, Multiple, Range
SelectedDate property (single selection)
SelectedDates collection (multiple/range selection)
Programmatic date selection
Selection changed events
Data binding selected dates

📄 阅读： references/selection.md

选择模式：无、单选、多选、范围选择
SelectedDate属性（单选模式）
SelectedDates集合（多选/范围选择模式）
程序化日期选择
选择变更事件
选中日期的数据绑定

Navigation and Display

导航和显示

📄 Read: references/navigation.md

Display modes: Month, Year, Decade, Century
Navigating between views
SetDisplayDate method to bring dates into view
Min/Max display mode restrictions
Selection based on view restrictions
Navigation direction (vertical/horizontal scrolling)

📄 阅读： references/navigation.md

显示模式：月、年、十年、世纪
视图间导航
使用SetDisplayDate方法将指定日期纳入视图
最小/最大显示模式限制
基于视图限制的选择逻辑
导航方向（垂直/水平滚动）

Date Restrictions

日期限制

📄 Read: references/date-restrictions.md

MinDate and MaxDate properties
Restricting selectable date ranges
BlackoutDates collection
Blocking specific dates from selection
Validating date selection
Styling disabled dates

📄 阅读： references/date-restrictions.md

MinDate和MaxDate属性
限制可选日期范围
BlackoutDates集合
拦截特定日期使其不可选择
日期选择校验
禁用日期的样式设置

Localization and Formatting

本地化和格式化

📄 Read: references/localization-formatting.md

Culture and language support
FormatString for custom date formats
Abbreviated day and month names
RTL (Right-to-Left) support
FlowDirection property
Date formatting patterns

📄 阅读： references/localization-formatting.md

文化和语言支持
自定义日期格式的FormatString属性
缩写的日期和月份名称
RTL（从右到左）支持
FlowDirection属性
日期格式化规则

UI Customization

UI自定义

📄 Read: references/customization.md

Cell templates (DataTemplate)
Special date highlighting with icons
Custom cell styling
Header customization
Background and foreground colors
Border and appearance customization
Theme integration

📄 阅读： references/customization.md

单元格模板（DataTemplate）
带图标的特殊日期高亮
自定义单元格样式
头部自定义
背景和前景色设置
边框和外观自定义
主题集成

Week Numbers

周数

📄 Read: references/week-numbers.md

ShowWeekNumbers property
WeekNumberRule options
Week number formatting
FirstDay, FirstFourDayWeek, FirstFullWeek rules
Culture-specific week calculations

📄 阅读： references/week-numbers.md

ShowWeekNumbers属性
WeekNumberRule配置项
周数格式化
首日、首四日周、整周起始规则
适配文化的周数计算

Quick Start Example

快速开始示例

Here's a minimal working example to get started:

以下是最小可运行的入门示例：

1. Add Namespace

1. 添加命名空间

XAML:

xml

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

C#:

csharp

using Syncfusion.UI.Xaml.Calendar;

XAML：

xml

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

C#：

csharp

using Syncfusion.UI.Xaml.Calendar;

2. Create Basic Calendar (XAML)

2. 创建基础日历（XAML）

xml

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

xml

<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. Or Create Programmatically (C#)

3. 或通过代码创建（C#）

csharp

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

csharp

using Syncfusion.UI.Xaml.Calendar;

namespace CalendarApp
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
            
            // 程序化创建日历
            SfCalendar sfCalendar = new SfCalendar();
            this.Content = sfCalendar;
        }
    }
}

4. Select a Date (Optional)

4. 选中日期（可选）

csharp

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

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

csharp

// 选中今天的日期
sfCalendar.SelectedDate = DateTimeOffset.Now;

// 或选中指定日期
sfCalendar.SelectedDate = new DateTimeOffset(new DateTime(2026, 3, 22));

Common Patterns

常用模式

Pattern 1: Single Date Selection

模式1：单选日期

xml

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

csharp

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

xml

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

csharp

// 获取选中的日期
DateTimeOffset? selected = calendar.SelectedDate;

Pattern 2: Multiple Date Selection

模式2：多选日期

xml

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

csharp

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

xml

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

csharp

// 获取多个选中的日期
DateTimeOffsetCollection selectedDates = calendar.SelectedDates;

Pattern 3: Date Range Selection

模式3：日期范围选择

xml

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

xml

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

Pattern 4: Restrict Date Range

模式4：限制日期范围

xml

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

csharp

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

xml

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

csharp

// 代码中设置日期限制
calendar.MinDate = new DateTimeOffset(new DateTime(2026, 1, 1));
calendar.MaxDate = new DateTimeOffset(new DateTime(2026, 12, 31));

Pattern 5: Block Specific Dates

模式5：拦截特定日期

csharp

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

csharp

// 创建禁用日期集合
DateTimeOffsetCollection blackoutDates = new DateTimeOffsetCollection();
blackoutDates.Add(new DateTimeOffset(new DateTime(2026, 3, 25))); // 节假日
blackoutDates.Add(new DateTimeOffset(new DateTime(2026, 12, 25))); // 圣诞节

calendar.BlackoutDates = blackoutDates;

Pattern 6: Navigate to Specific Month

模式6：导航到指定月份

csharp

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

csharp

// 导航到指定日期所在的月份
calendar.SetDisplayDate(new DateTimeOffset(new DateTime(2026, 6, 15)));

Pattern 7: Restrict Navigation to Year View

模式7：限制仅可导航到年视图

xml

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

xml

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

Pattern 8: ViewModel Data Binding

模式8：ViewModel数据绑定

csharp

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

xml

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

csharp

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

xml

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

Key Properties Reference

核心属性参考

Selection Properties

选择相关属性

Property	Type	Description
`SelectedDate`	DateTimeOffset?	Gets or sets the selected date (single selection mode)
`SelectedDates`	DateTimeOffsetCollection	Gets or sets the collection of selected dates (multiple/range modes)
`SelectedRange`	DateTimeOffsetRange	Gets the selected date range when SelectionMode is Range
`SelectionMode`	CalendarSelectionMode	Date selection mode: None, Single, Multiple, Range
`SelectionHighlightMode`	SelectionHighlightMode	Highlight style for selected dates: Outline, Filled
`SelectionShape`	SelectionShape	Shape of selection indicator: Circle, Rectangle

属性	类型	描述
`SelectedDate`	DateTimeOffset?	获取或设置选中的日期（单选模式下生效）
`SelectedDates`	DateTimeOffsetCollection	获取或设置选中的日期集合（多选/范围模式下生效）
`SelectedRange`	DateTimeOffsetRange	获取选择模式为范围时的选中日期范围
`SelectionMode`	CalendarSelectionMode	日期选择模式：None（无）、Single（单选）、Multiple（多选）、Range（范围）
`SelectionHighlightMode`	SelectionHighlightMode	选中日期的高亮样式：Outline（描边）、Filled（填充）
`SelectionShape`	SelectionShape	选中指示器的形状：Circle（圆形）、Rectangle（矩形）

Date Restriction Properties

日期限制相关属性

Property	Type	Description
`MinDate`	DateTimeOffset	Minimum selectable date (default: 1/1/1920)
`MaxDate`	DateTimeOffset	Maximum selectable date (default: 12/31/2120)
`BlackoutDates`	DateTimeOffsetCollection	Collection of non-selectable (blocked) dates

属性	类型	描述
`MinDate`	DateTimeOffset	最小可选择日期（默认：1/1/1920）
`MaxDate`	DateTimeOffset	最大可选择日期（默认：12/31/2120）
`BlackoutDates`	DateTimeOffsetCollection	不可选择（拦截）的日期集合

Display and Navigation Properties

显示和导航相关属性

Property	Type	Description
`DisplayMode`	CalendarDisplayMode	Current view: Month, Year, Decade, Century
`MinDisplayMode`	CalendarDisplayMode	Minimum view level users can navigate to
`MaxDisplayMode`	CalendarDisplayMode	Maximum view level users can navigate to
`NavigationDirection`	CalendarNavigationDirection	Scroll direction within view: Vertical, Horizontal
`OutOfScopeVisibility`	OutOfScopeVisibility	Show/hide dates from adjacent months: Enabled, Hidden
`HeaderInfo`	object	Custom header content for the calendar

属性	类型	描述
`DisplayMode`	CalendarDisplayMode	当前视图：Month（月）、Year（年）、Decade（十年）、Century（世纪）
`MinDisplayMode`	CalendarDisplayMode	用户可导航到的最小视图层级
`MaxDisplayMode`	CalendarDisplayMode	用户可导航到的最大视图层级
`NavigationDirection`	CalendarNavigationDirection	视图内滚动方向：Vertical（垂直）、Horizontal（水平）
`OutOfScopeVisibility`	OutOfScopeVisibility	显示/隐藏相邻月份的日期：Enabled（显示）、Hidden（隐藏）
`HeaderInfo`	object	日历的自定义头部内容

Localization and Formatting Properties

本地化和格式化相关属性

Property	Type	Description
`CalendarIdentifier`	string	Calendar system type: GregorianCalendar, HijriCalendar, HebrewCalendar, etc.
`FirstDayOfWeek`	FirstDayOfWeek	First day of week: Sunday, Monday, Tuesday, etc.
`DayFormat`	string	Format pattern for day numbers (e.g., "{day.integer(2)}")
`MonthFormat`	string	Format pattern for month names (e.g., "{month.full}")
`DayOfWeekFormat`	string	Format pattern for day-of-week headers (e.g., "{dayofweek.abbreviated(3)}")
`MonthHeaderFormat`	string	Format pattern for month/year header (e.g., "{month.full} {year.full}")
`NumberOfWeeksInView`	int	Number of week rows displayed in month view (default: 6)

属性	类型	描述
`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）

Week Number Properties

周数相关属性

Property	Type	Description
`ShowWeekNumbers`	bool	Display week numbers column (default: false)
`WeekNumberRule`	CalendarWeekRule	Week calculation rule: FirstDay, FirstFourDayWeek, FirstFullWeek
`WeekNumberFormat`	string	Format for week numbers (use # as placeholder, e.g., "W #")

属性	类型	描述
`ShowWeekNumbers`	bool	是否显示周数列（默认：false）
`WeekNumberRule`	CalendarWeekRule	周数计算规则：FirstDay（首日）、FirstFourDayWeek（首四日周）、FirstFullWeek（首个整周）
`WeekNumberFormat`	string	周数的格式化规则（使用#作为占位符，例如："W #"）

Common Use Cases

常见使用场景

Event Scheduling Application

活动调度应用

Create event scheduling interfaces where users select single dates for appointments, meetings, or reminders with future date restrictions and business day filtering.

创建活动调度界面，用户可以选择单日期用于预约、会议或提醒，支持未来日期限制和工作日过滤。

Vacation Request System

休假申请系统

Build vacation management systems with multiple date selection, blackout dates for company holidays, and range selection for consecutive vacation days.

构建休假管理系统，支持多选日期、公司节假日禁用日期、连续休假的范围选择能力。

Appointment Booking Calendar

预约日历

Implement booking systems with dynamic date availability, blackout dates for unavailable slots, and real-time availability checking through ItemPrepared event.

实现预订系统，支持动态日期可用状态、不可用时段的禁用日期，通过ItemPrepared事件实现实时可用性校验。

International Date Picker

国际化日期选择器

Develop multi-language applications with localized calendars supporting different calendar types (Hijri, Hebrew, Persian), RTL languages, and culture-specific formatting.

开发多语言应用，提供本地化日历，支持不同日历类型（回历、希伯来历、波斯历）、RTL语言和文化适配格式化。

Date Range Filtering

日期范围筛选

Create data filtering interfaces where users select date ranges for reports, analytics dashboards, or transaction queries with min/max date boundaries.

创建数据筛选界面，用户可以选择日期范围用于生成报表、分析看板或交易查询，支持最小/最大日期边界限制。

Credit Card Expiry Selector

信用卡有效期选择器

Implement month/year-only selectors for credit card expiration dates by restricting navigation to Year and Decade views only.

Next Steps: Read the reference documentation above based on what you need to implement. Start with getting-started.md for initial setup, then explore specific features as needed.

通过限制仅可导航到年和十年视图，实现仅选择月/年的信用卡有效期选择器。

后续步骤： 根据你需要实现的功能阅读上方的参考文档。初始搭建请先阅读getting-started.md，之后按需探索特定功能。