syncfusion-winui-scheduler

实现 Syncfusion WinUI Scheduler (SfScheduler)

在 WinUI 应用程序中实现 Syncfusion® SfScheduler 控件的综合指南。SfScheduler 提供丰富的日程安排和日历功能，包括 8 种以上的视图类型、约会管理、资源分组，以及用于管理日程和事件的丰富自定义选项。

何时使用此技能

用户需要执行以下操作时，请立即使用此技能：

• 为 WinUI 应用程序实现日历或日程安排组件
• 创建约会预订或事件管理界面
• 构建会议安排或时间管理工具
• 在日、周、月或时间线视图中显示事件
• 处理约会的拖放或编辑
• 实现基于资源的日程安排（会议室、员工、设备）
• 支持定期约会或事件
• 管理约会的时区
• 创建具有无障碍功能的日历视图
• 构建按需加载约会功能，以提升性能

Scheduler 概述

Syncfusion WinUI Scheduler (SfScheduler) 是一款全面的日历和日程安排控件，可在多种视图类型中显示约会，并允许用户高效地创建、编辑和管理约会。

主要功能

• 8 种内置视图： Day、Week、WorkWeek、TimelineDay、TimelineWeek、TimelineWorkWeek、TimelineMonth 和 Month
• 约会管理： 使用内置编辑器创建、编辑和删除约会
• 拖放： 通过直观的拖放操作重新安排约会
• 定期事件： 支持每日、每周、每月和每年的重复模式，并可设置例外
• 资源分组： 按资源（人员、会议室、设备）对约会分组
• 时区支持： 处理跨多个时区的约会
• 无障碍功能： 完整的键盘导航、屏幕阅读器支持，符合 WCAG 标准
• 本地化： 支持全球日期/时间格式和区域设置
• 主题： Fluent Design System，提供 Light、Dark 和 HighContrast 主题
• 按需加载： 针对大型约会数据集进行性能优化
• 上下文菜单： 内置且可自定义的上下文菜单
• 提醒： 约会提醒通知

组件标识

• 包： Syncfusion.Scheduler.WinUI
• 命名空间： Syncfusion.UI.Xaml.Scheduler
• 类： SfScheduler

文档和导航指南

本节根据用户的需求，指导应阅读哪个参考文件。每个参考文件都包含全面的文档、代码示例和故障排除指南。

入门

📄 阅读： references/getting-started.md

• NuGet 包安装和设置
• 创建首个 WinUI Scheduler 应用程序
• 在 XAML 和 C# 中初始化基本日程安排控件
• 包含约会的最小可运行示例
• ViewType 配置（Day、Week、Month 等）
• 设置一周的第一天
• 命名空间导入和基本结构

约会管理

核心约会

📄 阅读： references/appointments.md

• 了解 ScheduleAppointment 类和 ScheduleAppointmentCollection
• 使用 StartTime、EndTime、Subject 创建日程约会
• 向日程安排控件添加约会
• 使用 AppointmentMapping 属性自定义约会映射
• 将自定义业务对象绑定到约会
• 使用 IsAllDay 属性设置全天约会
• 跨多天安排约会
• 约会排序和内部排列
• 使用 ItemsSource 进行数据绑定

约会编辑

📄 阅读： references/appointment-editing.md

• 内置约会编辑器对话框
• 通过 UI 创建约会
• 编辑现有约会
• 通过编辑器删除约会
• 自定义编辑器对话框外观
• 约会验证规则
• 处理编辑器事件
• 以编程方式编辑约会

预约拖放

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

• 启用/禁用拖放功能
• 通过拖动重新安排预约
• 拖放事件（AppointmentDragStarting、AppointmentDragOver、AppointmentDrop）
• 将拖放限制在特定视图或时间段内
• 拖动操作期间的视觉反馈
• 处理拖放验证
• 禁止拖动特定预约

视图类型和配置

日视图和周视图

📄 阅读： references/day-week-views.md

• 使用 ViewType.Day 配置日视图
• 使用 ViewType.Week 设置周视图
• 使用 ViewType.WorkWeek 配置工作周视图（周一至周五）
• 使用 TimeInterval 属性自定义时间间隔
• 使用 TimeIntervalSize 调整时间段高度
• 配置灵活的工作日
• 使用 NonWorkingDays 属性设置非工作日
• 自定义时间刻度尺格式
• 配置开始和结束时间

