syncfusion-wpf-scheduler

WPF Scheduler (SfScheduler) 实现

WPF Scheduler (SfScheduler) 是一款功能全面的日程安排控件，可通过类似 Outlook 日历的直观用户界面管理约会。它提供 8 种不同的视图类型、约会管理、资源分组、拖放、重复模式、时区支持以及丰富的自定义选项。

何时使用此技能

在用户需要以下功能时使用此技能：

• 在 WPF 应用程序中实现日历或日程安排功能
• 创建约会管理系统
• 构建资源日程安排应用程序
• 实现会议或活动管理界面
• 在应用程序中添加类似 Outlook 的日历视图
• 安排和管理重复约会
• 处理多资源日程安排场景
• 显示不同时区中的约会
• 实现通过拖放重新安排约会
• 创建自定义约会编辑器或视图
• 将约会导入标准 iCalendar (.ics) 文件或从中导出约会
• 在 TimelineMonth 中使用特殊时间区域突出显示受限日期范围

组件概览

主要功能：

• 8 种内置视图： Day、Week、WorkWeek、Month、TimelineDay、TimelineWeek、TimelineWorkWeek、TimelineMonth
• 约会管理： 普通、全天、跨时段和重复约会，支持完整的 CRUD 操作
• 资源日程安排： 支持多资源，可按资源或日期分组
• 拖放： 通过直观操作和视觉反馈重新安排约会
• 重复模式： 每日、每周、每月、每年，支持例外处理
• 时区支持： 支持处理多个时区，并自动调整 DST
• 内置编辑器： 创建和编辑约会，并进行验证
• 自定义： 提供丰富的样式、模板和外观选项
• 无障碍支持： 符合 WCAG 标准，支持完整的键盘导航
• 高级功能： 按需加载、提醒、本地化
• ICS (iCalendar) 导入/导出： 使用标准 RFC 5545 .ics 文件双向导入和导出约会
• TimelineMonth 中的特殊时间区域： 通过 TimelineViewSettings.ShowMonthTimeRegions 按需启用跨日期列的区块

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署和 NuGet 包
• 创建基础日程安排应用程序（设计器、XAML、C#）
• 基础约会设置和配置
• 一周起始日和主题支持
• 初始设置和快速入门示例

视图与显示

📄 阅读： references/scheduler-views.md

• 可用的视图类型（Day、Week、Month、Timeline 变体）
• ViewType 属性和视图切换
• 特定视图的功能和呈现
• 当前日期显示

📄 阅读： references/view-customization.md

• 时间间隔和时段高度自定义
• 工作日和工作时间配置
• 特殊时间区域（午休、节假日）
• 通过 ShowMonthTimeRegions 在 TimelineMonth 中设置特殊时间区域
• 时段选择限制

约会与数据

📄 阅读： references/appointments.md

• ScheduleAppointment 类及其属性
• 创建和管理约会
• ItemSource 和 AppointmentMapping
• 自定义业务对象和数据绑定
• 全天和跨时段约会
• 重复约会和模式（RRULE）
• 重复例外

📄 阅读： references/appointment-editing.md

• 内置约会编辑器
• 通过 UI 创建、编辑和删除约会
• 编辑器自定义和验证
• 编辑器事件和自定义逻辑

📄 阅读： references/appointment-drag-drop.md

• 拖放功能
• 重新安排约会
• 拖放限制和事件

ICS 导入和导出

📄 阅读： references/ics-import-export.md

• ExportToICalendar(fileName) — 将所有约会写入 .ics 文件（Downloads 文件夹）
• ImportICalendar() — 打开文件选择器并解析所选 .ics 文件
• RFC 5545 映射（VCALENDAR / VEVENT / RRULE / EXDATE / RECURRENCE-ID）
• 循环模式和已更改实例的往返转换
• 导出和导入时的时区处理

资源管理

📄 阅读： references/resource-grouping.md

• 资源概念和 SchedulerResource 类
• ResourceGroupType（按资源或日期分组）
• 为约会分配资源
• 多资源排期
• 自定义资源外观

日历和时间管理

📄 阅读： references/calendar-types.md

• 日历系统（公历、自定义日历）
• 日历配置

📄 阅读： references/date-navigation.md

• DisplayDate 属性
• 通过编程方式导航的方法
• 日期更改事件

📄 阅读： references/timezones.md

