syncfusion-javascript-scheduler

实现 Syncfusion TypeScript Scheduler

一份全面的指南，介绍如何实现 Syncfusion EJ2 TypeScript Schedule（Scheduler）组件——一款功能齐全的日历和预约管理 UI，支持多种视图、重复事件、资源分组、拖放、内联编辑和数据导出。

何时使用此技能

• 在 TypeScript 项目中设置并初始化 Scheduler
• 配置日历视图（Day、Week、WorkWeek、Month、Year、Agenda、Timeline 等变体）
• 将本地或远程预约数据绑定到 Scheduler
• 为事件实现 CRUD（创建、读取、更新、删除）
• 使用重复事件和 RecurrenceEditor
• 配置多个资源和分组视图
• 自定义事件编辑器弹出窗口或快速信息模板
• 将 Scheduler 数据导出为 Excel、CSV 或 iCalendar（.ics）
• 为全球用户群处理时区
• 进行样式设置、主题配置并确保符合无障碍要求

---

文档和导航指南

入门与模块注入

📄 阅读： references/getting-started.md

• 软件包依赖项和 npm 安装
• CSS 导入和主题配置
• 使用 Schedule.Inject() 注入模块
• 初始化 Scheduler 并将其附加到 DOM
• 使用 eventSettings.dataSource 填充预约
• 设置 selectedDate 和 currentView
• 使用 views 数组为各个视图单独配置

视图配置

📄 阅读： references/views.md

• 全部 12 种视图类型及其模块要求
• 各视图选项（startHour、endHour、timeScale、showWeekend 等）
• 使用 interval 和 displayName 扩展视图
• 时间线视图方向和 Agenda 视图选项

预约与重复事件

📄 阅读： references/appointments.md

• 普通、跨时段、全天和重复事件类型
• iCal RecurrenceRule 字符串语法（FREQ、BYDAY、COUNT、UNTIL 等）
• 重复事件例外，以及编辑单个或后续事件
• 内置事件字段参考表
• 通过 eventSettings.fields 映射自定义字段
• 使用 allowOverlap 防止重叠，使用 sortComparer 自定义排序

数据绑定

📄 阅读： references/data-binding.md

• 通过 eventSettings.dataSource 绑定本地 JSON 数组
• 使用 DataManager 和 ODataV4Adaptor 进行远程绑定
• 使用 ej2-base Ajax 的 AJAX 加载模式
• 使用 includeFiltersInQuery 在服务器端按日期范围筛选
• 使用 eventSettings.query 传递查询参数
• 通过 dataBinding 事件集成 Google Calendar API

CRUD 操作

📄 阅读： references/crud-actions.md

• 通过编辑器、快速弹出窗口或 addEvent() 方法创建事件
• 使用 saveEvent() 和 deleteEvent() 更新和删除事件
• 使用 UrlAdaptor + crudUrl 在服务器端执行 CRUD
• 使用 validation 属性验证字段（必填、正则表达式）
• actionBegin / actionComplete 生命周期事件
• 启用只读模式

编辑器模板与快速信息

📄 阅读： references/editor-template.md

• 通过 popupOpen 自定义默认编辑器字段
• 使用 editorTemplate 完全替换编辑器
• editorHeaderTemplate 和 editorFooterTemplate
• 使用 quickInfoTemplates 自定义快速信息弹出窗口
• showQuickInfo 开关和 closeEditor() 方法
• 使用 timezoneDataSource 自定义时区下拉列表

资源与分组

📄 阅读： references/resources.md

• 使用 resources 属性和字段映射定义资源
• 通过 group.resources 进行单级和多级分组
• 使用 group.byDate 按日期分组
• 使用 allowMultiple 为事件分配多个资源
• 为资源设置专属工作时间、颜色和 CSS 类
• 在 Timeline 视图中展开资源行

工作日、工作时间与时间范围

📄 阅读： references/working-days-timescale.md

• workDays、showWeekend、showWeekNumber、firstDayOfWeek
• workHours 的高亮、开始和结束配置
• 使用 startHour / endHour 设置可见时间范围
• 使用 interval 和 slotCount 配置 timeScale
• 主/次时间段模板
• 使用 scrollTo() 以编程方式滚动时间

单元格、标题与视图自定义

📄 阅读： references/cell-header-customization.md

• 使用 elementType 条件配置 cellTemplate
• 使用 renderCell 事件针对性地修改单元格
• 使用 cellHeaderTemplate 设置 Month 视图的日期标题
• 标题栏：showHeaderBar、toolbarItems、dateHeaderTemplate
• Timeline 的 headerRows 属性，可设置 Year/Month/Week/Date/Hour 行
• 使用 minDate / maxDate 限制日期范围

导出与打印

📄 阅读： references/exporting.md

• 使用 ExportOptions（fileName、fields、customData 等）调用 exportToExcel()
• 通过 exportType: 'csv' 导出 CSV
• 使用 excelExport 事件在导出前自定义内容
• 使用 exportToICalendar() 导出为 .ics 格式
• 从文件 Blob 导入：importICalendar()
• 使用 print() 方法和 beforePrint 事件打印

时区处理

📄 阅读： references/timezone.md

• timezone 属性（IANA 时区字符串）
• 单个事件的 StartTimezone / EndTimezone 字段
• Timezone 工具类：offset()、convert()、add()、remove()
• 使用 timezoneData 自定义时区下拉菜单
• 面向全球/多地区团队的 UTC 模式