时间线视图

📄 阅读： references/timeline-views.md

• 使用 TimelineDay 视图水平显示一天
• 使用 TimelineWeek 视图显示周时间线
• 使用 TimelineWorkWeek 视图显示工作周时间线
• 使用 TimelineMonth 视图显示月时间线
• 自定义时间线视图中的时间间隔
• 使用 TimeIntervalSize 调整时间段宽度
• 水平滚动行为
• 时间线专属自定义选项
• 时间线视图中的灵活工作日

月视图

📄 阅读： references/month-view.md

• 使用 ViewType.Month 配置月视图
• 集成日程视图
• 配置显示的周数
• 月份单元格中的预约指示器
• 自定义月份单元格外观
• 显示上月和下月的日期
• 月份导航模式
• 突出显示今天的日期

导航和显示

日期导航

📄 阅读： references/date-navigations.md

• 以编程方式导航到特定日期
• 使用 DisplayDate 属性指定当前可见日期
• 向前和向后导航
• 使用 ViewChanged 事件跟踪视图变化
• 处理日期更改事件
• 以编程方式切换视图
• 日期范围验证

标题自定义

📄 阅读： references/header.md

• 自定义日程安排器标题外观
• 自定义日期标题格式
• 配置日期标题格式
• 自定义标题模板
• 调整标题高度
• 设置标题文本样式
• 视图标题模式

资源管理

资源分组

📄 阅读： references/resource-grouping.md

• 了解资源概念（人员、房间、设备）
• 使用 Id、Name、Foreground、Background 创建 SchedulerResource 对象
• 将资源添加到 ResourceCollection
• 为预约分配资源
• 使用 ResourceGroupType.Resource 按资源分组
• 使用 ResourceGroupType.Date 按日期分组
• 支持多个资源
• 自定义资源外观
• 在多个资源间共享预约

事件和交互

日程安排器事件

📄 阅读： references/events.md

• 使用 ViewChanged 事件处理视图类型更改
• 使用 CellTapped 事件处理单元格交互
• 使用 CellDoubleTapped 事件处理双击
• 使用 AppointmentTapped 事件处理预约选择
• 在 XAML 和代码中设置事件处理程序
• 事件参数属性和数据
• 处理用户交互

上下文菜单和命令

📄 阅读： references/context-flyout-commands.md

• 内置上下文菜单功能
• 添加自定义上下文菜单项
• 上下文菜单命令
• 处理上下文菜单事件
• 自定义菜单外观
• 操作的命令模式

高级功能

时区支持

📄 阅读： references/time-zone.md

• 设置 scheduler 的 TimeZone 属性
• 使用 StartTimeZone 和 EndTimeZone 设置预约专属时区
• 配置显示时区
• 处理夏令时
• 跨时区转换预约
• 在 UI 中显示时区
• 多时区应用的最佳实践

按需加载

📄 阅读： references/load-on-demand.md

• 启用按需加载以提升性能
• 使用 QueryAppointments 事件动态加载
• 显示加载指示器
• 高效处理大型预约数据集
• 基于日期范围加载
• 性能优化技巧
• 延迟加载模式

提醒

📄 阅读： references/reminder.md

• 配置预约提醒
• 提醒通知功能
• 自定义提醒窗口
• 稍后提醒功能
• 自定义提醒间隔
• 提醒通知

无障碍功能和本地化

无障碍功能

📄 阅读： references/accessibility.md

• 键盘导航（Tab、箭头键、Enter、Escape）
• 屏幕阅读器支持（兼容 Narrator）
• 符合 WCAG 2.1 标准
• 焦点指示器和视觉反馈
• 无障碍预约创建和编辑
• 支持高对比度主题
• 无障碍最佳实践

本地化

📄 阅读： references/localization.md

• 设置 scheduler 本地化
• 为不同区域性创建资源文件（.resw）
• 区域性特定的日期和时间格式
• 本地化 scheduler UI 字符串
• 支持 RTL（从右到左）语言
• 多语言支持模式

自定义和主题

主题

📄 阅读： references/themes.md