• Scheduler 和约会的时区
• 自动时区转换
• 夏令时处理
• 多时区排期场景

UI 自定义

📄 阅读： references/ui-features.md

• 标题自定义和模板
• 上下文菜单和命令
• 忙碌指示器
• 选择模式和事件

高级功能

📄 阅读： references/advanced-features.md

• 无障碍访问（WCAG、键盘导航）
• 本地化和特定区域设置的格式
• 为大型数据集按需加载
• 提醒和通知
• 从 SfSchedule 迁移到 SfScheduler

快速入门示例

带约会的基本 Scheduler

XAML：

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <syncfusion:SfScheduler x:Name="Schedule" 
                            ViewType="Week"
                            FirstDayOfWeek="Sunday" />
</Window>

C# 代码隐藏：

using Syncfusion.UI.Xaml.Scheduler;

public MainWindow()
{
    InitializeComponent();
    
    // Create appointment collection
    var appointments = new ScheduleAppointmentCollection();
    
    // Add sample appointment
    appointments.Add(new ScheduleAppointment
    {
        StartTime = DateTime.Now.Date.AddHours(10),
        EndTime = DateTime.Now.Date.AddHours(12),
        Subject = "Client Meeting",
        Location = "Conference Room A",
        Notes = "Discuss project timeline",
        AppointmentBackground = Brushes.LightBlue
    });
    
    Schedule.ItemsSource = appointments;
}

常见模式

模式 1：通过数据绑定使用自定义约会

// Custom business object
public class Meeting : INotifyPropertyChanged
{
    public string EventName { get; set; }
    public DateTime From { get; set; }
    public DateTime To { get; set; }
    public Brush Color { get; set; }
    public bool IsAllDay { get; set; }
}

// ViewModel
public class SchedulerViewModel
{
    public ObservableCollection<Meeting> Events { get; set; }
    
    public SchedulerViewModel()
    {
        Events = new ObservableCollection<Meeting>
        {
            new Meeting
            {
                EventName = "Team Standup",
                From = DateTime.Now.Date.AddHours(9),
                To = DateTime.Now.Date.AddHours(9.5),
                Color = Brushes.Green,
                IsAllDay = false
            }
        };
    }
}

XAML：

<syncfusion:SfScheduler x:Name="Schedule" 
                        ViewType="Week"
                        ItemsSource="{Binding Events}">
    <syncfusion:SfScheduler.AppointmentMapping>
        <syncfusion:AppointmentMapping
            Subject="EventName"
            StartTime="From"
            EndTime="To"
            AppointmentBackground="Color"
            IsAllDay="IsAllDay" />
    </syncfusion:SfScheduler.AppointmentMapping>
</syncfusion:SfScheduler>

模式 2：每周定期会议

var recurringMeeting = new ScheduleAppointment
{
    StartTime = new DateTime(2026, 3, 24, 14, 0, 0), // Monday 2PM
    EndTime = new DateTime(2026, 3, 24, 15, 0, 0),
    Subject = "Weekly Status Meeting",
    // Recur every Monday for 12 weeks
    RecurrenceRule = "FREQ=WEEKLY;BYDAY=MO;COUNT=12",
    AppointmentBackground = Brushes.Orange
};

模式 3：基于资源的排期

// Add resources
Schedule.ResourceCollection = new ObservableCollection<SchedulerResource>
{
    new SchedulerResource { Id = "1001", Name = "Dr. Smith", Background = Brushes.Blue },
    new SchedulerResource { Id = "1002", Name = "Dr. Jones", Background = Brushes.Green }
};

Schedule.ResourceGroupType = ResourceGroupType.Resource;

// Assign appointment to resource
var appointment = new ScheduleAppointment
{
    StartTime = DateTime.Now.AddHours(2),
    EndTime = DateTime.Now.AddHours(3),
    Subject = "Patient Consultation",
    ResourceIdCollection = new ObservableCollection<object> { "1001" }
};

模式 4：支持时区的约会

var globalMeeting = new ScheduleAppointment
{
    StartTime = new DateTime(2026, 3, 25, 10, 0, 0),
    EndTime = new DateTime(2026, 3, 25, 11, 0, 0),
    Subject = "Global Team Sync",
    StartTimeZone = "Pacific Standard Time",
    EndTimeZone = "Pacific Standard Time"
};

// Scheduler displays in local timezone automatically
Schedule.TimeZone = TimeZoneInfo.Local.Id;

