简介FullCalendar 1.5.3 是一套用于在网页中构建日程、事件和时间表的 JavaScript 组件包面向需要快速实现日历管理功能的前端开发者和 Web 项目团队。它支持日、周、月及列表视图可加载 JSON、PHP 等动态数据源并提供多语言配置方便与常见后端系统结合。整个压缩包共 35 个文件以 JS、CSS、HTML 为主同时包含 PNG 图标、PHP 示例、文本说明及数据库文件整体约 159KB轻量易部署未压缩版与压缩版脚本分别适合开发调试和生产引用配套样式表与打印样式可直接处理常规展示需求。预览显示包内已提供多种视图、外部拖拽、可选中日期和 Google 日历接入等可运行示例并附有 jQuery 依赖便于对照 API 完成二次开发。目前已有 175 人学习下载适合希望低成本接入在线日程展示、事件管理或预约功能的中高级前端开发者参考。 做前端时间管理类功能日历永远是绕不开的坎。从最早的只在后台管理里放一个简单的月视图到后来要做周视图、日视图、资源时间线、拖拽修改日程需求一复杂自己手写就彻底不现实了。我前前后后换过好几个方案最后固定在FullCalendar上一直用到现在。这篇文章不聊官网文档里的Hello World就聊我在真实项目里怎么选型、怎么接线、怎么填坑以及那些文档里没写明白但你一定会踩到的细节。FullCalendar是一个开源的JavaScript日历库用它可以在React、Vue、Angular甚至原生JS里快速实现支持月视图、周视图、日视图、列表视图的事件日历并且具备拖拽、缩放、点击编辑等交交互能力。如果你要做的功能是“带数据的日历”而不是“画一个日历外观”那它就是现成的轮子。下面这几年的实战内容希望能帮你省下几个通宵排查问题的时间。1. 为什么是FullCalendar项目选型背后的思考1.1 这个库解决了什么问题我接手过好几个和日程、排班、课程表相关的项目最开始的实现方式基本都是自己写一个表格把一个月按周拆开再往单元格里塞数据。听着简单实际做起来全是坑月份第一天不是周一每周跨月的时候要怎么补格子点击上个月按钮之后日期范围怎么算事件跨越多天的时候DOM要怎么处理。这些逻辑单独拿出来都不难但合在一起就是一个完整的状态机写一遍能掉一层头发。FullCalendar替我把这一整块都解决了。传入一个日期范围它自己计算视图的起止时间、渲染格子、处理跨月跨周传入事件数组它负责把事件按时间投射到正确的位置用户拖拽后它抛出事件我只需要在回调里更新数据就行。这就不只是一个“UI组件”而是一个完整的日程管理引擎。1.2 和其他方案的对比用FullCalendar之前我认真比较过几条技术路线。第一条是自己基于表格手写。好处是可控性高但坏处特别明显研发周期长、边界场景多、后期维护成本高。做一个只读月视图可能要两三天做到可拖拽、可跨视图编辑至少要一两周而且每加一个新交互都要从头推一遍状态逻辑。第二条是使用其他日历库比如React Big Calendar。平心而论它在React项目里很方便可是配置灵活性、插件生态和文档完整度都不如FullCalendar。比如资源时间线视图就是那种左侧人员列表、右侧按小时排班的模式FullCalendar提供了一个Scheduler插件直接搞定而React Big Calendar需要自己组合组件实现。第三条就是FullCalendar。它的优势很明显本身是框架无关的核心库提供React、Vue、Angular适配器包体积可控可以按需引入插件事件对象模型设计得很完整覆盖了真实业务里绝大多数需求。我在两个项目里用了之后觉得它确实能扛住复杂场景就稳定用它了。1.3 版本选择的考量FullCalendar在2022年发布了v6和v5对比从上到下来了一次重构。最大的变化是样式系统全套换成了CSS变量颜色、边框、圆角这些全部可以覆盖而不是像以前那样去改深层SCSS。这对我这种习惯在业务层统一设计语言的开发者来说非常友好。v6还调整了包结构核心功能拆成了fullcalendar/core加插件的形式编译层面也全面ESModule化。如果你用的是Vite、Webpack 5这类现代构建工具tree-shaking能帮你把最终打进项目的代码控制到很小的体积。我个人建议新项目直接用v6。旧项目如果不涉及大规模重构留在v5也能跑但早晚要升级。v6的中文文档资源虽然没有英文全但核心API和v5基本保持一致很多旧经验都能直接迁移过来。2. 核心细节解析与实操要点2.1 视图体系日历的四种显示模式FullCalendar的视图体系一句话概括视图决定了你“按什么维度展示时间段”。dayGridMonth是经典月视图以自然月为容器列出所有事件适合做排期总览。timeGridWeek和timeGridDay是按时间轴排列的周视图/日视图每个事件按起止时间渲染成色块适合做会议室预订、课程安排。listWeek是以列表形式罗列事件适合放在手机端或做辅助信息流。多视图最常见的配置方法是这样import FullCalendar from fullcalendar/react import dayGridPlugin from fullcalendar/daygrid import timeGridPlugin from fullcalendar/timegrid import interactionPlugin from fullcalendar/interaction import listPlugin from fullcalendar/list FullCalendar plugins{[dayGridPlugin, timeGridPlugin, interactionPlugin, listPlugin]} headerToolbar{{ left: dayGridMonth,timeGridWeek,timeGridDay,listWeek, center: title, right: prev,next today }} initialViewdayGridMonth /有一点值得注意headerToolbar里配置的按钮名称必须和插件的视图ID一一对应。listWeek属于list插件timeGridDay属于timeGrid插件只要少引一个工具栏上对应的按钮就不会出现而且不报错这是很多新手容易忽略的点。2.2 事件源与事件对象数据从哪里来、长什么样事件源EventSource是FullCalendar里数据接入的统一入口。你可以把它理解成“一个日历里可以挂多个数据来源”比如同时挂一个团队日程源和一个个人日程源每个源都可以独立控制是否显示、用什么颜色、从哪里加载。事件源有三种定义方式固定数组、JSON地址、函数。固定数组适合静态数据JSON地址适合后端给好接口直接用函数形式是我最推荐的因为它在每次视图切换、刷新时都会被调用可以带上当前视图的开始时间和结束时间出去请求数据只拉当前可见范围内的数据。事件对象的核心字段需要注意id事件的唯一标识拖拽更新回传的时候靠它定位数据。title显示在日历上的文本。start/end起止时间可以是ISO字符串也可以是Date对象。end是可选的不传时FullCalendar会按默认时长处理。allDay是否全天事件。全天事件在月视图顶部显示时间格子里不占钟点位置。backgroundColor/borderColor/textColor覆盖默认外观。extendedProps自定义字段。这是我最常用的比如事件关联的数据库ID、人员对象、订单编号全挂在里面回调时原样返回。我实测一个经验后端返回的数据字段名往往和FullCalendar不一致。比如后端叫startTimeFullCalendar要的是start。这种情况不用改后端在前端做一次映射就好保持后端模型稳定把适配逻辑放在前端。2.3 交互插件拖拽、缩放、点击的底层机制交互能力分散在两个插件里。fullcalendar/interaction负责基础的点击事件、选中时间段、拖拽移动事件、拖拽调整事件起止时间。fullcalendar/resource-timeline这类Scheduler插件是在交互插件之上叠加资源维度的视图能力。拖拽移动触发的事件是eventDrop拖拽调整时长触发的是eventResize它们都是在用户松开鼠标之后才触发回调参数里有一个event对象和一个delta对象delta表示从原位置偏移了多少毫秒。业务上要在回调里做的就是拿到新的事件起止时间去调后端接口更新完成后再刷新日历数据。点击和选中时间段也是高频用法。dateClick可以处理“点击某一个日期格子”的动作比如弹出新建日程的弹窗selectable开启后用户可以在视图上拖拽框选一个时间段松开后触发select回调非常适合做“在日历上直接创建日程”的交互。3. 实操过程与核心环节实现3.1 三步快速搭建一个基础日历以React项目为例第一步安装依赖npm install fullcalendar/react fullcalendar/core fullcalendar/daygrid fullcalendar/timegrid fullcalendar/interaction fullcalendar/list第二步引入组件和插件做最小配置import FullCalendar from fullcalendar/react import dayGridPlugin from fullcalendar/daygrid import timeGridPlugin from fullcalendar/timegrid import interactionPlugin from fullcalendar/interaction import zhLocale from fullcalendar/core/locales/zh-cn function Calendar() { return ( FullCalendar plugins{[dayGridPlugin, timeGridPlugin, interactionPlugin]} locale{zhLocale} initialViewdayGridMonth events{[ { id: 1, title: 产品评审, start: 2025-05-06T10:00:00, end: 2025-05-06T11:30:00 }, { id: 2, title: 开发周会, start: 2025-05-07T14:00:00 } ]} / ) }到这一步一个带工具栏、支持中文显示、有月周日视图的基础日历就出来了。整个配置的量级比手写一个月的格局小太多。第三步是把日历的宽高撑起来这算一个比较隐蔽的问题。FullCalendar默认样式是自适应容器宽度的但高度在大多数情况下需要手动控制。最稳妥的做法是用CSS变量覆盖.calendar-wrapper { height: 600px; } .calendar-wrapper .fc { height: 100%; }或者直接在组件上传height属性比如height{600}或height100%。如果不管高度月视图和列表视图可能正常但时间视图会出现滚动条不出现、事件错位等奇怪问题。3.2 把数据接进来与后端接口对接的常规做法真实项目里不可能把事件写死在前端数据几乎都来自后端。我推荐用函数形式的事件源原因前面说过每次视图切换、数据刷新时它都会带着当前视图的开始时间、结束时间去请求接口。import dayGridPlugin from fullcalendar/daygrid import timeGridPlugin from fullcalendar/timegrid import interactionPlugin from fullcalendar/interaction // 统一的请求封装fetchEvents 示意 async function fetchEvents(start, end) { const params new URLSearchParams({ start: start.toISOString(), end: end.toISOString() }) const res await fetch(/api/events?${params.toString()}) const json await res.json() return json.data.map(item ({ id: item.id, title: item.name, start: item.beginTime, end: item.endTime, extendedProps: item })) } FullCalendar plugins{[dayGridPlugin, timeGridPlugin, interactionPlugin]} initialViewdayGridMonth events{fetchEvents} loading{isLoading { // isLoading 为 true 时显示 loadingfalse 时隐藏 }} /这里有两个很关键的细节。第一个是start和end参数的类型日历默认传的是Date对象。直接传给后端最好先格式化成固定格式尤其是当后端对时区敏感的时候。第二个是返回的数据必须是数组而且数组里每一项最好带id没有id的话拖拽后Frontend很难精确知道是哪个事件更新了会导致视图重渲染丢失数据。接口正好返回空数组时日历不会报错只是显示空白。实际情况中这更多说明后端接口在前端可见范围内没有返回数据而不是日历配置错误。3.3 给日历加上拖拽和调整实现可编辑日程只读日历只能看能拖拽才叫真正的日程管理。启用拖拽交互需要加fullcalendar/interaction插件并在日历上打开editable。const handleEventDrop async (info) { const { event, oldEvent } info const id event.id const newStart event.start.toISOString() const newEnd event.end ? event.end.toISOString() : null // 乐观更新先改前端再请求后端 try { await updateEvent(id, { start: newStart, end: newEnd }) } catch (e) { // 请求失败还原 info.revert() } } FullCalendar editable{true} eventDrop{handleEventDrop} eventResize{handleEventDrop} selectable{true} select{handleSelect} /info.revert()是官方提供的回滚能力调用之后事件会自动回到拖动前的位置。在实际项目里我一般把更新请求和前端状态改动的顺序设计成“先改前端数据再发后端请求失败就revert”这样用户体验最好也不会出现点击后长时间无响应的情况。再说select回调。用户按住鼠标从周一的9点拖到10点松开后select事件会返回start、end。可以在回调里弹一个Modal让用户输入标题再保存。新建之后把新事件refetchEvents()或直接追加到日历数据里页面会立刻显示。3.4 中文本地化和其他高频配置FullCalendar默认是英文中文切换非常简单只需要引入中文本地化包import zhLocale from fullcalendar/core/locales/zh-cn FullCalendar locale{zhLocale} /locale会同时影响按钮文字、月份标题、星期显示、日期格式等。如果项目有中英文切换直接把locale变量换成对应语言包即可。另一个高频需求是控制可选的视图按钮。业务中经常只让用户看周视图和日视图不想开放月视图入口headerToolbar{{ left: title, center: , right: prev,next today timeGridWeek,timeGridDay }}还可以用initialDate指定日历默认定位到某个日期用firstDay设置一周从星期几开始国内一般设1表示周一这些细节虽然小但都直接影响用户对产品的感知。4. 常见问题与排查技巧实录4.1 事件的开始时间总是差8个小时这个问题我遇到太多次了。日历里的时间显示正常但通过eventDrop回调拿到的event.start时间戳转到本地展示时发现多了8小时或少8小时。根源几乎都是时区解析问题后端返回的ISO字符串带有时区偏移比如2025-05-06T10:00:00ZFullCalendar会按当地时间解析而后端返回的是2025-05-06T10:00:00无时区标记的字符串FullCalendar会默认当成本地时间转成时间戳时可能就出现了偏移。实践经验是协作时全链路统一用ISO 8601格式后端返回带时区偏移的时间前端展示时用dayjs或Intl.DateTimeFormat做格式化不要手动拼字符串。如果你确认后端返回的就是无时区的“墙上时间”那在传给FullCalendar之前先给末尾补上本地时区偏移可以规避很多莫名奇妙的偏差。4.2 事件拖拽之后视图没刷新有一种情况是eventDrop回调里用了alert或console.log调试事件位置变了但后端数据没更新日历重渲染之后又变回原样。这不是日历的bug而是数据源没有变化FullCalendar的渲染基于数据源不是基于DOM。所以要先确认事件源是函数还是静态数组。函数形式的事件源默认在每次视图切换时重新执行但拖拽后不会自动重新请求。需要在更新接口成功后手动调用calendarRef.current.getApi().refetchEvents()强制重新拉取数据。我在项目里已经养成了一个习惯所有数据变更操作增删改事件完成后统一调一次refetchEvents()保证视图和数据始终同步绝不依赖组件内部状态去猜。4.3 月视图事件太多挤成一团看不清事件数量一多月视图默认会显示eventMaxStack: 2也就是最多垂直叠2条超出部分折叠成“N更多”点击可以展开弹层。这个默认值在很多业务里不够用可以通过设置eventMaxStack调大但最大不建议超过5否则单元格会很高月视图看起来不像月历更像垂直列表。另一个方案是把月视图的事件改成只显示一个小圆点点击时在旁边的面板里看详情这是很多SaaS产品在移动端的做法。FullCalendar里可以通过eventDisplay: list-item或自定义eventContent来实现视觉效果干净很多。还有一点是别把dayMaxEvents和eventMaxStack搞混。dayMaxEvents控制的是“某一天最多显示多少个事件条目”eventMaxStack控制的是“垂直堆叠几层”如果都设置了以它们共同作用的视觉结果为标准先调dayMaxEvents通常更容易见效。4.4 移动端长按拖拽不灵敏FullCalendar在桌面端的拖拽体验很好但到了手机端editable开启后手指长按事件块再拖动偶尔会触发浏览器的默认行为比如选中文字、滚动页面。两个处理方法第一个是在CSS里禁用日历区域内的文字选中.fc * { -webkit-user-select: none; user-select: none; }第二个是在日历组件上开启longPressDelay比如longPressDelay{200}单位毫秒让长按判定时间变长减少误触。注意longPressDelay属于交互插件的配置项不传的话默认值在移动端是0所以明显感觉到触摸就触发加了延迟会舒服很多。如果产品业务以移动端为主我建议不要完全依赖拖拽来修改时间可以同时在eventClick里弹出一个底部抽屉里面提供“修改开始时间”“修改结束时间”的明确按钮这样对触屏用户更友好。4.5 条件刷新、动态权限与按需加载资源FullCalendar通过refetchEvents()支持整表刷新通过getEventSources()可以拿到所有事件源然后单独调用某个源上的refetch()实现部分刷新。在多团队、多标签页共存的场景这个能力很有用。权限控制方面可以动态切换editable的值。比如用户只有只读权限时设置editable{false}前端不用改逻辑只改一个属性就能锁住所有交互。最后说一下Scheduler插件。如果你要做会议室预订、医院排班、多人日程的资源时间线它解决的正是这块核心需求。它属于License插件有试用版商用需要购买授权这一点在选型时提前评估不要等到上线前才被合规卡住。最后再分享一点个人心得用FullCalendar这几年最深的体会是它不是一个“日历组件”而是一个“日程管理运行时”。你在配置里写的不是UI描述而是对业务规则的声明。事件源、视图、交互回调、时区处理这些东西想清楚了换什么前端框架都能顺滑接上。如果这个项目是第一次用FullCalendar我的建议是把v6官方示例完整跑一遍不要跳过任何交互演示拖拽、缩放、多事件源、资源时间线每一项都亲手点一点。然后再从最简单的月视图开始一步步往里加业务逻辑。别一上来就想着上Scheduler插件做时间线基础视图的配置和联调经验会让你在后面踩坑时更快定位问题。本文还有配套的精品资源点击获取