syncfusion-vue-scheduler

Syncfusion Vue Scheduler

一款功能全面的 Vue 排程组件，提供日历视图、预约管理、资源排程和基于时间的事件可视化，并支持拖放。

何时使用此技能

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

• 在 Vue 应用中实现日历或排程功能
• 创建预约预订或事件管理系统
• 构建资源分配或会议排程工具
• 在日、周、月、时间线或议程视图中显示事件
• 处理具有复杂重复模式的循环事件
• 管理多个资源并进行分组排程
• 实现拖放式事件排程
• 创建支持 CRUD 操作的交互式日历
• 在排程应用中支持多个时区
• 导出/导入日历数据（ICS 格式）
• 使用 Scheduler WebMCP 工具集成由 WebMCP Agent 驱动的排程
• 为预约预留事件前后的时间（准备、恢复、过渡）
• 自定义当前时间指示器（标签、之前的日期、堆叠顺序）

组件概览

Syncfusion Vue Scheduler 是一款功能丰富的日历和排程组件，支持：

• 多种视图：日、周、工作周、月、年、议程和时间线视图
• 事件管理：普通、全天、跨时段和循环事件及其例外情况
• 事件缓冲时间：预留事件前后的时间（准备、恢复、过渡），并支持自定义缓冲区模板
• WebMCP 集成：通过 enableWebMcp 和 webMcpSettings 及内置 WebMCP 工具实现由 Agent 驱动的排程
• 自定义当前时间指示器：可配置当前时间线，包括自定义标签、之前日期范围和堆叠顺序
• 资源排程：支持单个和多个资源分组，并提供自定义模板
• 拖放：在时间槽和资源之间移动和调整事件大小
• 数据绑定：支持本地和远程数据源及字段映射
• 自定义：单元格模板、事件模板和全面的样式选项
• 交互：上下文菜单、剪贴板操作、键盘快捷键
• 无障碍访问：全面符合 WCAG 标准，支持键盘导航和屏幕阅读器

文档和导航指南

全面介绍 Syncfusion Vue Scheduler，包含 20 个详尽的参考文件，涵盖排程实现的各个方面。

入门

📄 阅读： references/getting-started.md

• 安装 @syncfusion/ej2-vue-schedule 和主题包
• 使用 Syncfusion 主题包引用 CSS
• Vue 2/3 的模块注入和 provide 设置
• 使用 selectedDate 和 currentView 初始化基本排程器
• 使用 eventSettings 创建首批预约
• 所需所有组件的 CSS 导入路径

预约和事件

📄 阅读： references/appointments.md

• 事件类型：普通、全天、跨时段和循环预约
• 事件字段和自定义字段映射
• 重复规则和模式（FREQ、INTERVAL、COUNT、UNTIL、BYDAY 等）
• 重复例外情况，以及编辑单次事件或整个系列
• 使用 dragStart/drag/dragStop 事件拖放
• 使用调整大小控件调整事件大小
• 内联预约编辑
• 事件检索方法（getEventDetails、getCurrentViewEvents、getEvents）

预约行为和验证

📄 阅读： references/appointment-behavior-and-validation.md

• 设置预约最小高度
• 屏蔽日期和时间
• 只读事件和限制事件创建
• 区分过去的事件并禁用过去的日期
• 让预约占据整个单元格并限制显示的事件数
• 工具提示和筛选操作
• 选择预约并通过 Delete 键删除多个预约
• 防止事件重叠并验证重复规则

视图与导航（显示模式）

📄 阅读： references/views.md

• Day、Week、WorkWeek、Month、Year、Agenda、MonthAgenda 视图
• Timeline 视图（TimelineDay、TimelineWeek、TimelineWorkWeek、TimelineMonth、TimelineYear）
• 视图专属配置（startHour、endHour、workDays、interval、dateFormat）
• 多日、多周和多月视图间隔
• 视图模板（cellTemplate、dateHeaderTemplate、eventTemplate、resourceHeaderTemplate）
• Timeline 视图的自定义标题行
• 周起始日配置
• 所有视图均支持隐藏周末
• 只读视图模式
• Agenda 和 Timeline 视图中的虚拟滚动
• 显示周数
• Agenda 天数以及 hideEmptyAgendaDays
• 使用 maxEventStack 限制重叠事件数量

