ToolJet Calendar 组件实战指南属性、事件绑定、资源调度与底层实现【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet本文基于 ToolJet 3.0.0-LTS 官方文档中的 Calendar 组件参考完整讲解该组件的属性配置、事件对象结构、资源调度用法、交互事件与暴露变量并结合frontend/src/AppBuilder/Widgets/Calendar下的源码逐条印证每个属性在底层如何生效。读完本文你可以独立搭建一个带数据绑定、多资源视图与点击交互的日历应用并理解每个 Inspector 属性对应的真实代码行为。一、组件定位与使用限制Calendar 组件用于以可视化方式组织与排期日程事件可设置默认视图day、week、month、开关各类显示选项并将数据绑定到事件Events和资源Resources上。有一个明确的布局限制Calendar 的 Popout弹出子容器中不允许再放置 Calendar 和 Kanban 组件。这一点在文档中被标注为 Restricted components且可以在源码中验证——restrictedWidgetsConfig.js 中明确声明了Calendar: [Calendar, Kanban]即在 Calendar 的 Popout 内仅禁止嵌套这两类组件。二、基础属性Date Format 与 Default Date属性说明Date Format决定所有经由属性传入日历的日期字符串如何被解析同时也决定日历通过暴露变量向外输出的日期格式。采用 moment.js 的日期格式约定。Default Date决定日历视图围绕哪一天居中。默认为当前日期即{{moment().format(MM-DD-YYYY HH:mm:ss A Z)}}。若处于month视图则展示该日期所在月份若处于week视图则展示该日期所在周。该属性必须使用Date format属性指定的格式书写。从 calendar.js 的默认定义看新建 Calendar 组件时的出厂值为dateFormatMM-DD-YYYY HH:mm:ss A ZdefaultDate{{moment().format(MM-DD-YYYY HH:mm:ss A Z)}}defaultView{{month}}startTime/endTime分别为当天startOf(day)/endOf(day)的格式化日期源码层面的日期解析发生在 Calendar.jsxprepareEvent会用moment(event.start, dateFormat).toDate()把事件对象中的字符串日期转为原生DateparseDate则对解析结果做isNaN(parsed.getTime())校验无效日期直接返回null——这意味着如果把Default Date写成了与Date Format不一致的格式日历不会抛出异常而是静默回退到初始状态排障时这是首先要检查的地方。startTime/endTime未配置时源码会回退为今天的起止时刻Calendar.jsx 中的todayStartTime/todayEndTime这也是默认定义里用moment().startOf(day)表达式的原因。三、事件绑定Events 与事件对象Events属性应包含一个对象数组每个对象描述日历上要展示的一条事件。假设Date format设为MM-DD-YYYY HH:mm:ss A Z下面的代码会渲染出本页配图中的Sample event当天第一小时开始的整日事件{{[ { title: Sample event, start: ${moment().startOf(day).format(MM-DD-YYYY HH:mm:ss A Z)}, end: ${moment().endOf(day).format(MM-DD-YYYY HH:mm:ss A Z)}, allDay: false, tooltip: Sample event, color: lightgreen, } ]}}事件对象的字段字段说明title事件标题start事件开始的日期及时间须按你配置的Date format格式化end事件结束的日期及时间须按你配置的Date format格式化allDay可选。将事件标记为全天事件在day与week视图中会被钉在日期头部tooltip鼠标悬停在事件上时显示的提示文案color事件背景色支持任意 CSS 颜色名或十六进制色值textColor事件标题文字颜色支持任意 CSS 颜色名或十六进制色值textOrientation可选。设为vertical时事件标题纵向排布resourceId仅在启用资源调度时适用指该事件对应的资源 id事件对象中任意额外字段都会被原样保留当 Calendar 通过暴露变量如selectedEvent吐出事件时这些自定义属性一并可用。源码中prepareEvent使用展开运算符{...event}透传所有原始字段Calendar.jsx这正是任意附加属性可透传的实现依据。事件样式同样有源码级的默认值行为eventPropGetterCalendar.jsx中背景色缺省为var(--cc-primary-brand)主题主色文字色缺省为whitetextOrientation vertical会渲染为writingMode: vertical-rl但源码额外限定currentView ! month——也就是说纵向文字在 month 视图下不生效这一细节文档未直接写出排障时值得注意。tooltip通过tooltipAccessortooltip交给底层日历库处理Calendar.jsx。四、资源调度Resources配置resources后日历会为每个资源把week/day视图拆分成独立的列。例如按三间会议室分类{{[ {resourceId: 1, title: Room A}, {resourceId: 2, title: Room B}, {resourceId: 3, title: Room C}, ]}}再把某个事件的resourceId设为1该事件就会出现在Room A列中。以下截图展示了把视图设为day并按三间资源分类后的效果源码印证Calendar.jsx、Calendar.jsxresourcesParam仅在properties.resources为非空数组时才传入底层组件{{[]}}默认值等效于未启用资源调度资源与事件的关联键由resourceIdAccessorresourceId和resourceTitleAccessortitle指定因此事件字段名必须叫resourceId资源数组中的显示名必须叫title改名会导致调度失效。五、视图与显示控制属性属性行为源码映射Default View决定初始展示day/week/month中的哪一种设为其他值时回退为month。当前选中视图同时暴露为currentView变量allowedCalendarViews 白名单校验非法值取allowedCalendarViews[0]即monthStart Time on Week and Day View决定week/day视图时间轴起点。该字段接受日期但只取其中的时间与如提供时时区格式须符合Date format传入底层日历的min参数End Time on Week and Day View决定week/day视图时间轴终点取值规则同上传入底层日历的max参数Show Toolbar是否显示日历工具栏可点Fx用{{true}}/{{false}}程序化控制toolbar{properties.displayToolbar}Show View Switcher是否显示month/week/day视图切换按钮支持 Fx 动态控制关闭时容器追加hide-view-switcher类名Highlight Today是否高亮今天卡片支持 Fx 动态控制关闭时追加dont-highlight-today类名Show Popover When the Event is Clicked点击事件时是否弹出 Popover支持 Fx 动态控制onSelectEvent中按showPopOverOnEventClick决定是否打开 CalendarEventPopover几个与源码一致的补充细节底层日历通过selectable{true}保持常开允许点击空槽或拖拽选择多个槽位Calendar.jsx事件点击的 Popover 由 CalendarPopover.jsx 实现它会依据点击坐标做边界翻转超出画布右侧时移到事件下方并在组件被拖动尺寸时自动关闭defaultView改变时会触发useEffect同步currentView暴露变量并强制刷新视图Calendar.jsx所以{{components.calendar1.currentView}}始终与工具栏当前视图一致。六、交互事件Events事件触发时机与暴露变量On Event Select用户点击某个日历事件时触发最近选中的事件暴露为selectedEventOn Slot Select用户点击日历空槽含带事件单元格内的空白区域或按住拖拽多选槽位时触发选中的槽位暴露为selectedSlotsOn Date Navigate用户点击Today、Next、Back按钮时触发导航到的日期暴露为currentDateOn View Change用户切换视图时触发当前视图暴露为currentView更详细的 Action 参考可查阅 Action Reference 文档。事件分发的完整链路可在源码中确认组件内fireEvent(onCalendarEventSelect, { id, calendarEvent })Calendar.jsx发出事件后eventsSlice.js 中对应处理先调用setExposedValue(id, selectedEvent, calendarEvent)/setExposedValue(id, selectedSlots, selectedSlots)写入暴露变量再执行用户配置的 Action 列表。因此暴露变量与触发 Action是同一事件里的两个副作用变量在 Action 执行前就已就绪。selectedSlots的结构由 slotSelectHandler 构造slots数组中的每个日期、以及start/end都会先按Date Format格式化再输出因此下游 JS 表达式拿到的都是字符串日期可继续用 moment 解析。七、暴露变量Exposed Variables变量说明selectedEvent存储当前选中的事件对象含title、start、end、allDay、color等键可用{{components.calendar1.selectedEvent.title}}、{{components.calendar1.selectedEvent.start}}等语法动态访问selectedSlots存储选中的槽位信息含slots、start、end、resourceId、action等键可用{{components.calendar1.selectedSlots.slots[0]}}、{{components.calendar1.selectedSlots.end}}访问currentView当前视图类型支持month、week、day用户从日历头部切换时自动更新访问语法{{components.calendar1.currentView}}。初始值为monthcurrentDate当前日期数据按MM-DD-YYYY HH:mm:ss A Z格式输出访问语法{{components.calendar1.currentDate}}从 calendar.js 的exposedVariables定义可见currentView出厂默认即为month、currentDate初始为undefined而 Calendar.jsx 的初始化useEffect会在挂载时把defaultDate格式化后写入currentDate所以应用启动后该变量即有值。八、General、Layout 与 StylesGeneral — Tooltip在General折叠区设置字符串后鼠标悬停组件时即显示该提示文案用于补充说明组件用途。Layout选项说明默认值Show on Desktop控制桌面视图下是否显示可用Fx设为{{true}}/{{false}}{{true}}Show on Mobile控制移动视图下是否显示可用Fx设为{{true}}/{{false}}{{false}}Styles样式说明Visibility控制组件可见性支持Fx程序化控制。设为{{false}}时应用部署后组件不可见默认{{true}}。源码中通过display: styles.visibility ? block : none生效Calendar.jsxCell Size in Views Classified by Resource配置resources后日历横向空间占用大频繁需要水平滚动此项提供Compact/Spacious两档单元格密度默认Spacious对应容器类名Calendar.jsx选项定义见 calendar.jsHeader Date Format on Week View决定 week 视图每个日期列头的显示格式同样遵循 moment.js 约定默认DD MMM。源码中由自定义 week header 组件moment(props.date).format(styles.weekDateFormat)渲染Calendar.jsx此外calendar.js 还定义了borderColor默认var(--cc-weak-border)与borderRadius默认 6px两个边框样式项分别映射为组件外框的border与borderRadius。凡字段旁带Fx按钮的属性均可通过{{...}}表达式程序化配置。九、组件特定操作CSA当前版本没有实现用于管控 Calendar 组件的 CSAComponent-Specific Actions。对 Calendar 的控制手段即本文所述的属性 Fx 绑定、事件回调与暴露变量组合。十、小结关键默认值速查新建 Calendar 组件时值得记住的出厂默认均来自 calendar.js 的definition项默认值尺寸宽 30 列 × 高 600pxdateFormatMM-DD-YYYY HH:mm:ss A ZdefaultViewmonthdisplayToolbar/displayViewSwitcher/highlightTodaytrueshowPopOverOnEventClickfalseresources{{[]}}即不启用资源调度cellSizeInViewsClassifiedByResourcespaciousweekDateFormatDD MMMshowOnDesktop/showOnMobiletrue/falseCalendar 组件底层基于react-big-calendar moment localizer 实现Calendar.jsx本文所述的解析、校验、回退逻辑均以当前仓库 3.0.0-LTS 源码为准若在升级大版本后遇到行为差异建议先对照frontend/src/AppBuilder/Widgets/Calendar/与frontend/src/AppBuilder/WidgetManager/widgets/calendar.js两处实现核对。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考