重复规则编辑器

📄 阅读： references/recurrence-editor.md

• 独立 RecurrenceEditor 组件的设置
• frequencies 和 endTypes 属性配置
• 使用 change 事件获取生成的规则字符串
• setRecurrenceRule() 和 getRecurrenceDates() 方法

样式与主题

📄 阅读： references/scheduler-styling.md

• 所有 Scheduler 元素的 CSS 类选择器参考
• 按视图限定的选择器（.e-vertical-view、.e-month-view 等）
• 状态类：选中单元格、选中预约
• Timeline 视图的资源行选择器
• 阻止和只读预约的样式

高级功能

📄 阅读： references/advanced-features.md

• 使用 ContextMenu 集成上下文菜单
• 剪贴板：allowClipboard、cut()、copy()、paste()、beforePaste 事件
• 使用 allowVirtualScrolling 和 enableLazyLoading 实现虚拟滚动
• 用于 Timeline 和 Month 视图的 rowAutoHeight
• 使用 enablePersistence 持久化状态
• 通过 calendarMode: 'Islamic' 使用伊斯兰历/希吉来历
• Scheduler 尺寸：height 和 width
• 无障碍、WCAG 2.2、键盘快捷键

---

快速开始

import { Schedule, Day, Week, WorkWeek, Month, Agenda } from '@syncfusion/ej2-schedule';

// Inject required view modules
Schedule.Inject(Day, Week, WorkWeek, Month, Agenda);

let scheduleObj: Schedule = new Schedule({
    height: '550px',
    selectedDate: new Date(2018, 1, 15),
    currentView: 'Week',
    eventSettings: {
        dataSource: [
            {
                Id: 1,
                Subject: 'Team Meeting',
                StartTime: new Date(2018, 1, 15, 10, 0),
                EndTime: new Date(2018, 1, 15, 12, 0)
            }
        ]
    }
});
scheduleObj.appendTo('#Schedule');

/* In styles.css */
@import '../../node_modules/@syncfusion/ej2-base/styles/fluent2.css';
@import '../../node_modules/@syncfusion/ej2-buttons/styles/fluent2.css';
@import '../../node_modules/@syncfusion/ej2-calendars/styles/fluent2.css';
@import '../../node_modules/@syncfusion/ej2-dropdowns/styles/fluent2.css';
@import '../../node_modules/@syncfusion/ej2-inputs/styles/fluent2.css';
@import '../../node_modules/@syncfusion/ej2-navigations/styles/fluent2.css';
@import '../../node_modules/@syncfusion/ej2-popups/styles/fluent2.css';
@import '../../node_modules/@syncfusion/ej2-schedule/styles/fluent2.css';

---

常见模式

模式 1：切换到隐藏周末的 Month 视图

import { Schedule, Month } from '@syncfusion/ej2-schedule';

Schedule.Inject(Month);
let scheduleObj: Schedule = new Schedule({
    height: '550px',
    currentView: 'Month',
    showWeekend: false,
    eventSettings: { dataSource: [...] }
});
scheduleObj.appendTo('#Schedule');

模式 2：自定义字段名称

let scheduleObj: Schedule = new Schedule({
    height: '550px',
    eventSettings: {
        dataSource: myData,
        fields: {
            id: 'EventId',
            subject: { name: 'Title' },
            startTime: { name: 'From' },
            endTime: { name: 'To' },
            isAllDay: { name: 'AllDay' }
        }
    }
});
scheduleObj.appendTo('#Schedule');

模式 3：以编程方式创建事件

let eventData: Object = {
    Id: 10,
    Subject: 'New Event',
    StartTime: new Date(2018, 1, 15, 14, 0),
    EndTime: new Date(2018, 1, 15, 16, 0)
};
scheduleObj.addEvent(eventData);

模式 4：按资源分组的 Timeline

import { Schedule, TimelineViews } from '@syncfusion/ej2-schedule';

Schedule.Inject(TimelineViews);
let scheduleObj: Schedule = new Schedule({
    height: '550px',
    currentView: 'TimelineWeek',
    group: { resources: ['Rooms'] },
    resources: [{
        field: 'RoomId',
        title: 'Room',
        name: 'Rooms',
        dataSource: [
            { RoomText: 'Room 1', Id: 1, RoomColor: '#cb6bb2' },
            { RoomText: 'Room 2', Id: 2, RoomColor: '#56ca85' }
        ],
        textField: 'RoomText',
        idField: 'Id',
        colorField: 'RoomColor'
    }],
    eventSettings: { dataSource: [...] }
});
scheduleObj.appendTo('#Schedule');

---

关键属性参考

属性	类型	描述
height	string	日程表高度（'550px'、'100%'、'auto'）
width	string	日程表宽度
selectedDate	Date	当前显示的日期
currentView	string	当前视图名称
views	ViewsModel[]	各视图的配置数组
eventSettings	EventSettingsModel	数据源和字段映射
group	GroupModel	资源分组配置
resources	ResourcesModel[]	资源定义
workDays	number[]	要显示的星期几（0=周日–6=周六）
workHours	WorkHoursModel	工作时间高亮和范围
showWeekend	boolean	显示/隐藏周六和周日
timezone	string	用于显示的 IANA 时区字符串
enablePersistence	boolean	在 localStorage 中持久化状态
readonly	boolean	禁用所有 CRUD 交互
allowClipboard	boolean	启用事件的剪切/复制/粘贴