简介FullCalendar 1.5.3 完整资源包专门面向需要快速搭建网页日历、日程管理功能的 Web 开发者尤其适合前端入门者与需要集成时间组件的项目。该库支持日、周、月及列表视图并可与 PHP、ASP.NET 等后端进行事件数据交互实用性很强。压缩包共 35 个文件包含 5 个 JS 核心脚本、3 个 CSS 样式表、8 个 HTML 示例页面、14 个 PNG 图标资源以及 PHP 示例、数据库文件和说明文档整体仅 159KB轻量且便于部署。资源中附带了 basic-views、agenda-views、external-dragging、gcal 等典型 demo配合 jquery 脚本即可快速理解初始化、事件源绑定和视图切换等关键用法同时包含 GPL/MIT 许可文件方便商用或二次开发时规避授权风险。目前已有 175 人学习对想尽快上手 FullCalendar 的开发者来说是一份紧凑实用的参考包。 FullCalendar这个名字做前端的老哥们应该都不陌生。前阵子接了个门店预约系统的改造需求客户嫌原来那套用多个日期下拉框选择的交互太反人类用户想看某一天哪些时段能约得来回切换表单控件别说顾客了运营自己都嫌麻烦。我当时的第一个念头就是放弃自己吭哧吭哧写日历组件直接上FullCalendar——它是一个开源的JavaScript日历库专门用来解决”时间、事件、视图”这三者的展示与交互问题。一张日历页面可以在月视图、周视图、日视图之间自由切换事件可以拖动、缩放、点击甚至可以直接点空白日期来新建排期。对于预约、排班、日程管理、课程表这类业务场景这基本是现成的正确答案。这篇就围绕我在实际项目里用FullCalendar搭排期系统的过程把选型逻辑、版本坑、数据接入方式、交互定制的细节和生产环境常见的坑位一次性聊透适合准备在业务里上日历组件、或者已经在用但经常被各种细节卡住的开发者参考。1. 为什么是FullCalendar业务日历的选型复盘1.1 需求来自一张难用的排班页面先还原一下当时的业务现场。门店预约系统里顾客需要选择”哪天、哪个时间段、哪个服务人员”。产品经理提的需求很朴素能不能像手机日历一样一眼看过去就知道哪天约满了、哪天还剩哪些时段。仅这一个诉求就把原生input[typedate]判了死刑。它只能选一个日期看不到某天的事件分布更谈不上多视图切换。用组件库自带的Calendar组件比如Ant Design的日历如果你项目刚好是React生态用起来还行但视图类型依然受限月视图下的格子想塞进按小时划分的时段列表基本要自己重写渲染逻辑。FullCalendar最核心的价值在于它不是一个”日期选择器”而是一个完整的”日程渲染引擎”。它内置了月份、周、日、列表四种视图模型每种视图都自带一套时间轴计算逻辑从周起始日到跨月跨周的边界规则这些琐碎又容易出错的时间算法它已经替你处理好了。1.2 手写日历和组件库日历差在哪我也见过不少团队选择自己写日历说实话如果只是展示”某月某日是节日”手写一个表格并不难难的是那些藏在水面下的边界问题。某个月第一天是周几一个月有多少天这些是基础中的基础。一旦牵涉到跨周、跨月的事件显示比如一个持续三天的事件需要在月视图里同时出现在三个格子里并且要连成一条视觉上连续的色块事件块如何跨格子渲染、如何计算高度、如何避免遮挡自己去实现就会非常痛苦。FullCalendar对事件的渲染策略是内置的。一个跨越多天的事件在月视图里会自动拆分成多个片段并保持样式联动在周视图和日视图里则按时间轴长度渲染成对应高度的色块。这背后涉及的时间算法和DOM渲染逻辑自己从零做工作量论周算用现成库配置两个字段就搞定了。1.3 选型结论什么时候可以放心用它对比下来我最终选择FullCalendar核心原因有四条免费开源MIT协议商用没有授权成本。框架无关原生JavaScript能用官方同时提供了React和Vue的封装版本现有技术栈无论是什么都能接入。内置Interaction插件后点击日期、框选时间段、拖拽事件、调整事件时长这些操作都是开箱即用的交互能力。事件数据是纯JSON结构和后端接口对接非常顺畅不存在什么私有协议。当然它也有适用边界。如果你只是需要一个单纯的日期选择器选日期然后提交表单那用它属于大炮打蚊子。更合适的场景是页面主体本身就是一张日历用户需要在日历上完成查看、新增、拖拽、改期、筛选等操作这种”日历即工作台”的需求用它是最稳妥的选择。2. 开工前先搞懂版本与初始化2.1 版本选择从v3到v6别照着老教程抄FullCalendar的版本迭代很折腾人网上搜到的教程大量还停留在v3甚至更早的jQuery时代。v3版本依赖jQuery和moment.js初始化写法是$(#calendar).fullCalendar({...})如果你照着这种代码去配现在的版本连对象都拿不到直接报错。v4是一次彻底的重写去掉了jQuery依赖改成了ES Module的插件化架构。v5继续沿用了这套架构。也就是说你要用月视图就装fullcalendar/daygrid要用周视图和日视图的时间轴就装fullcalendar/timegrid需要交互能力就装fullcalendar/interaction不再是一个大杂烩文件一把梭。这也是我目前主用的版本线下面的示例都以v5/v6的写法为准。如果项目要新开建议直接看官方文档的最新版不要再看三年前的文章。2.2 安装、引入与第一个渲染以npm方式安装为例核心包加三个常用插件npm install fullcalendar/core fullcalendar/daygrid fullcalendar/timegrid fullcalendar/interaction然后在你的模块里初始化import { Calendar } from fullcalendar/core; import dayGridPlugin from fullcalendar/daygrid; import timeGridPlugin from fullcalendar/timegrid; import interactionPlugin from fullcalendar/interaction; const calendarEl document.getElementById(calendar); const calendar new Calendar(calendarEl, { plugins: [dayGridPlugin, timeGridPlugin, interactionPlugin], initialView: dayGridMonth, headerToolbar: { left: prev,next today, center: title, right: dayGridMonth,timeGridWeek,timeGridDay } }); calendar.render();这里有个非常容易踩的坑plugins数组不能漏。很多人初始化后页面空白第一反应是Dom元素ID写错了实际往往是插件没注册。dayGrid是月视图的基础插件timeGrid负责周视图和日视图interaction负责点击、拖拽、框选这些交互。只写一个Calendar构造器而不注册插件FullCalendar会静默失败页面上一片空白没有任何报错。2.3 中文本地化与基础配置默认界面全是英文必须先做本地化配置。locale字段设成zh-cn但前提是要引入对应的语言包import zhLocale from fullcalendar/core/locales/zh-cn; const calendar new Calendar(calendarEl, { locale: zh-cn, // 如果引入的是具名locale也可以写 locale: zhLocale });语言配置会直接影响星期表头、月份标题、按钮文字以及事件时间显示格式。比如不配的话“今天”按钮显示为Today月份标题是英文排班人员看到全英文界面就直接打回来了。初始化时还有几个基础配置我个人习惯第一时间设置好firstDay: 1让周一作为一周的开始符合国内业务习惯。height: auto避免容器高度写死之后不同月份行数变化导致页面跳动。nowIndicator: true在当前时间位置显示一条红色指示线周视图和日视图里很有用。slotMinTime和slotMaxTime如果门店营业时间是9点到21点就把时间轴范围设成09:00:00到21:00:00避免用户看到一个凌晨三点的时间格子。3. 数据接入的四种方式与性能取舍3.1 events配置项的三种形态FullCalendar的事件数据源是用events字段来配置的它有三种写法。第一种是直接给一个数组适合测试和静态数据第二种是给一个JSON接口地址字符串它会自动请求这个URL并把返回值当作事件列表第三种是传一个回调函数接收当前视图范围作为参数自己控制数据获取逻辑。在这三种方式里我最不推荐的是第二种——直接把后端接口地址写进去。它有一个隐患FullCalendar会在视图切换、数据刷新时频繁请求这个URL而你完全无法控制请求参数也无法对异常情况做统一处理。接口返回格式稍微不规范事件就全丢排查起来很费劲。3.2 用回调函数做按需加载我推荐的做法是使用回调函数。它最大的价值是天然实现了按需加载用户当前看到的是哪一周就只请求这一周的数据接口只返回这一周的事件而不是把全年的数据一次性塞到前端。const calendar new Calendar(calendarEl, { // ... events(info, successCallback, failureCallback) { fetch(/api/events?start${info.startStr}end${info.endStr}) .then(res { if (!res.ok) throw new Error(Network error); return res.json(); }) .then(data successCallback(data)) .catch(err failureCallback(err)); } });info.startStr和info.endStr是当前视图的起止时间字符串默认是ISO格式后端拿到之后可以直接用日期解析库处理。这个回调会在初次渲染、切换视图、点击今天按钮时自动触发所以用户永远不会看到超出当前视野范围的事件数据后端接口的压力也小很多。3.3 数据格式与时区细节后端返回的事件数组每个事件对象至少要包含start字段title字段和end字段按需给。这里有一个容易出问题的细节全天事件和时段事件的表达方式不同。一个全天事件应该写成{ id: 1001, title: 公休, start: 2025-06-10, allDay: true, backgroundColor: #f59e0b }而一个有时段的预约应该是{ id: 1002, title: 张小姐-护理, start: 2025-06-10T14:00:00, end: 2025-06-10T15:00:00, allDay: false }时区是另外一个特别隐蔽的坑。FullCalendar默认会把时间字符串解析为本地时区如果你的接口返回的是带时区偏移的UTC时间或者是YYYY-MM-DD HH:mm:ss这种不带时区标记的格式浏览器的解析行为可能跟你预期的差八个小时事件显示到前一天或者后一天去了。这个我在后面踩坑清单部分专门展开说这里先记住一个原则前后端约定好所有时间要么统一用ISO 8601带偏移的格式要么在FullCalendar初始化时显式设置timeZone: local让解析行为可预期。3.4 事件增删改不要整包刷新数据接入之后前端对事件的增删改也有一套推荐姿势。很多初学者习惯在操作完数据之后调用calendar.refetchEvents()这个方法会把所有事件源重新请求一遍数据量小的时候感觉不出来数据量一大画面会明显闪烁而且用户的拖拽状态、弹窗状态全都被打断。更好的做法是使用实例方法新增事件用calendar.addEvent({ title, start, end, ... })它会立即把新事件渲染到当前视图上。删除事件用event.remove()直接从数据源和视图里同时移除。修改事件属性用event.setProp(title, 新标题)或event.setExtendedProp(customField, value)。这些方法只操作当前事件对象不会触发全量请求交互反馈也更快。配合后端接口通常的做法是前端先调用接口持久化数据接口返回成功后再调用这些方法更新视图接口失败则不做任何操作这样视图和数据保持一致。4. 把日期选择变成业务流程的一部分4.1 点击空白创建排期FullCalendar最有价值的交互能力之一是用户可以直接在日历上点选空白区域来创建事件。要开启这个能力必须引入interaction插件并且配置selectable: true。当用户点击日历空白格子或者用鼠标拖拽框选一个时间段时会触发select回调。回调参数里包含选择的起始时间、结束时间以及当前视图类型。这个回调非常适合用来弹出新增排期的表单select(info) { // 弹出表单把 info.startStr 和 info.endStr 作为默认排期时间 openBookingModal(info.start, info.end); }对应的还有dateClick回调它比select更轻量在点击某个日期时立即触发不要求用户拖拽。这两种交互可以共存常见做法是单击弹新建表单拖拽框选快捷创建连续排期。4.2 限制可选范围与营业时段日历如果允许用户选任何时间业务上一定会出问题。比如预约系统用户不应该能选择过去的时间也不应该能选择半夜三点的时段。这种约束用selectAllow回调来控制selectAllow(info) { const start info.start; const now new Date(); return start.getTime() now.getTime(); }营业时段的限制则可以结合businessHours配置它专门用来定义一周里的可预约时间段。例如周一到周五9点到18点可以预约businessHours: { daysOfWeek: [1, 2, 3, 4, 5], startTime: 09:00, endTime: 18:00 }这里有个细节要注意businessHours只是高亮显示营业时间区域它本身不会阻止用户创建非营业时间的事件。要真正限制选择还是得用selectAllow去判断。把这两者配合起来用高亮是一层视觉提示selectAllow是硬性拦截缺一不可。4.3 拖拽改期与冲突校验排期系统的另一个核心交互是拖拽改期。用户把一个预约从周三拖到周四触发eventDrop回调你需要在这个回调里同步到后端。但这里的坑在于回调的参数结构eventDrop(info) { const event info.event; const oldStart info.oldEvent.start; const oldEnd info.oldEvent.end; // 先调用接口更新排期时间 updateBooking(event.id, { start: event.startStr, end: event.endStr }).catch(() { // 接口失败要回滚 info.revert(); }); }info.event是拖拽后的事件对象它已经在视图里移动过了info.oldEvent保存了拖拽前的快照用于失败回滚。记住一个铁律接口调用前不要做任何乐观更新视图的移动是FullCalendar自己驱动的你要负责的是把变更持久化。接口失败时调用info.revert()把事件拖回原位同时给出提示让用户知道这次操作没有生效。业务上如果存在时间冲突校验比如某个服务人员同一个时段只能接一个单应该在接口返回冲突错误时不仅回滚拖拽还要用calendar.getEventById()定位到那个已经存在的事件高亮闪烁一下提示用户具体冲突在哪个时段。这个细节做得好能大幅减少运营人员的沟通成本。5. 皮相和移动端让日历融入业务系统5.1 修改头部按钮与周末样式组件默认的头部工具栏可以自定义但样式上还是需要二次处理才能融入现有设计系统。头部工具栏的headerToolbar配置里左侧、中间、右侧的按钮集合可以自由组合。比如我们项目里要去掉“今天”按钮把视图切换放到侧边栏里headerToolbar: { left: prev,next, center: title, right: }周末和高亮色块的定制FullCalendar自己有CSS变量体系。比如月视图里今天的背景色、周末的字体颜色都可以用普通CSS覆盖.fc .fc-day-today { background-color: #fff7e6 !important; } .fc .fc-day-sat .fc-daygrid-day-number, .fc .fc-day-sun .fc-daygrid-day-number { color: #e06060; }这里强烈建议用!important或者提高选择器的优先级FullCalendar的样式优先级不低不加一行代码改不动的情况经常出现。5.2 暗色主题适配业务系统如果走暗色路线日历默认的白底配色会显得非常突兀。FullCalendar把常用颜色都拆成了CSS变量看fc-theme-standard这个类名下的定义就能找到通常用的有以下这些.fc { --fc-border-color: #373a40; --fc-page-bg-color: #1f2328; --fc-today-bg-color: rgba(255, 220, 100, 0.15); --fc-event-bg-color: #3b82f6; --fc-event-border-color: #3b82f6; --fc-now-indicator-color: #ff6b6b; }覆盖之后日历的边框、背景、事件色块、今天高亮、当前时间指示线的颜色整体切换比逐个类名去改省心得多。暗色主题下注意事件文字颜色也要同步调亮否则深色背景配深色文字内容根本看不清。5.3 移动端视口与触摸交互预约系统的C端用户大量来自手机端FullCalendar的默认桌面交互在手机上体验很差。移动端的适配我一般从三个维度处理。第一根据视口宽度切换默认视图。手机屏幕显示月视图格子里的文字挤得没法看更合适的默认视图是列表视图if (window.innerWidth 768) { calendar.changeView(listWeek); }第二控制事件在移动端的显示数量。月视图里一个格子塞进五个以上的事件基本就变成一坨色块了用dayMaxEvents: 3配合moreLinkClick: day超出的部分显示“2更多”点击后跳转日视图查看完整列表体验会好很多。第三触摸拖拽。移动端的拖拽事件在FullCalendar里默认是支持的但灵敏度跟桌面不一样。实测下来要给eventDragMinDistance设置一个稍微大一点的值比如10像素避免用户上下滑动页面时误触发拖拽改期。6. 生产环境里的高频坑位清单6.1 界面白屏和样式错乱白屏和样式错乱是新手最容易碰到的问题几乎都和CSS没有引入有关。FullCalendar的组件逻辑和样式是分离的不能只安装JS包就完事。至少需要引入fullcalendar/core的全局样式和各个插件样式import fullcalendar/core/main.css; import fullcalendar/daygrid/main.css; import fullcalendar/timegrid/main.css;不同版本的CSS入口路径略有不同如果引入之后页面错乱先检查版本对应的文档路径。另外做打包优化的人容易把CSS忽略掉这种问题自己不出现一次很难长记性。现象根因解决办法日历区域完全空白未注册对应视图插件确认plugins数组包含dayGridPlugin/timeGridPlugin页面一片白无报错未引入对应CSS检查main.css等样式文件是否被打包事件不显示数据格式不符合要求确认start/end字段是合法ISO字符串事件日期偏移一天时区解析不一致统一使用ISO8601带偏移格式或显式设置timeZone6.2 事件日期偏移一天这类问题的典型表现是后端存的时间是2025-06-10日历上事件显示成了6月9日。多数原因是时间字符串格式不统一。如果后端返回的是2025-06-10T00:00:00Z这种带Z的UTC时间FullCalendar会基于浏览器本地时区解析国内浏览器是UTC8解析出来就是6月10日上午8点显示在10号没毛病。但如果后端返回的是2025-06-10 00:00:00这种无时区标记的字符串不同浏览器的解析结果就可能不一致很容易出现整夜偏移。解决办法是约束后端统一返回ISO 8601格式并明确时区或者在初始化时固定timeZone: local让所有时间都按本地时区解析谁都不许带节奏。6.3 拖拽没落库和重复渲染拖拽事件后切换到别的周再切回来事件又回到原来的位置这是典型的只改了前端视图、没调后端接口的情况。检查一下是否监听了eventDrop回调并且回调里是否正确处理了接口返回。另一个常见问题是重复渲染在React或Vue项目里组件每次状态更新都重新初始化一个Calendar实例导致页面上出现两个日历互相叠加。正确做法是用useRef或ref保存Calendar实例只在组件挂载时初始化一次后续更新用实例方法而不是重新构造。6.4 高度、滚动和容器宽度问题日历在初始渲染时如果容器是隐藏状态或者宽度为0渲染出来高度计算就会出错。常见场景是Tabs标签页里放日历组件切换到日历所在标签页时日历内容显示不全或者高度塌陷。这是因为FullCalendar在初始化时对容器进行了测量容器当时是不可见的。解决办法是在切换标签页后调用calendar.updateSize()它会主动重新测量容器尺寸并重排。容器宽度变化时也同理监听window.resize事件调用一次updateSize()可以避免窗口缩放后时间轴和事件块错位。实际项目里还有一个让我长教训的细节不要把日历放在一个display: none的父容器里初始化应该先让容器可见再初始化或者延迟到容器可见后再调用render。控制台什么都不报页面就是不对检查半天才发现是时序问题。我个人在做过这个预约排期项目之后最大的感受是FullCalendar的价值不在它有多少个配置项而在于它把日历类业务中最难啃的时间计算、视图切换、事件渲染这三件事做得足够扎实。如果你只是需要一个好看的日历它未必是最轻量的选择但如果你想做的是以日历为核心工作台、用户要真在上面操作业务数据的系统它就是不二之选。上手的时候建议先把官方示例跑通再逐步加数据源和交互逻辑别一上来就追求把所有功能堆满。版本升级时尤其要谨慎v3到v4的那次重构网上那些老教程的用户可是实打实踩过一轮坑。本文还有配套的精品资源点击获取
用FullCalendar打造预约排期系统：从选型到避坑指南
简介FullCalendar 1.5.3 完整资源包专门面向需要快速搭建网页日历、日程管理功能的 Web 开发者尤其适合前端入门者与需要集成时间组件的项目。该库支持日、周、月及列表视图并可与 PHP、ASP.NET 等后端进行事件数据交互实用性很强。压缩包共 35 个文件包含 5 个 JS 核心脚本、3 个 CSS 样式表、8 个 HTML 示例页面、14 个 PNG 图标资源以及 PHP 示例、数据库文件和说明文档整体仅 159KB轻量且便于部署。资源中附带了 basic-views、agenda-views、external-dragging、gcal 等典型 demo配合 jquery 脚本即可快速理解初始化、事件源绑定和视图切换等关键用法同时包含 GPL/MIT 许可文件方便商用或二次开发时规避授权风险。目前已有 175 人学习对想尽快上手 FullCalendar 的开发者来说是一份紧凑实用的参考包。 FullCalendar这个名字做前端的老哥们应该都不陌生。前阵子接了个门店预约系统的改造需求客户嫌原来那套用多个日期下拉框选择的交互太反人类用户想看某一天哪些时段能约得来回切换表单控件别说顾客了运营自己都嫌麻烦。我当时的第一个念头就是放弃自己吭哧吭哧写日历组件直接上FullCalendar——它是一个开源的JavaScript日历库专门用来解决”时间、事件、视图”这三者的展示与交互问题。一张日历页面可以在月视图、周视图、日视图之间自由切换事件可以拖动、缩放、点击甚至可以直接点空白日期来新建排期。对于预约、排班、日程管理、课程表这类业务场景这基本是现成的正确答案。这篇就围绕我在实际项目里用FullCalendar搭排期系统的过程把选型逻辑、版本坑、数据接入方式、交互定制的细节和生产环境常见的坑位一次性聊透适合准备在业务里上日历组件、或者已经在用但经常被各种细节卡住的开发者参考。1. 为什么是FullCalendar业务日历的选型复盘1.1 需求来自一张难用的排班页面先还原一下当时的业务现场。门店预约系统里顾客需要选择”哪天、哪个时间段、哪个服务人员”。产品经理提的需求很朴素能不能像手机日历一样一眼看过去就知道哪天约满了、哪天还剩哪些时段。仅这一个诉求就把原生input[typedate]判了死刑。它只能选一个日期看不到某天的事件分布更谈不上多视图切换。用组件库自带的Calendar组件比如Ant Design的日历如果你项目刚好是React生态用起来还行但视图类型依然受限月视图下的格子想塞进按小时划分的时段列表基本要自己重写渲染逻辑。FullCalendar最核心的价值在于它不是一个”日期选择器”而是一个完整的”日程渲染引擎”。它内置了月份、周、日、列表四种视图模型每种视图都自带一套时间轴计算逻辑从周起始日到跨月跨周的边界规则这些琐碎又容易出错的时间算法它已经替你处理好了。1.2 手写日历和组件库日历差在哪我也见过不少团队选择自己写日历说实话如果只是展示”某月某日是节日”手写一个表格并不难难的是那些藏在水面下的边界问题。某个月第一天是周几一个月有多少天这些是基础中的基础。一旦牵涉到跨周、跨月的事件显示比如一个持续三天的事件需要在月视图里同时出现在三个格子里并且要连成一条视觉上连续的色块事件块如何跨格子渲染、如何计算高度、如何避免遮挡自己去实现就会非常痛苦。FullCalendar对事件的渲染策略是内置的。一个跨越多天的事件在月视图里会自动拆分成多个片段并保持样式联动在周视图和日视图里则按时间轴长度渲染成对应高度的色块。这背后涉及的时间算法和DOM渲染逻辑自己从零做工作量论周算用现成库配置两个字段就搞定了。1.3 选型结论什么时候可以放心用它对比下来我最终选择FullCalendar核心原因有四条免费开源MIT协议商用没有授权成本。框架无关原生JavaScript能用官方同时提供了React和Vue的封装版本现有技术栈无论是什么都能接入。内置Interaction插件后点击日期、框选时间段、拖拽事件、调整事件时长这些操作都是开箱即用的交互能力。事件数据是纯JSON结构和后端接口对接非常顺畅不存在什么私有协议。当然它也有适用边界。如果你只是需要一个单纯的日期选择器选日期然后提交表单那用它属于大炮打蚊子。更合适的场景是页面主体本身就是一张日历用户需要在日历上完成查看、新增、拖拽、改期、筛选等操作这种”日历即工作台”的需求用它是最稳妥的选择。2. 开工前先搞懂版本与初始化2.1 版本选择从v3到v6别照着老教程抄FullCalendar的版本迭代很折腾人网上搜到的教程大量还停留在v3甚至更早的jQuery时代。v3版本依赖jQuery和moment.js初始化写法是$(#calendar).fullCalendar({...})如果你照着这种代码去配现在的版本连对象都拿不到直接报错。v4是一次彻底的重写去掉了jQuery依赖改成了ES Module的插件化架构。v5继续沿用了这套架构。也就是说你要用月视图就装fullcalendar/daygrid要用周视图和日视图的时间轴就装fullcalendar/timegrid需要交互能力就装fullcalendar/interaction不再是一个大杂烩文件一把梭。这也是我目前主用的版本线下面的示例都以v5/v6的写法为准。如果项目要新开建议直接看官方文档的最新版不要再看三年前的文章。2.2 安装、引入与第一个渲染以npm方式安装为例核心包加三个常用插件npm install fullcalendar/core fullcalendar/daygrid fullcalendar/timegrid fullcalendar/interaction然后在你的模块里初始化import { Calendar } from fullcalendar/core; import dayGridPlugin from fullcalendar/daygrid; import timeGridPlugin from fullcalendar/timegrid; import interactionPlugin from fullcalendar/interaction; const calendarEl document.getElementById(calendar); const calendar new Calendar(calendarEl, { plugins: [dayGridPlugin, timeGridPlugin, interactionPlugin], initialView: dayGridMonth, headerToolbar: { left: prev,next today, center: title, right: dayGridMonth,timeGridWeek,timeGridDay } }); calendar.render();这里有个非常容易踩的坑plugins数组不能漏。很多人初始化后页面空白第一反应是Dom元素ID写错了实际往往是插件没注册。dayGrid是月视图的基础插件timeGrid负责周视图和日视图interaction负责点击、拖拽、框选这些交互。只写一个Calendar构造器而不注册插件FullCalendar会静默失败页面上一片空白没有任何报错。2.3 中文本地化与基础配置默认界面全是英文必须先做本地化配置。locale字段设成zh-cn但前提是要引入对应的语言包import zhLocale from fullcalendar/core/locales/zh-cn; const calendar new Calendar(calendarEl, { locale: zh-cn, // 如果引入的是具名locale也可以写 locale: zhLocale });语言配置会直接影响星期表头、月份标题、按钮文字以及事件时间显示格式。比如不配的话“今天”按钮显示为Today月份标题是英文排班人员看到全英文界面就直接打回来了。初始化时还有几个基础配置我个人习惯第一时间设置好firstDay: 1让周一作为一周的开始符合国内业务习惯。height: auto避免容器高度写死之后不同月份行数变化导致页面跳动。nowIndicator: true在当前时间位置显示一条红色指示线周视图和日视图里很有用。slotMinTime和slotMaxTime如果门店营业时间是9点到21点就把时间轴范围设成09:00:00到21:00:00避免用户看到一个凌晨三点的时间格子。3. 数据接入的四种方式与性能取舍3.1 events配置项的三种形态FullCalendar的事件数据源是用events字段来配置的它有三种写法。第一种是直接给一个数组适合测试和静态数据第二种是给一个JSON接口地址字符串它会自动请求这个URL并把返回值当作事件列表第三种是传一个回调函数接收当前视图范围作为参数自己控制数据获取逻辑。在这三种方式里我最不推荐的是第二种——直接把后端接口地址写进去。它有一个隐患FullCalendar会在视图切换、数据刷新时频繁请求这个URL而你完全无法控制请求参数也无法对异常情况做统一处理。接口返回格式稍微不规范事件就全丢排查起来很费劲。3.2 用回调函数做按需加载我推荐的做法是使用回调函数。它最大的价值是天然实现了按需加载用户当前看到的是哪一周就只请求这一周的数据接口只返回这一周的事件而不是把全年的数据一次性塞到前端。const calendar new Calendar(calendarEl, { // ... events(info, successCallback, failureCallback) { fetch(/api/events?start${info.startStr}end${info.endStr}) .then(res { if (!res.ok) throw new Error(Network error); return res.json(); }) .then(data successCallback(data)) .catch(err failureCallback(err)); } });info.startStr和info.endStr是当前视图的起止时间字符串默认是ISO格式后端拿到之后可以直接用日期解析库处理。这个回调会在初次渲染、切换视图、点击今天按钮时自动触发所以用户永远不会看到超出当前视野范围的事件数据后端接口的压力也小很多。3.3 数据格式与时区细节后端返回的事件数组每个事件对象至少要包含start字段title字段和end字段按需给。这里有一个容易出问题的细节全天事件和时段事件的表达方式不同。一个全天事件应该写成{ id: 1001, title: 公休, start: 2025-06-10, allDay: true, backgroundColor: #f59e0b }而一个有时段的预约应该是{ id: 1002, title: 张小姐-护理, start: 2025-06-10T14:00:00, end: 2025-06-10T15:00:00, allDay: false }时区是另外一个特别隐蔽的坑。FullCalendar默认会把时间字符串解析为本地时区如果你的接口返回的是带时区偏移的UTC时间或者是YYYY-MM-DD HH:mm:ss这种不带时区标记的格式浏览器的解析行为可能跟你预期的差八个小时事件显示到前一天或者后一天去了。这个我在后面踩坑清单部分专门展开说这里先记住一个原则前后端约定好所有时间要么统一用ISO 8601带偏移的格式要么在FullCalendar初始化时显式设置timeZone: local让解析行为可预期。3.4 事件增删改不要整包刷新数据接入之后前端对事件的增删改也有一套推荐姿势。很多初学者习惯在操作完数据之后调用calendar.refetchEvents()这个方法会把所有事件源重新请求一遍数据量小的时候感觉不出来数据量一大画面会明显闪烁而且用户的拖拽状态、弹窗状态全都被打断。更好的做法是使用实例方法新增事件用calendar.addEvent({ title, start, end, ... })它会立即把新事件渲染到当前视图上。删除事件用event.remove()直接从数据源和视图里同时移除。修改事件属性用event.setProp(title, 新标题)或event.setExtendedProp(customField, value)。这些方法只操作当前事件对象不会触发全量请求交互反馈也更快。配合后端接口通常的做法是前端先调用接口持久化数据接口返回成功后再调用这些方法更新视图接口失败则不做任何操作这样视图和数据保持一致。4. 把日期选择变成业务流程的一部分4.1 点击空白创建排期FullCalendar最有价值的交互能力之一是用户可以直接在日历上点选空白区域来创建事件。要开启这个能力必须引入interaction插件并且配置selectable: true。当用户点击日历空白格子或者用鼠标拖拽框选一个时间段时会触发select回调。回调参数里包含选择的起始时间、结束时间以及当前视图类型。这个回调非常适合用来弹出新增排期的表单select(info) { // 弹出表单把 info.startStr 和 info.endStr 作为默认排期时间 openBookingModal(info.start, info.end); }对应的还有dateClick回调它比select更轻量在点击某个日期时立即触发不要求用户拖拽。这两种交互可以共存常见做法是单击弹新建表单拖拽框选快捷创建连续排期。4.2 限制可选范围与营业时段日历如果允许用户选任何时间业务上一定会出问题。比如预约系统用户不应该能选择过去的时间也不应该能选择半夜三点的时段。这种约束用selectAllow回调来控制selectAllow(info) { const start info.start; const now new Date(); return start.getTime() now.getTime(); }营业时段的限制则可以结合businessHours配置它专门用来定义一周里的可预约时间段。例如周一到周五9点到18点可以预约businessHours: { daysOfWeek: [1, 2, 3, 4, 5], startTime: 09:00, endTime: 18:00 }这里有个细节要注意businessHours只是高亮显示营业时间区域它本身不会阻止用户创建非营业时间的事件。要真正限制选择还是得用selectAllow去判断。把这两者配合起来用高亮是一层视觉提示selectAllow是硬性拦截缺一不可。4.3 拖拽改期与冲突校验排期系统的另一个核心交互是拖拽改期。用户把一个预约从周三拖到周四触发eventDrop回调你需要在这个回调里同步到后端。但这里的坑在于回调的参数结构eventDrop(info) { const event info.event; const oldStart info.oldEvent.start; const oldEnd info.oldEvent.end; // 先调用接口更新排期时间 updateBooking(event.id, { start: event.startStr, end: event.endStr }).catch(() { // 接口失败要回滚 info.revert(); }); }info.event是拖拽后的事件对象它已经在视图里移动过了info.oldEvent保存了拖拽前的快照用于失败回滚。记住一个铁律接口调用前不要做任何乐观更新视图的移动是FullCalendar自己驱动的你要负责的是把变更持久化。接口失败时调用info.revert()把事件拖回原位同时给出提示让用户知道这次操作没有生效。业务上如果存在时间冲突校验比如某个服务人员同一个时段只能接一个单应该在接口返回冲突错误时不仅回滚拖拽还要用calendar.getEventById()定位到那个已经存在的事件高亮闪烁一下提示用户具体冲突在哪个时段。这个细节做得好能大幅减少运营人员的沟通成本。5. 皮相和移动端让日历融入业务系统5.1 修改头部按钮与周末样式组件默认的头部工具栏可以自定义但样式上还是需要二次处理才能融入现有设计系统。头部工具栏的headerToolbar配置里左侧、中间、右侧的按钮集合可以自由组合。比如我们项目里要去掉“今天”按钮把视图切换放到侧边栏里headerToolbar: { left: prev,next, center: title, right: }周末和高亮色块的定制FullCalendar自己有CSS变量体系。比如月视图里今天的背景色、周末的字体颜色都可以用普通CSS覆盖.fc .fc-day-today { background-color: #fff7e6 !important; } .fc .fc-day-sat .fc-daygrid-day-number, .fc .fc-day-sun .fc-daygrid-day-number { color: #e06060; }这里强烈建议用!important或者提高选择器的优先级FullCalendar的样式优先级不低不加一行代码改不动的情况经常出现。5.2 暗色主题适配业务系统如果走暗色路线日历默认的白底配色会显得非常突兀。FullCalendar把常用颜色都拆成了CSS变量看fc-theme-standard这个类名下的定义就能找到通常用的有以下这些.fc { --fc-border-color: #373a40; --fc-page-bg-color: #1f2328; --fc-today-bg-color: rgba(255, 220, 100, 0.15); --fc-event-bg-color: #3b82f6; --fc-event-border-color: #3b82f6; --fc-now-indicator-color: #ff6b6b; }覆盖之后日历的边框、背景、事件色块、今天高亮、当前时间指示线的颜色整体切换比逐个类名去改省心得多。暗色主题下注意事件文字颜色也要同步调亮否则深色背景配深色文字内容根本看不清。5.3 移动端视口与触摸交互预约系统的C端用户大量来自手机端FullCalendar的默认桌面交互在手机上体验很差。移动端的适配我一般从三个维度处理。第一根据视口宽度切换默认视图。手机屏幕显示月视图格子里的文字挤得没法看更合适的默认视图是列表视图if (window.innerWidth 768) { calendar.changeView(listWeek); }第二控制事件在移动端的显示数量。月视图里一个格子塞进五个以上的事件基本就变成一坨色块了用dayMaxEvents: 3配合moreLinkClick: day超出的部分显示“2更多”点击后跳转日视图查看完整列表体验会好很多。第三触摸拖拽。移动端的拖拽事件在FullCalendar里默认是支持的但灵敏度跟桌面不一样。实测下来要给eventDragMinDistance设置一个稍微大一点的值比如10像素避免用户上下滑动页面时误触发拖拽改期。6. 生产环境里的高频坑位清单6.1 界面白屏和样式错乱白屏和样式错乱是新手最容易碰到的问题几乎都和CSS没有引入有关。FullCalendar的组件逻辑和样式是分离的不能只安装JS包就完事。至少需要引入fullcalendar/core的全局样式和各个插件样式import fullcalendar/core/main.css; import fullcalendar/daygrid/main.css; import fullcalendar/timegrid/main.css;不同版本的CSS入口路径略有不同如果引入之后页面错乱先检查版本对应的文档路径。另外做打包优化的人容易把CSS忽略掉这种问题自己不出现一次很难长记性。现象根因解决办法日历区域完全空白未注册对应视图插件确认plugins数组包含dayGridPlugin/timeGridPlugin页面一片白无报错未引入对应CSS检查main.css等样式文件是否被打包事件不显示数据格式不符合要求确认start/end字段是合法ISO字符串事件日期偏移一天时区解析不一致统一使用ISO8601带偏移格式或显式设置timeZone6.2 事件日期偏移一天这类问题的典型表现是后端存的时间是2025-06-10日历上事件显示成了6月9日。多数原因是时间字符串格式不统一。如果后端返回的是2025-06-10T00:00:00Z这种带Z的UTC时间FullCalendar会基于浏览器本地时区解析国内浏览器是UTC8解析出来就是6月10日上午8点显示在10号没毛病。但如果后端返回的是2025-06-10 00:00:00这种无时区标记的字符串不同浏览器的解析结果就可能不一致很容易出现整夜偏移。解决办法是约束后端统一返回ISO 8601格式并明确时区或者在初始化时固定timeZone: local让所有时间都按本地时区解析谁都不许带节奏。6.3 拖拽没落库和重复渲染拖拽事件后切换到别的周再切回来事件又回到原来的位置这是典型的只改了前端视图、没调后端接口的情况。检查一下是否监听了eventDrop回调并且回调里是否正确处理了接口返回。另一个常见问题是重复渲染在React或Vue项目里组件每次状态更新都重新初始化一个Calendar实例导致页面上出现两个日历互相叠加。正确做法是用useRef或ref保存Calendar实例只在组件挂载时初始化一次后续更新用实例方法而不是重新构造。6.4 高度、滚动和容器宽度问题日历在初始渲染时如果容器是隐藏状态或者宽度为0渲染出来高度计算就会出错。常见场景是Tabs标签页里放日历组件切换到日历所在标签页时日历内容显示不全或者高度塌陷。这是因为FullCalendar在初始化时对容器进行了测量容器当时是不可见的。解决办法是在切换标签页后调用calendar.updateSize()它会主动重新测量容器尺寸并重排。容器宽度变化时也同理监听window.resize事件调用一次updateSize()可以避免窗口缩放后时间轴和事件块错位。实际项目里还有一个让我长教训的细节不要把日历放在一个display: none的父容器里初始化应该先让容器可见再初始化或者延迟到容器可见后再调用render。控制台什么都不报页面就是不对检查半天才发现是时序问题。我个人在做过这个预约排期项目之后最大的感受是FullCalendar的价值不在它有多少个配置项而在于它把日历类业务中最难啃的时间计算、视图切换、事件渲染这三件事做得足够扎实。如果你只是需要一个好看的日历它未必是最轻量的选择但如果你想做的是以日历为核心工作台、用户要真在上面操作业务数据的系统它就是不二之选。上手的时候建议先把官方示例跑通再逐步加数据源和交互逻辑别一上来就追求把所有功能堆满。版本升级时尤其要谨慎v3到v4的那次重构网上那些老教程的用户可是实打实踩过一轮坑。本文还有配套的精品资源点击获取
