syncfusion-winforms-calendar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Calendars (SfCalendar)

实现日历(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.
本指南将指导你实现Syncfusion的SfCalendar控件,这是一款功能强大的日期选择日历控件,支持多视图(月、年、十年、世纪)、全面的自定义选项,同时支持特殊日期、禁用日期和日期范围限制功能。

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
当你需要实现以下需求时可使用本指南:
  • 在WinForms应用中添加用于日期选择的日历控件
  • 实现支持单选或多选的日期选择器
  • 搭建预约或事件日期选择器
  • 创建日期范围选择界面
  • 展示带有月、年、十年、世纪视图的日历
  • 通过最小/最大日期范围限制可选日期
  • 用自定义图标和描述高亮特殊日期
  • 通过禁用日期功能屏蔽特定日期的选择
  • 用主题和单元格样式自定义日历外观
  • 针对不同文化和语言对日历进行本地化
  • 实现周末和节假日高亮
  • 搭建带有可视化日期指示器的日程安排界面

Component Overview

组件概述

Control:
SfCalendar

Namespace:
Syncfusion.WinForms.Input

Assemblies Required:
  • Syncfusion.Core.WinForms.dll
  • Syncfusion.SfInput.WinForms.dll
  • Syncfusion.Shared.Base.dll
控件:
SfCalendar

命名空间:
Syncfusion.WinForms.Input

所需程序集:
  • 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
SfCalendar提供完善的日历功能:
  • 多视图:支持月、年、十年、世纪视图,可快速导航日期
  • 日期选择:支持单选、多选、日期范围选择模式
  • 日期限制:通过MinDate和MaxDate属性限制可选日期范围
  • 特殊日期:可用自定义图标和描述高亮重要日期
  • 禁用日期:可屏蔽特定日期的选择并为其设置独立样式
  • 外观配置:丰富的主题选项、单元格自定义能力和视觉样式
  • 全球化:基于文化的本地化、一周首日设置、日期格式配置
  • 导航能力:可通过今日和清除按钮轻松在视图间导航
  • 无障碍支持:支持触控、键盘、鼠标多种交互模式

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
📄 阅读: references/getting-started.md
  • 安装与程序集要求
  • 通过设计器添加SfCalendar
  • 通过代码添加SfCalendar
  • 命名空间导入与基础配置
  • 设置初始日期值
  • 完整配置示例

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
📄 阅读: references/date-selection.md
  • 单选日期模式
  • 多选日期
  • 日期范围选择
  • MinDate与MaxDate限制
  • 禁用日期(屏蔽特定日期)
  • 带图标和描述的特殊日期
  • 选择变更事件
  • 编程式日期选择

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
📄 阅读: references/views-and-navigation.md
  • 月视图(默认视图)
  • 用于选择月份的年视图
  • 用于选择年份的十年视图
  • 用于选择十年的世纪视图
  • 视图间导航
  • 今日按钮功能
  • 用于清除选择的清除按钮
  • 头部自定义

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
📄 阅读: references/appearance-customization.md
  • 视觉样式与主题(Office2016、Metro等)
  • 单元格自定义与样式设置
  • 用于自定义渲染的单元格模板
  • 颜色自定义(背景、前景、边框)
  • 字体自定义
  • 周末单元格高亮
  • 当前日期高亮
  • 边框与内边距设置

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
📄 阅读: references/globalization.md
  • 文化与本地化支持
  • 设置一周首日
  • 日期格式自定义
  • 月份与日期名称本地化
  • 从右到左(RTL)支持
  • 特定文化的日历系统

Quick Start Example

快速入门示例

Here's a basic calendar with date selection:
C#:
csharp
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:
vb
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
以下是一个支持日期选择的基础日历实现:
C#:
csharp
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:
vb
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

模式1:带范围限制的日期选择器

Limit selectable dates to a specific range:
C#:
csharp
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;
将可选日期限制在特定范围内:
C#:
csharp
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

模式2:带特殊日期的预约选择器

Highlight appointments or special dates:
C#:
csharp
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
});
高亮预约或特殊日期:
C#:
csharp
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

模式3:多选日历

Allow selecting multiple dates:
C#:
csharp
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");
};
支持选择多个日期:
C#:
csharp
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

核心属性

PropertyTypeDescription
SelectedDate
DateTime?
Gets or sets the currently selected date
SelectedDates
ObservableCollection<DateTime>
Gets or sets collection of selected dates for multiple selection
MinDate
DateTime
Minimum selectable date
MaxDate
DateTime
Maximum selectable date
AllowMultipleSelection
bool
Enables multiple date selection
ShowToday
bool
Shows or hides Today button
ShowNone
bool
Shows or hides None button for clearing selection
BlackoutDates
ObservableCollection<DateTime>
Collection of dates to block from selection
SpecialDates
ObservableCollection<SpecialDate>
Collection of special dates with icons and descriptions
Culture
CultureInfo
Culture for localization and formatting
FirstDayOfWeek
DayOfWeek
First day of the week (Sunday, Monday, etc.)
Style
SfCalendarStyle
Visual style settings for appearance
属性类型描述
SelectedDate
DateTime?
获取或设置当前选中的日期
SelectedDates
ObservableCollection<DateTime>
获取或设置多选模式下的选中日期集合
MinDate
DateTime
最小可选日期
MaxDate
DateTime
最大可选日期
AllowMultipleSelection
bool
启用多选日期功能
ShowToday
bool
展示或隐藏今日按钮
ShowNone
bool
展示或隐藏用于清除选择的清除按钮
BlackoutDates
ObservableCollection<DateTime>
禁止选择的日期集合
SpecialDates
ObservableCollection<SpecialDate>
带有图标和描述的特殊日期集合
Culture
CultureInfo
本地化和格式设置对应的文化
FirstDayOfWeek
DayOfWeek
一周的首日(周日、周一等)
Style
SfCalendarStyle
外观对应的视觉样式设置

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

  1. 日期选择器:表单和输入对话框的单选日期功能
  2. 预约日程表:选择预约日期,同时高亮特殊日期
  3. 日期范围选择器:为报表或预订功能选择起止日期
  4. 节假日日历:用自定义图标展示节假日和特殊事件
  5. 可用性日历:在预订系统中通过禁用日期屏蔽不可用日期
  6. 多日期选择器:为批量操作或重复事件选择多个日期
  7. 本地化日历:为全球应用展示不同语言和文化的日历

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.
先阅读**入门指南**完成SfCalendar的安装和配置,之后根据你的应用需求,通过上面的导航指南探索特定功能。