数据绑定（本地和远程）

📄 阅读： references/data-binding.md

• 使用对象数组作为本地数据源
• 使用 DataManager 进行远程数据绑定（ODataV4Adaptor、WebApiAdaptor、UrlAdaptor）
• 自定义字段映射（id、subject、startTime、endTime、location、description、isAllDay、recurrenceRule、isReadonly）
• 使用 includeFiltersInQuery 进行服务器端筛选
• 使用 processResponse 扩展 ODataV4Adaptor 的自定义适配器
• 使用回调通过 AJAX Post 加载数据
• 使用 Query.addParams 向服务器传递额外参数
• 使用 actionFailure 事件处理失败操作
• 使用 UrlAdaptor 执行 CRUD 操作及服务器端控制器代码
• 使用 EditParams 实现 C# 控制器（Insert/Update/Remove 逻辑）
• 使用 WebApiAdaptor 和 dataBinding 转换集成 Google Calendar
• 支持 crossDomain 的 DataManager 配置

资源与分组

📄 阅读： references/resources.md

• 资源字段和属性（field、title、name、allowMultiple、dataSource、idField、textField、colorField 等）
• 资源数据绑定（本地 JSON 和远程 DataManager）
• 单个和多个资源分配
• 单级和多级层次资源分组
• 按日期进行资源分组（byDate 属性）
• 一对一资源分组（byGroupID: false）
• 使用 allowGroupEdit 在多个资源间共享事件
• 垂直与 Timeline 资源视图的实现

资源自定义

📄 阅读： references/resource-customization.md

• 为每个资源自定义工作时间
• 为每个资源自定义工作日
• 使用自定义资源标题模板
• 多列资源标题（仅限 Timeline）
• 使用 renderCell 事件自定义父资源单元格
• 为每个资源设置自定义 CSS 类
• 资源的展开/折叠状态（Timeline 视图）

时间配置（时间刻度与时区）

📄 阅读： references/timescale-timezone.md

• 时间刻度配置（enable、interval、slotCount、templates）
• 时段时长配置（30 分钟、15 分钟、10 分钟、5 分钟间隔）
• 隐藏时间刻度并自定义时间格式
• 主时段和次时段模板
• 使用 IANA 时区名称配置 Scheduler 时区
• 常见时区（America/New_York、Europe/London、Asia/Tokyo 等）
• 面向全球应用的 UTC 显示
• 使用 startTimezone 和 endTimezone 字段为每个事件单独设置时区
• 时区转换辅助方法（convert、removeLocalOffset、addLocalOffset）
• 事件编辑器中的时区下拉菜单
• 浏览器本地时区（不设置时区）
• 夏令时处理

自定义

📄 阅读： references/customization.md

• 使用 CSS 类设置单元格尺寸（所有视图的高度和宽度）
• workCells、monthCells、allDayCells、dateHeader 单元格的单元格模板
• 使用 elementType 检查的 RenderCell 事件（workCells、monthCells、dateHeader、resourceGroupCells 等）
• Month 视图的单元格标题模板
• Week/Day 视图的日期标题自定义
• 最小和最大日期限制
• 周末单元格自定义和高亮
• 自定义工作时间和工作日
• 多单元格和多行选择控制
• 使用 isSlotAvailable 方法检查时段是否可用

编辑器模板

📄 阅读： references/editor-template.md

• 事件编辑器概览和模式（Add、Edit、EditOccurrence、EditSeries）
• 使用 title 属性自定义编辑器字段标签
• 通过本地化（L10n）自定义编辑器按钮
• 字段验证规则（required、regex、自定义验证器）
• 向默认编辑器添加自定义字段
• 创建完全自定义的编辑器模板
• 快速信息模板自定义（标题、内容、页脚）
• 使用 readonly 或 popupOpen 事件禁用编辑器
• 编辑器字段类型和验证

标题栏配置

📄 阅读： references/header-configuration.md

• 标题栏自定义和样式设置
• 时间线视图的标题行（Year、Month、Date）
• 所有视图的日期标题模板
• 自定义工具栏操作和按钮
• 标题栏导航（上一项、今天、下一项）
• 隐藏/显示标题栏元素

