syncfusion-winforms-calendar

实现日历（SfCalendar）

本技能介绍如何实现 Syncfusion 的 SfCalendar。这是一款功能强大的日期选择日历控件，支持多种视图（月、年、十年、世纪），提供全面的自定义选项，并支持特殊日期、禁用日期和日期范围限制。

何时使用此技能

在以下情况下使用此技能：

• 在 WinForms 应用程序中添加用于日期选择的日历控件
• 实现支持单选或多选日期的日期选择器
• 构建预约或事件日期选择器
• 创建日期范围选择界面
• 显示月、年、十年和世纪视图的日历
• 使用最小和最大日期范围限制日期选择
• 使用自定义图标和说明突出显示特殊日期
• 使用禁用日期阻止选择特定日期
• 使用主题和单元格样式自定义日历外观
• 针对不同文化和语言本地化日历
• 实现周末和节假日突出显示
• 构建带有可视日期指示器的日程安排界面

组件概述

控件： SfCalendar
命名空间： Syncfusion.WinForms.Input
所需程序集：

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

主要功能

SfCalendar 提供全面的日历功能：

• 多种视图：月、年、十年和世纪视图，方便快速浏览日期
• 日期选择：单个日期、多个日期或日期范围选择模式
• 日期限制：使用 MinDate 和 MaxDate 属性限制可选日期范围
• 特殊日期：使用自定义图标和说明突出显示重要日期
• 禁用日期：使用不同样式阻止选择特定日期
• 外观：丰富的主题选项、单元格自定义和视觉样式
• 全球化：基于区域性的本地化、每周首日和日期格式
• 导航：通过“今天”和“无”按钮轻松切换视图
• 辅助功能：支持触控、键盘和鼠标等多种交互方式

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和程序集要求
• 通过设计器添加 SfCalendar
• 通过代码添加 SfCalendar
• 导入命名空间并进行基本设置
• 设置初始日期值
• 完整的设置示例

日期选择

📄 阅读： references/date-selection.md

• 单个日期选择模式
• 多日期选择
• 日期范围选择
• MinDate 和 MaxDate 限制
• 禁用日期（阻止选择特定日期）
• 带图标和说明的特殊日期
• 选择更改事件
• 以编程方式选择日期

事件

• SelectedDateChanged：单选模式下，单个 SelectedDate 属性发生变化时触发。
• SelectionChanged：多选模式下，SelectedDates 集合发生变化时触发。

视图与导航

📄 阅读： references/views-and-navigation.md

• 月视图（默认视图）
• 用于选择月份的年视图
• 用于选择年份的十年视图
• 用于选择十年的世纪视图
• 在视图之间导航
• “今天”按钮功能
• 用于清除选择的“无”按钮
• 标题自定义

外观自定义

📄 阅读： references/appearance-customization.md

• 视觉样式和主题（Office2016、Metro 等）
• 单元格自定义和样式设置
• 用于自定义呈现的单元格模板
• 颜色自定义（背景、前景、边框）
• 字体自定义
• 周末单元格突出显示
• 当前日期突出显示
• 边框和内边距设置

全球化

📄 阅读： references/globalization.md

• 文化和本地化支持
• 设置一周的第一天
• 日期格式自定义
• 月份和星期名称本地化
• 从右到左（RTL）支持
• 特定文化的日历系统

快速入门示例

下面是一个带日期选择功能的基本日历：

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

常见模式

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

将可选日期限制在特定范围内：

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;

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

突出显示预约或特殊日期：

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

模式 3：多选日历

允许选择多个日期：

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

关键属性

属性	类型	说明
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	外观的视觉样式设置

常见用例

1. 日期选择器：用于表单和输入对话框的单日期选择
2. 预约安排器：选择预约日期并突出显示特殊日期
3. 日期范围选择器：为报告或预订选择开始和结束日期
4. 节日日历：使用自定义图标显示节日和特殊活动
5. 可用时间日历：通过屏蔽不可用日期，为预订系统设置日期限制
6. 多日期选择器：为批量操作或定期活动选择多个日期
7. 本地化日历：在全球应用中以不同语言和区域性显示日历

---

后续步骤

从 入门指南 开始安装和配置 SfCalendar，然后根据应用需求，通过上方的导航指南探索特定功能。