syncfusion-winforms-calendar
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing 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:
Namespace:
Assemblies Required:
SfCalendarNamespace:
Syncfusion.WinForms.InputAssemblies Required:
Syncfusion.Core.WinForms.dllSyncfusion.SfInput.WinForms.dllSyncfusion.Shared.Base.dll
控件:
命名空间:
所需程序集:
SfCalendar命名空间:
Syncfusion.WinForms.Input所需程序集:
Syncfusion.Core.WinForms.dllSyncfusion.SfInput.WinForms.dllSyncfusion.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 ClassCommon 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
核心属性
| Property | Type | Description |
|---|---|---|
| SelectedDate | | Gets or sets the currently selected date |
| SelectedDates | | Gets or sets collection of selected dates for multiple selection |
| MinDate | | Minimum selectable date |
| MaxDate | | Maximum selectable date |
| AllowMultipleSelection | | Enables multiple date selection |
| ShowToday | | Shows or hides Today button |
| ShowNone | | Shows or hides None button for clearing selection |
| BlackoutDates | | Collection of dates to block from selection |
| SpecialDates | | Collection of special dates with icons and descriptions |
| Culture | | Culture for localization and formatting |
| FirstDayOfWeek | | First day of the week (Sunday, Monday, etc.) |
| Style | | Visual style settings for appearance |
| 属性 | 类型 | 描述 |
|---|---|---|
| SelectedDate | | 获取或设置当前选中的日期 |
| SelectedDates | | 获取或设置多选模式下的选中日期集合 |
| MinDate | | 最小可选日期 |
| MaxDate | | 最大可选日期 |
| AllowMultipleSelection | | 启用多选日期功能 |
| ShowToday | | 展示或隐藏今日按钮 |
| ShowNone | | 展示或隐藏用于清除选择的清除按钮 |
| BlackoutDates | | 禁止选择的日期集合 |
| SpecialDates | | 带有图标和描述的特殊日期集合 |
| Culture | | 本地化和格式设置对应的文化 |
| FirstDayOfWeek | | 一周的首日(周日、周一等) |
| Style | | 外观对应的视觉样式设置 |
Common Use Cases
常见使用场景
- Date Picker: Single date selection for forms and input dialogs
- Appointment Scheduler: Select dates for appointments with special date highlighting
- Date Range Selector: Select start and end dates for reports or bookings
- Holiday Calendar: Display holidays and special events with custom icons
- Availability Calendar: Block unavailable dates using blackout dates for booking systems
- Multi-Date Selector: Select multiple dates for batch operations or recurring events
- 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.
先阅读**入门指南**完成SfCalendar的安装和配置,之后根据你的应用需求,通过上面的导航指南探索特定功能。