CRUD 操作

📄 阅读： references/crud-operations.md

• 添加事件：addEvent 方法、批量添加多个事件
• 编辑事件：使用不同操作类型的 saveEvent 方法
• 删除事件：按 ID 或对象使用 deleteEvent、批量删除
• 使用 allowDragAndDrop 模块进行拖放
• 使用 allowResizing 模块调整事件大小
• 用于验证和取消操作的 ActionBegin 事件
• 用于操作后处理的 ActionComplete 事件
• 用于错误处理的 ActionFailure 事件
• 只读模式和单个事件的 readonly 标志
• 时间范围和时段可用性验证
• 使用 isSlotAvailable 防止重叠

剪贴板操作

📄 阅读： references/clipboard.md

• 使用 allowClipboard 属性启用剪贴板
• 复制/剪切/粘贴键盘快捷键（Ctrl+C、Ctrl+X、Ctrl+V）
• 编程接口（copy()、cut()、paste() 方法）
• 与自定义菜单项集成的上下文菜单
• 用于修改数据的粘贴前/后事件
• 行为说明（复制会创建副本，剪切会移动事件）
• 多次粘贴已复制的事件
• 支持跨应用粘贴

上下文菜单

📄 阅读： references/context-menu.md

• 使用 ContextMenu 组件集成自定义上下文菜单
• 使用 items 配置设置菜单
• 用于菜单显示逻辑的 BeforeOpen 事件
• 用于菜单操作处理的 OnSelect 事件
• 根据上下文（单元格或事件）显示/隐藏菜单项
• 带子项的重复事件菜单（编辑/删除实例/系列）
• 自定义菜单项（打印、导出、电子邮件等）
• 支持长按操作的移动端上下文菜单
• 使用 CSS 类自定义样式

本地化与无障碍

📄 阅读： references/localization-accessibility.md

• 区域设置配置和语言翻译（en、fr、de、ja 等）
• 用于自定义文本翻译的 L10n 类
• 使用 dateFormat 和 timeFormat 设置日期和时间格式（12/24 小时制、ISO、根据区域设置格式化）
• 支持阿拉伯语、希伯来语的 RTL（从右到左）布局
• 符合 WCAG 2.0 AA 级标准
• 键盘快捷键（Tab、Enter、Space、Delete、Ctrl+A 等）
• ARIA 属性（role、aria-label、aria-describedby）
• 屏幕阅读器支持和播报
• 焦点管理和可见的焦点指示器

高级功能

📄 阅读： references/advanced-features.md

• 在 Agenda/Timeline 视图中为大型数据集启用虚拟滚动
• 导出为 PDF 和 Excel 格式
• 使用自定义模板打印 Scheduler
• 状态持久化（enablePersistence），保存视图、日期和滚动位置
• 为重叠事件自动调整行高
• 用于自定义渲染的事件模板
• 快速信息模板
• 屏蔽时间段（标记不可用时间）
• 导入/导出 ICS 日历
• 鼠标悬停在事件上时显示工具提示
• 支持内联编辑
• 响应式自适应 UI

WebMCP 集成

📄 阅读： references/webmcp-integration.md

• 使用 enableWebMcp 启用 Scheduler WebMCP 工具注册
• 通过 webMcpSettings 配置工具选择、前缀和公开方式
• 通过 beforeWebMcpToolExecute 控制工具执行

重复编辑器和日历模式

📄 阅读： references/recurrence-editor-calendar-modes.md

• 重复编辑器和重复日期生成
• 公历和伊斯兰历模式
• 工作日、工作时间和自定义时间范围
• Scheduler 样式和主题
• 性能优化技巧
• 生产环境最佳实践

事件缓冲时间

📄 阅读： references/EventBuffer.md

• 为每个预约预留事件前后时间（准备、恢复、过渡）
• 激活 eventSettings.enableBuffer 并映射 bufferBefore / bufferAfter 字段
• 使用自定义 bufferTemplate 插槽渲染缓冲时间标签（图标、标签、时长）
• 在 allowOverlap=false 时检测包含缓冲时间的重叠，并通过 dragStop 进行验证
• 在 Day、Week、WorkWeek、TimelineDay、TimelineWeek 和 TimelineWorkWeek 视图中支持缓冲时间
• 何时使用或不使用 EventBuffer；约束、验证和最佳实践

