syncfusion-winui-calendar（Synfusion WinUI 日历）

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.

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

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

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

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

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)

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

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

UI Customization

📄 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

Week Numbers

📄 Read: references/week-numbers.md

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

Quick Start Example

Here's a minimal working example to get started:

1. Add Namespace

XAML:

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

C#:

using Syncfusion.UI.Xaml.Calendar;

2. Create Basic 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>

3. Or Create Programmatically (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 a Date (Optional)

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

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

Common Patterns

Pattern 1: Single Date Selection

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

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

Pattern 2: Multiple Date Selection

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

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

Pattern 3: Date Range Selection

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

Pattern 4: Restrict Date Range

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

Pattern 5: Block Specific Dates

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

Pattern 6: Navigate to Specific Month

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

Pattern 7: Restrict Navigation to Year View

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

Pattern 8: ViewModel Data Binding

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}" />

Key Properties Reference

Selection Properties

Date Restriction Properties

Display and Navigation Properties

Localization and Formatting Properties

Week Number Properties

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.

International Date Picker

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

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.