模式 5：导入 / 导出 iCalendar（RFC 5545）

// Export all appointments to a .ics file in the user's Downloads folder
await Schedule.ExportToICalendar("TeamCalendar");

// Import appointments from a .ics file chosen via the system file picker
await Schedule.ImportICalendar();

模式 6：TimelineMonth 中的特殊时间区域

// Switch to TimelineMonth and enable special time region rendering
Schedule.ViewType = SchedulerViewType.TimelineMonth;
Schedule.TimelineViewSettings.ShowMonthTimeRegions = true;

// Add a region spanning several days (time-of-day is ignored in TimelineMonth)
Schedule.TimelineViewSettings.SpecialTimeRegions.Add(new SpecialTimeRegion
{
    StartTime = new DateTime(2026, 6, 10),
    EndTime = new DateTime(2026, 6, 14),
    Text = "Audit Week",
    Background = new SolidColorBrush(Color.FromRgb(0xF5, 0xE1, 0xB4)),
    Foreground = Brushes.Black,
    CanEdit = false // blocks drag-drop and new appointments in those columns
});

关键属性概览

核心属性

属性	类型	说明	默认值
ViewType	SchedulerViewType	设置视图（Day、Week、WorkWeek、Month、TimelineDay、TimelineWeek、TimelineWorkWeek、TimelineMonth）	Month
ItemsSource	IEnumerable	要显示的约会集合	null
DisplayDate	DateTime	当前显示的日期	DateTime.Now
SelectedDate	DateTime?	当前选中的日期	null
FirstDayOfWeek	DayOfWeek	一周的起始日	Sunday
TimeZone	string	Scheduler 的时区标识符（为 null 时回退到 TimeZoneInfo.Local.Id）	null

视图导航和配置

属性	类型	说明	默认值
AllowedViewTypes	SchedulerViewType	导航时允许的视图类型	All
AllowViewNavigation	bool	启用点击标题后从周 / 月 / TimelineMonth 视图导航到日 / TimelineDay 视图	false
ShowDatePickerButton	bool	在标题中显示日期选择器按钮	true

日期范围属性

属性	类型	说明	默认值
MinimumDate	DateTime	可显示的最早日期	DateTime.MinValue
MaximumDate	DateTime	可显示的最晚日期	DateTime.MaxValue
BlackoutDates	ObservableCollection<DateTime>	禁止交互的日期（Month 和 TimelineMonth 视图）	null

数据绑定与映射

属性	类型	说明	默认值
AppointmentMapping	AppointmentMapping	将自定义对象映射到 ScheduleAppointment 属性	null
ResourceMapping	ResourceMapping	将自定义对象映射到 SchedulerResource 属性	null

标题自定义

属性	类型	说明	默认值
HeaderHeight	double	调度器标题的高度（视图上方的日期选择器／月份名称标题）	32 (WPF) / 40 (WinUI)
HeaderTemplate	DataTemplate	标题的自定义模板	null
ViewHeaderHeight	double	Day／Week／Timeline 视图中每个日期／资源列标题的高度（在 ViewSettingsBase 上）	50
ViewHeaderDateFormat	string	每列视图标题的日期格式字符串（在 TimeSlotViewSettings 上）	"%d"
ViewHeaderDayFormat	string	每列视图标题的星期格式字符串（在 ViewSettingsBase 上）	（默认为星期缩写）
ViewHeaderTemplate	DataTemplate	每列视图标题的自定义模板	null

资源排程

属性	类型	说明	默认值
ResourceCollection	ObservableCollection<SchedulerResource>	调度器资源集合	null
ResourceGroupType	ResourceGroupType	分组模式（Resource、Date、None）	None
ResourceHeaderTemplate	DataTemplate	资源标题的自定义模板	null
ResourceHeaderTemplateSelector	DataTemplateSelector	资源标题的模板选择器	null

视图专属设置

属性	类型	说明	默认值
DaysViewSettings	DaysViewSettings	Day／Week／WorkWeek 视图的设置	Default
MonthViewSettings	MonthViewSettings	Month 视图的设置	Default
TimelineViewSettings	TimelineViewSettings	Timeline 视图的设置	Default

日历与区域设置

属性	类型	说明	默认值
CalendarIdentifier	string	日历系统标识符（Gregorian 等）	Gregorian

UI 与交互