自定义当前时间指示器

📄 阅读： references/CustomCurrentTimeIndicator.md

• showTimeIndicator 总开关和 currentTimeIndicatorSettings 行为对象
• 显示包含当前时间的自定义标签（showTime）、以前日期的范围（showPreviousDates）
• 设置指示器与预约单元格之间的堆叠顺序（onTop）
• 在 Day、Week、WorkWeek、TimelineDay、TimelineWeek 和 TimelineWorkWeek 视图中支持
• 使用 ref 和 computed 在运行时响应式切换设置面板
• 何时使用或不使用；约束、验证和最佳实践

快速入门示例

包含预约的基本 Scheduler

<template>
  <div id='app'>
    <ejs-schedule 
      height='550px' 
      :selectedDate='selectedDate'
      :eventSettings='eventSettings'>
    </ejs-schedule>
  </div>
</template>

<script setup>
import { provide } from "vue";
import { ScheduleComponent as EjsSchedule, Day, Week, WorkWeek, Month, Agenda } from '@syncfusion/ej2-vue-schedule';

const selectedDate = new Date(2024, 0, 15);
const eventSettings = {
  dataSource: [
    {
      Id: 1,
      Subject: 'Team Meeting',
      StartTime: new Date(2024, 0, 15, 10, 0),
      EndTime: new Date(2024, 0, 15, 11, 30),
      IsAllDay: false
    },
    {
      Id: 2,
      Subject: 'Project Review',
      StartTime: new Date(2024, 0, 16, 14, 0),
      EndTime: new Date(2024, 0, 16, 15, 30),
      IsAllDay: false
    }
  ]
};

// Inject required view modules
provide('schedule', [Day, Week, WorkWeek, Month, Agenda]);
</script>

<style>
@import "../node_modules/@syncfusion/ej2-material3-theme/styles/schedule/index.css";
</style>

常见模式

带例外情况的重复事件

<script setup>
const eventSettings = {
  dataSource: [
    {
      Id: 1,
      Subject: 'Daily Standup',
      StartTime: new Date(2024, 0, 15, 9, 0),
      EndTime: new Date(2024, 0, 15, 9, 30),
      RecurrenceRule: 'FREQ=DAILY;INTERVAL=1;COUNT=10',
      RecurrenceException: '20240117T090000Z,20240119T090000Z'
    }
  ]
};
</script>

资源分组

<template>
  <ejs-schedule 
    :eventSettings='eventSettings'
    :group='group'>
    <e-resources>
      <e-resource 
        field='RoomId' 
        title='Room' 
        name='Rooms'
        :dataSource='roomData'
        textField='Name' 
        idField='Id' 
        colorField='Color'>
      </e-resource>
    </e-resources>
  </ejs-schedule>
</template>

<script setup>
const roomData = [
  { Id: 1, Name: 'Room A', Color: '#ffaa00' },
  { Id: 2, Name: 'Room B', Color: '#357cd2' }
];

const group = { resources: ['Rooms'] };
</script>

自定义字段映射

<script setup>
const eventSettings = {
  dataSource: appointmentData,
  fields: {
    id: 'EventId',
    subject: { name: 'Title' },
    startTime: { name: 'From' },
    endTime: { name: 'To' },
    location: { name: 'Place' },
    description: { name: 'Notes' },
    isAllDay: { name: 'FullDay' }
  }
};
</script>

时间线视图配置

<template>
  <ejs-schedule 
    :selectedDate='selectedDate'
    :eventSettings='eventSettings'>
    <e-views>
      <e-view option='TimelineDay'></e-view>
      <e-view option='TimelineWeek'></e-view>
      <e-view option='TimelineMonth'></e-view>
    </e-views>
  </ejs-schedule>
</template>

<script setup>
import { provide } from "vue";
import { TimelineViews, TimelineMonth } from '@syncfusion/ej2-vue-schedule';

provide('schedule', [TimelineViews, TimelineMonth]);
</script>

事件缓冲时间