• 内置 Fluent Design 主题（浅色、深色、高对比度）
• 为 scheduler 应用主题
• 创建自定义主题
• 使用 ThemeResource 自定义颜色
• 覆盖主题键
• GitHub 上的主题资源文件
• 响应式主题切换

快速入门示例

以下是开始使用 WinUI Scheduler 的最简示例：

XAML 设置

<Window
    x:Class="SchedulerApp.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:scheduler="using:Syncfusion.UI.Xaml.Scheduler">
    
    <Grid>
        <scheduler:SfScheduler x:Name="Schedule" 
                              ViewType="Week" 
                              FirstDayOfWeek="Monday" />
    </Grid>
</Window>

C# 代码隐藏

using Syncfusion.UI.Xaml.Scheduler;
using System;

namespace SchedulerApp
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
            
            // Create appointment collection
            var appointments = new ScheduleAppointmentCollection();
            
            // Add a sample appointment
            appointments.Add(new ScheduleAppointment
            {
                StartTime = DateTime.Now.Date.AddHours(10),
                EndTime = DateTime.Now.Date.AddHours(12),
                Subject = "Team Meeting",
                Location = "Conference Room A",
                Notes = "Discuss Q1 goals"
            });
            
            // Set appointments to scheduler
            Schedule.ItemsSource = appointments;
        }
    }
}

结果

这将创建一个 Week 视图 scheduler，并安排今天上午 10 点到中午 12 点的一个预约。

常见模式

模式 1：自定义预约绑定

使用自定义业务对象而非 ScheduleAppointment 时：

// Custom appointment class
public class Meeting
{
    public string Title { get; set; }
    public DateTime From { get; set; }
    public DateTime To { get; set; }
    public bool AllDay { get; set; }
}

<scheduler:SfScheduler x:Name="Schedule" 
                      ItemsSource="{Binding Meetings}">
    <scheduler:SfScheduler.AppointmentMapping>
        <scheduler:AppointmentMapping
            Subject="Title"
            StartTime="From"
            EndTime="To"
            IsAllDay="AllDay"/>
    </scheduler:SfScheduler.AppointmentMapping>
</scheduler:SfScheduler>

模式 2：重复预约

var recurringAppointment = new ScheduleAppointment
{
    StartTime = DateTime.Now.Date.AddHours(9),
    EndTime = DateTime.Now.Date.AddHours(10),
    Subject = "Daily Standup",
    RecurrenceRule = "FREQ=DAILY;INTERVAL=1;COUNT=10"
};

模式 3：基于资源的排程

// Create resources
var resources = new ObservableCollection<SchedulerResource>
{
    new SchedulerResource 
    { 
        Id = "1", 
        Name = "Conference Room A",
        Background = new SolidColorBrush(Colors.Blue)
    },
    new SchedulerResource 
    { 
        Id = "2", 
        Name = "Conference Room B",
        Background = new SolidColorBrush(Colors.Green)
    }
};

Schedule.ResourceCollection = resources;
Schedule.ResourceGroupType = ResourceGroupType.Resource;

// Assign appointment to resource
var appointment = new ScheduleAppointment
{
    StartTime = DateTime.Now.Date.AddHours(10),
    EndTime = DateTime.Now.Date.AddHours(11),
    Subject = "Product Demo",
    ResourceIdCollection = new ObservableCollection<object> { "1" }
};

模式 4：视图类型切换

// Switch between views programmatically
public void SwitchToMonthView()
{
    Schedule.ViewType = SchedulerViewType.Month;
}

public void SwitchToTimelineView()
{
    Schedule.ViewType = SchedulerViewType.TimelineWeek;
}

模式 5：时区处理

// Set scheduler time zone
Schedule.TimeZone = TimeZoneInfo.FindSystemTimeZoneById("Pacific Standard Time");

// Appointment with specific time zones
var appointment = new ScheduleAppointment
{
    StartTime = new DateTime(2024, 3, 22, 10, 0, 0),
    EndTime = new DateTime(2024, 3, 22, 11, 0, 0),
    Subject = "Cross-timezone Meeting",
    StartTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Pacific Standard Time"),
    EndTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time")
};

关键属性参考

基本属性