属性	类型	说明	默认值
ShowBusyIndicator	bool	在操作期间显示加载指示器	false
EnableToolTip	bool	启用预约事项的工具提示	true
ToolTipTemplate	DataTemplate	工具提示的自定义模板	null
EnableReminder	bool	启用提醒功能	true

上下文菜单

属性	类型	说明	默认值
AppointmentContextMenu	ContextMenu	预约事项的上下文菜单	Default
CellContextMenu	ContextMenu	单元格的上下文菜单	Default

拖放

属性	类型	说明	默认值
DragDropSettings	DragDropSettings	配置拖放行为	Default

预约事项编辑

属性	类型	说明	默认值
AppointmentEditFlag	AppointmentEditFlag	控制允许的编辑操作（Add、Edit、Resize、DragDrop）	Add | Edit | Resize | DragDrop
AppointmentResizeController	AppointmentResizeController	自定义调整大小行为控制器	new AppointmentResizeController(this)

按需加载

属性	类型	说明	默认值
LoadOnDemandCommand	ICommand	按需加载可见日期范围内预约事项时调用的命令	null

关键方法

方法	描述
Forward()	向前导航一个视图间隔
Backward()	向后导航一个视图间隔
SchedulerDateToPoint(DateTime)	将日期转换为屏幕坐标
PointToSchedulerDate(Point)	将屏幕坐标转换为日期/时间
ExportToICalendar(string fileName = null)	异步将所有约会导出到写入用户 Downloads 文件夹的 .ics 文件。返回 Task<bool>（成功时为 true）。
ImportICalendar()	异步打开文件选择器，并将选中的 .ics 文件解析到日程表中。返回 Task<bool>（成功时为 true）。

关键事件

事件	描述
ViewChanged	视图类型更改时触发
DisplayDateChanged	显示日期更改时触发
SelectionChanged	选中的日期/约会更改时触发
CellTapped	单元格被轻触/单击时触发
CellDoubleTapped	单元格被双击时触发
CellLongPressed	长按单元格时触发
AppointmentTapped	约会被轻触/单击时触发
AppointmentDoubleTapped	约会被双击时触发
AppointmentDragStarting	开始拖动约会时触发（可取消）
AppointmentDragOver	将约会拖过日程表时触发
AppointmentDrop	放下约会时触发
AppointmentResizeStarting	开始调整约会大小时触发（可取消）
AppointmentResizing	调整约会大小时触发
AppointmentResizeCompleted	完成调整约会大小时触发
AppointmentEditorOpening	打开约会编辑器时触发（可取消）
AppointmentEditorClosing	关闭约会编辑器时触发（可取消）
HeaderTapped	标题被轻触/单击时触发

常见用例

1. 会议室日程管理 - 通过资源分组管理会议室预订
2. 医疗预约 - 管理医生排班、患者预约和定期时段
3. 项目时间线 - 跟踪任务、里程碑和团队成员分配
4. 活动日历 - 管理全天和多日公共活动
5. 员工轮班规划 - 基于资源安排轮班，并支持拖放
6. 课程表 - 管理包含定期课程的教学时间表
7. 服务预订 - 管理包含可用时段的预约预订系统

重要注意事项

• 性能： 对于跨越多年的大型数据集，请使用 LoadOnDemand
• 数据绑定： 自定义对象必须实现 INotifyPropertyChanged 才能更新
• 重复规则： 使用 RRULE 格式定义重复模式（标准 RFC 5545）
• 时区： 面向全球用户的应用始终应指定时区
• 资源： ResourceIdCollection 中的 ID 必须与 ResourceCollection 中的 ID 相匹配
• 视图： 根据用例选择合适的视图（详细信息使用 Day，概览使用 Month）
• TimelineMonth 特殊时间区域： 通过 TimelineViewSettings.ShowMonthTimeRegions = true 启用。TimelineMonth 会忽略一天中的时间——只有 StartTime / EndTime 的日期部分会控制渲染范围。
• ICS 导出位置： ExportToICalendar 始终将文件写入用户的 Downloads 文件夹（%USERPROFILE%\Downloads）。系统会自动追加 .ics 扩展名。
• ICS 重复项处理： ImportICalendar 会跳过已存在相同 Id 的约会，以及已存在相同 RecurrenceId 的已更改重复实例，因此重新导入同一文件不会产生重复项。

后续步骤

从入门指南开始，了解安装和基本设置；然后根据需求，使用上方的导航指南探索具体功能。