<template>
  <ejs-schedule
    :selectedDate="selectedDate"
    :currentView="currentView"
    :allowOverlap="false"
    :eventSettings="eventSettings">
    <e-views>
      <e-view option="Day"></e-view>
      <e-view option="TimelineDay"></e-view>
      <e-view option="TimelineWeek"></e-view>
    </e-views>

    <template v-slot:bufferTemplate="{ data }">
      <span class="buffer-duration">
        {{ data.bufferType === 'before'
            ? data.data.bufferBefore
            : data.data.bufferAfter }} min
      </span>
    </template>
  </ejs-schedule>
</template>

<script setup>
import { provide } from "vue";
import {
  ScheduleComponent as EjsSchedule,
  ViewDirective as EView,
  ViewsDirective as EViews,
  Day,
  TimelineViews
} from '@syncfusion/ej2-vue-schedule';

const eventSettings = {
  enableBuffer: true,
  dataSource: [
    {
      Id: 1,
      Subject: 'Knee Replacement',
      StartTime: new Date(2024, 0, 15, 9, 0),
      EndTime: new Date(2024, 0, 15, 10, 30),
      IsAllDay: false,
      bufferBefore: 30, // 30 minutes preparation
      bufferAfter: 45   // 45 minutes recovery
    }
  ],
  bufferTemplate: 'bufferTemplate',
  fields: {
    bufferBefore: { name: 'bufferBefore' },
    bufferAfter: { name: 'bufferAfter' }
  }
};

provide('schedule', [Day, TimelineViews]);
</script>

自定义当前时间指示器

<template>
  <ejs-schedule
    width="100%"
    height="550px"
    :selectedDate="currentDate"
    currentView="TimelineWeek"
    :showTimeIndicator="showTimeIndicator"
    :currentTimeIndicatorSettings="currentTimeIndicatorSettings"
    :timeScale="{ enable: true }"
    :eventSettings="eventSettings">
    <e-views>
      <e-view option="Day"></e-view>
      <e-view option="Week"></e-view>
      <e-view option="WorkWeek"></e-view>
      <e-view option="TimelineDay"></e-view>
      <e-view option="TimelineWeek"></e-view>
      <e-view option="TimelineWorkWeek"></e-view>
    </e-views>
  </ejs-schedule>
</template>

<script setup>
import { ref, computed, provide } from "vue";
import {
  ScheduleComponent as EjsSchedule,
  ViewsDirective as EViews,
  ViewDirective as EView,
  Day,
  Week,
  WorkWeek,
  TimelineViews
} from '@syncfusion/ej2-vue-schedule';

const currentDate = new Date();

const showTimeIndicator = ref(true);
const showTime = ref(true);
const showPreviousDates = ref(true);
const onTop = ref(true);

const currentTimeIndicatorSettings = computed(() => ({
  showTime: showTime.value,
  showPreviousDates: showPreviousDates.value,
  onTop: onTop.value
}));

const eventSettings = { dataSource: [] };

provide('schedule', [Day, Week, WorkWeek, TimelineViews]);
</script>

关键属性和事件

基本属性

属性	类型	描述
selectedDate	Date	Scheduler 中当前选定的日期
currentView	string	当前视图（Day、Week、Month、Agenda 等）
eventSettings	object	事件数据源和字段配置
views	array	要显示的视图集合
startHour	string	日/周视图的开始时间（例如，'08:00'）
endHour	string	日/周视图的结束时间（例如，'18:00'）
workDays	number[]	工作日（0=星期日，1=星期一等）
timeScale	object	时间段配置（interval、slotCount）
group	object	资源分组配置
readonly	boolean	为 true 时禁止 CRUD 操作
allowDragAndDrop	boolean	启用事件拖放
allowResizing	boolean	启用事件大小调整
allowMultiDrag	boolean	启用多事件拖动选择
allowClipboard	boolean	启用剪贴板操作
timezone	string	Scheduler 时区（例如，'America/New_York'）

核心事件