属性	类型	说明
ViewType	SchedulerViewType	设置视图类型（Day、Week、Month、Timeline 各种视图）
ItemsSource	IEnumerable	预约的数据源
DisplayDate	DateTime	scheduler 当前显示的日期
FirstDayOfWeek	DayOfWeek	一周的第一天（Sunday、Monday 等）
TimeZone	TimeZoneInfo	显示预约时使用的时区

外观属性

属性	类型	说明
DaysViewSettings	DaysViewSettings	Day、Week 和 WorkWeek 视图的设置
TimelineViewSettings	TimelineViewSettings	Timeline 视图的设置
MonthViewSettings	MonthViewSettings	Month 视图的设置

资源属性

属性	类型	说明
ResourceCollection	ObservableCollection<SchedulerResource>	资源集合
ResourceGroupType	ResourceGroupType	分组类型（None、Resource、Date）

预约映射

属性	类型	说明
AppointmentMapping	AppointmentMapping	将自定义对象属性映射到预约属性

视图专属设置

DaysViewSettings：

• TimeInterval - 时间段间隔（例如，30 分钟、1 小时）
• TimeIntervalSize - 时间段的高度
• NonWorkingDays - 标记为非工作日的日期

TimelineViewSettings：

• TimeInterval - 时间线的时间段间隔
• TimeIntervalSize - 时间线中时间段的宽度

MonthViewSettings：

• NumberOfWeeksInView - 要显示的周数
• ShowAgendaView - 显示/隐藏议程视图

常见用例

1. 会议室预订系统

创建基于资源的日程安排程序，通过拖放预订来显示会议室的可用情况。

适用场景： 构建会议室预订系统、设备排期系统 主要功能： 资源分组、拖放、编辑约会

2. 员工轮班排期程序

跨多天显示员工班次，并使用不同颜色标记日程安排。

适用场景： 轮班规划、劳动力管理、零售排班 主要功能： 资源分组、周/月视图、自定义约会颜色

3. 医生预约系统

管理患者预约，支持时间段和循环约会。

适用场景： 医疗排期、预约系统 主要功能： 日/周视图、循环约会、编辑约会

4. 活动日历

在月历视图中显示活动及其详细信息。

适用场景： 活动管理、会议排期、活动日历 主要功能： 月视图、全天事件、自定义约会模板

5. 项目时间线

在时间线视图中显示项目里程碑和任务。

适用场景： 项目管理、类似甘特图的视图、规划工具 主要功能： 时间线视图、跨时段约会、资源分组

6. 多时区日程安排程序

处理全球团队跨不同时区的约会。

适用场景： 远程团队协调、国际排期 主要功能： 时区支持、时区转换、时间显示

最佳实践：

• 对于大型约会数据集（>1000 个约会），使用按需加载
• 绑定到 ObservableCollection，以自动更新 UI
• 在自定义约会类中实现 INotifyPropertyChanged
• 使用 AppointmentMapping 映射自定义业务对象
• 在拖放操作期间提供清晰的视觉反馈
• 为不同的约会类型或资源使用易于区分的颜色
• 启用键盘导航以提升无障碍体验
• 使用主题资源确保外观一致
• 如果业务逻辑有要求，验证约会是否重叠
• 谨慎处理时区转换

故障排除

约会未显示

• 确认 ItemsSource 已正确绑定
• 检查 StartTime 和 EndTime 是否在可见日期范围内
• 确保已正确设置 ViewType
• 确认约会已添加到集合中

拖放不起作用

• 检查约会是否为只读
• 确认已启用拖放（默认启用）
• 确保目标时间段对该约会有效

资源分组不可见

• 确认 ResourceGroupType 未设置为 None
• 检查 ResourceCollection 是否已填充
• 确保约会具有正确的 ResourceIdCollection 值

性能问题

• 对大型数据集实现按需加载
• 减少同时可见的约会数量
• 如果使用了自定义模板，请优化这些模板

后续步骤

根据用户的具体需求，引导他们查阅上方文档和导航指南部分中相应的参考文件。每份参考文件都通过代码示例、边缘情况和故障排除内容进行深入介绍。

有关 WinUI 组件或其他 Syncfusion 控件的一般问题，请参阅父级技能：

• 实现 Syncfusion WinUI 组件

---

NuGet 包： Syncfusion.Scheduler.WinUI
命名空间： Syncfusion.UI.Xaml.Scheduler
API 参考： https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Scheduler.html