syncfusion-winforms-calendar（同步融合 winforms 日历）

Implementing Calendars (SfCalendar)

This skill guides the implementation of Syncfusion's SfCalendar, a powerful calendar control for date selection with multiple views (Month, Year, Decade, Century), comprehensive customization options, and support for special dates, blackout dates, and date range restrictions.

When to Use This Skill

Use this skill when you need to:

• Add a calendar control for date selection in WinForms applications
• Implement date pickers with single or multiple date selection
• Build appointment or event date selectors
• Create date range selection interfaces
• Display calendars with Month, Year, Decade, and Century views
• Restrict date selection with minimum and maximum date ranges
• Highlight special dates with custom icons and descriptions
• Block specific dates from selection using blackout dates
• Customize calendar appearance with themes and cell styling
• Localize calendars for different cultures and languages
• Implement weekend and holiday highlighting
• Build scheduling interfaces with visual date indicators

Component Overview

Control: SfCalendar Namespace: Syncfusion.WinForms.Input Assemblies Required:

• Syncfusion.Core.WinForms.dll
• Syncfusion.SfInput.WinForms.dll
• Syncfusion.Shared.Base.dll

Key Capabilities

The SfCalendar provides comprehensive calendar functionality:

• Multiple Views: Month, Year, Decade, and Century views for quick date navigation
• Date Selection: Single date, multiple dates, or date range selection modes
• Date Restrictions: MinDate and MaxDate properties to limit selectable date ranges
• Special Dates: Highlight important dates with custom icons and descriptions
• Blackout Dates: Block specific dates from selection with distinct styling
• Appearance: Rich theming options, cell customization, and visual styles
• Globalization: Culture-based localization, first day of week, date formats
• Navigation: Easy navigation between views with Today and None buttons
• Accessibility: Touch, keyboard, and mouse support for various interaction modes

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and assembly requirements
• Adding SfCalendar via designer
• Adding SfCalendar via code
• Namespace imports and basic setup
• Setting initial date value
• Complete setup example

Date Selection

📄 Read: references/date-selection.md

• Single date selection mode
• Multiple date selection
• Date range selection
• MinDate and MaxDate restrictions
• Blackout dates (blocking specific dates)
• Special dates with icons and descriptions
• Selection changed events
• Programmatic date selection

Events

• SelectedDateChanged: Raised when the single SelectedDate property changes.
• SelectionChanged: Raised when the SelectedDates collection changes in multiple‑selection mode.

Views and Navigation

📄 Read: references/views-and-navigation.md

• Month view (default view)
• Year view for month selection
• Decade view for year selection
• Century view for decade selection
• Navigating between views
• Today button functionality
• None button for clearing selection
• Header customization

Appearance Customization

📄 Read: references/appearance-customization.md

• Visual styles and themes (Office2016, Metro, etc.)
• Cell customization and styling
• Cell templates for custom rendering
• Color customization (background, foreground, borders)
• Font customization
• Weekend cell highlighting
• Current date highlighting
• Border and padding settings

Globalization

📄 Read: references/globalization.md

• Culture and localization support
• Setting first day of week
• Date format customization
• Month and day name localization
• Right-to-left (RTL) support
• Culture-specific calendar systems

Quick Start Example

Here's a basic calendar with date selection:

C#:

using Syncfusion.WinForms.Input;
using System;
using System.Windows.Forms;

public class CalendarForm : Form
{
    private SfCalendar calendar;
    private Label lblSelected;

    public CalendarForm()
    {
        // Create calendar
        calendar = new SfCalendar
        {
            Location = new Point(20, 20),
            Size = new Size(350, 300)
        };

        // Handle selection change
        calendar.SelectedDateChanged += Calendar_SelectedDateChanged;

        // Create label to show selected date
        lblSelected = new Label
        {
            Location = new Point(20, 330),
            Size = new Size(350, 30),
            Text = "No date selected"
        };

        this.Controls.Add(calendar);
        this.Controls.Add(lblSelected);
        this.Text = "Calendar Example";
        this.Size = new Size(400, 420);
    }

    private void Calendar_SelectedDateChanged(object sender, EventArgs e)
    {
        if (calendar.SelectedDate.HasValue)
        {
            lblSelected.Text = $"Selected: {calendar.SelectedDate.Value:D}";
        }
    }
}

VB.NET:

Imports Syncfusion.WinForms.Input
Imports System
Imports System.Windows.Forms

Public Class CalendarForm
    Inherits Form

    Private calendar As SfCalendar
    Private lblSelected As Label

    Public Sub New()
        ' Create calendar
        calendar = New SfCalendar With {
            .Location = New Point(20, 20),
            .Size = New Size(350, 300)
        }

        ' Handle selection change
        AddHandler calendar.SelectedDateChanged, AddressOf Calendar_SelectedDateChanged

        ' Create label to show selected date
        lblSelected = New Label With {
            .Location = New Point(20, 330),
            .Size = New Size(350, 30),
            .Text = "No date selected"
        }

        Me.Controls.Add(calendar)
        Me.Controls.Add(lblSelected)
        Me.Text = "Calendar Example"
        Me.Size = New Size(400, 420)
    End Sub

    Private Sub Calendar_SelectedDateChanged(sender As Object, e As EventArgs)
        If calendar.SelectedDate.HasValue Then
            lblSelected.Text = $"Selected: {calendar.SelectedDate.Value:D}"
        End If
    End Sub
End Class

Common Patterns

Pattern 1: Date Picker with Range Restrictions

Limit selectable dates to a specific range:

C#:

SfCalendar calendar = new SfCalendar();

// Restrict to future dates only (starting from today)
calendar.MinDate = DateTime.Today;
calendar.MaxDate = DateTime.Today.AddMonths(6);

// Set initial date
calendar.SelectedDate = DateTime.Today;

Pattern 2: Appointment Selector with Special Dates

Highlight appointments or special dates:

C#:

SfCalendar calendar = new SfCalendar();

// Add special dates (appointments, holidays, etc.)
calendar.SpecialDates.Add(new SpecialDate
{
    Date = new DateTime(2026, 3, 25),
    Description = "Team Meeting",
    IconImage = Properties.Resources.MeetingIcon
});

calendar.SpecialDates.Add(new SpecialDate
{
    Date = new DateTime(2026, 3, 28),
    Description = "Project Deadline",
    IconImage = Properties.Resources.DeadlineIcon
});

Pattern 3: Multi-Select Calendar

Allow selecting multiple dates:

C#:

SfCalendar calendar = new SfCalendar();

// Enable multiple selection
calendar.AllowMultipleSelection = true;

// Get selected dates
calendar.SelectionChanged += (s, e) =>
{
    var dates = calendar.SelectedDates;
    MessageBox.Show($"Selected {dates.Count} dates");
};

Key Properties

Common Use Cases

1. Date Picker: Single date selection for forms and input dialogs
2. Appointment Scheduler: Select dates for appointments with special date highlighting
3. Date Range Selector: Select start and end dates for reports or bookings
4. Holiday Calendar: Display holidays and special events with custom icons
5. Availability Calendar: Block unavailable dates using blackout dates for booking systems
6. Multi-Date Selector: Select multiple dates for batch operations or recurring events
7. Localized Calendar: Display calendars in different languages and cultures for global applications

Next Steps

Start with Getting Started to install and configure the SfCalendar, then explore specific features through the navigation guide above based on your application requirements.