事件	描述
actionBegin	在任何 CRUD 操作（添加／编辑／删除）之前触发
actionComplete	CRUD 操作成功后触发
actionFailure	CRUD 操作失败时触发
eventClick	单击事件时触发
eventDoubleClick	双击事件时触发
cellClick	单击单元格时触发
cellDoubleClick	双击单元格时触发
popupOpen	编辑器／快速信息弹出窗口打开前触发
popupClose	弹出窗口关闭时触发
dragStart	开始拖动事件时触发
drag	拖动事件期间触发
dragStop	停止拖动事件时触发
resizeStart	开始调整事件大小时触发
resizing	调整事件大小期间触发
resizeStop	停止调整事件大小时触发
dataBinding	数据绑定前触发
dataBound	数据绑定完成后触发
beforePaste	粘贴剪贴板内容前触发

核心方法

方法	描述
addEvent(data)	向日程组件添加新事件
saveEvent(data, action)	保存已修改的事件
deleteEvent(id/object)	按 ID 或对象删除事件
getEvents(startDate, endDate)	获取日期范围内的事件
getEventDetails(element)	从元素获取事件详情
openEditor(data, action)	以编程方式打开编辑器窗口
closeEditor()	关闭编辑器窗口
refreshEvents()	刷新所有事件
scrollTo(hour)	在日／周视图中滚动到指定小时
getCurrentViewDates()	返回当前视图的日期集合

安装

安装 Syncfusion Vue Schedule 软件包：

npm install @syncfusion/ej2-vue-schedule --save

导入所需的 CSS 主题：

import "@syncfusion/ej2-material3-theme/styles/schedule/index.css";

模块注入

Scheduler 需要注入视图模块。只注入所需的视图：

import { 
  Day, Week, WorkWeek, Month, Year, Agenda, MonthAgenda,
  TimelineViews, TimelineMonth, TimelineYear,
  DragAndDrop, Resize
} from '@syncfusion/ej2-vue-schedule';

provide('schedule', [Day, Week, Month, Agenda, DragAndDrop]);

相关组件

• Recurrence Editor：用于创建重复规则的独立组件
• DatePicker/DateRangePicker：用于在自定义编辑器中选择日期
• TimePicker：用于在自定义编辑器中选择时间
• DropDownList：用于在自定义编辑器中选择资源

最佳实践

1. 模块注入：仅注入实际使用的视图模块，以减小打包体积
2. 字段映射：当数据结构与默认结构不同时，使用自定义字段映射
3. 性能：对于大型数据集（时间线视图），启用虚拟滚动
4. 时区：使用多个时区时，明确设置 Scheduler 时区
5. 事件 ID：始终为事件提供唯一 ID，以确保 CRUD 操作正常
6. 验证：使用 actionBegin 事件在保存前验证数据
7. 模板：使用模板自定义事件渲染和单元格
8. 无障碍：启用键盘导航并提供恰当的 ARIA 标签
9. 响应式：使用 CSS 媒体查询调整 Scheduler 在移动设备上的显示
10. 状态管理：使用状态持久化保存用户偏好设置
11. 自定义当前时间指示器：使用 currentTimeIndicatorSettings 设置行为（标签、过去日期、堆叠顺序），并使用 CSS 设置视觉样式；不要将该设置对象视为样式 API

故障排除

事件不显示：验证事件字段是否与调度程序预期的字段名称匹配，或在 eventSettings 中使用字段映射。

视图未加载：确保通过 provide 方法正确注入所需的视图模块。

拖放不起作用：导入并注入 DragAndDrop 模块。

时区问题：设置调度程序的 timezone 属性，并确保事件时间格式正确。

自定义字段未保存：在 eventSettings.fields 配置中映射自定义字段。

性能问题：对于包含大量事件或资源的时间线视图，启用虚拟滚动。

未从服务器加载数据：验证 CORS 设置、DataManager 适配器配置，以及浏览器 DevTools 中的网络请求。

未生成重复事件实例：检查 RecurrenceRule 语法（FREQ、INTERVAL、COUNT、UNTIL 参数），并验证规则是否有效。

缓冲区胶囊未渲染：确认 eventSettings.enableBuffer 为 true，在 eventSettings.fields 下映射了 bufferBefore 和 bufferAfter 字段，并且事件的这些字段包含数值。

当前时间指示器不可见：确认 showTimeIndicator 为 true，当前视图包含时间轴（Day、Week、WorkWeek、TimelineDay、TimelineWeek、TimelineWorkWeek），且 timeScale.enable 设置为 true。该指示器不会在 Month、Year 或 Agenda 视图中渲染。