antd Calendar 通知日历实战：用 dateCellRender 与 monthCellRender 定制日期格与月份格内容

antd Calendar 通知日历实战用 dateCellRender 与 monthCellRender 定制日期格与月份格内容【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design这篇指南以 antd 官方示例 通知事项日历 为主体完整拆解“如何在日历的每一个日期格、月份格中渲染业务数据如待办事项、告警事件”这一场景。读完后你将掌握dateCellRender、monthCellRender两个渲染函数的写法理解当前版本推荐的统一入口cellRender的工作机制并结合 generateCalendar.tsx 源码弄清三者的渲染优先级与弃用演进关系。示例定位一个“复杂应用”级场景官方对 notice-calendar.md 的说明是一个复杂的应用示例用dateCellRender和monthCellRender函数来自定义需要渲染的数据。它对应的可运行代码是 notice-calendar.tsx在 Calendar 组件文档 中登记为“通知事项日历”演示。该示例要解决两个问题日期维度某天可能存在 0N 条事件如 8 号 2 条、10 号 3 条、15 号 6 条需要在日期格下方列出带状态点的事件列表且超长文案要自动省略月份维度某个月可能有汇总指标如 9 月的“Backlog number: 1394”需要在月份格中央渲染大数字。完整示例代码走读以下是notice-calendar.tsx的核心结构数据层与渲染层分离这是该示例最值得借鉴的组织方式。数据层按日期/月份取数据const getListData (value: Dayjs) { let listData: { type: string; content: string }[] []; switch (value.date()) { case 8: listData [ { type: warning, content: This is warning event. }, { type: success, content: This is usual event. }, ]; break; case 10: listData [ { type: warning, content: This is warning event. }, { type: success, content: This is usual event. }, { type: error, content: This is error event. }, ]; break; case 15: listData [ { type: warning, content: This is warning event }, { type: success, content: This is very long usual event...... }, { type: error, content: This is error event 1. }, // ... 共 6 条用于演示超长列表在格子内的表现 ]; break; default: break; } return listData || []; }; const getMonthData (value: Dayjs) { if (value.month() 8) { return 1394; } return undefined; };两个纯函数分别以value.date()月内的第几天和value.month()0 起始的月份序号8 即 9 月为键返回数据。渲染函数只负责“把数据画出来”不掺杂取数逻辑便于单独测试与替换数据源。渲染层monthCellRender 与 dateCellRenderconst monthCellRender (value: Dayjs) { const num getMonthData(value); return num ? ( div className{styles.notesMonth} section{num}/section spanBacklog number/span /div ) : null; }; const dateCellRender (value: Dayjs) { const listData getListData(value); return ( ul className{styles.events} {listData.map((item) ( li key{item.content} Badge status{item.type as BadgeProps[status]} text{item.content} / /li ))} /ul ); };几个关键细节返回null表示“该格无自定义内容”。monthCellRender在无数据时返回null格子就保持日历默认的月份名展示dateCellRender在无数据时返回空的ul视觉上等同于空白。事件行用Badge的 status 形态渲染status传入warning | success | error等预置状态色。从 Badge.tsx 源码看status为PresetStatusColorType类型组件会生成状态点${prefixCls}-status-dot与状态文案${prefixCls}-status-text正好契合“小圆点 事件描述”的视觉。样式收敛在createStyles中events类重置了ul默认样式并对.ant-badge-status设置overflow: hidden; white-space: nowrap; text-overflow: ellipsis保证 15 号那种“very long usual event”超长文案在格子内被省略号截断而不是撑破布局notesMonth类则把月份格汇总数字放大到 28px 并居中。组装层用统一的 cellRender 分发示例最终没有直接传dateCellRender/monthCellRender而是把两个函数合并进一个cellRender回调const cellRender: CalendarPropsDayjs[cellRender] (current, info) { if (info.type date) { return dateCellRender(current); } if (info.type month) { return monthCellRender(current); } return info.originNode; }; return Calendar cellRender{cellRender} /;cellRender的第二个参数info携带typedate或month见 generateCalendar.tsx 中的CalendarProps类型定义据此把不同形态的单元格分发给对应渲染函数对其它类型如年选择面板则原样返回info.originNode不破坏组件默认结构。源码深度渲染优先级与弃用演进为什么示例要“绕开”官方旧写法从 generateCalendar.tsx 的CalendarProps接口定义L57-L86可以看到dateCellRender与monthCellRender至今仍被支持但已标记为弃用/** deprecated Please use fullCellRender instead. */ dateFullCellRender?: (date: DateType) React.ReactNode; /** deprecated Please use cellRender instead. */ dateCellRender?: (date: DateType) React.ReactNode; /** deprecated Please use fullCellRender instead. */ monthFullCellRender?: (date: DateType) React.ReactNode; /** deprecated Please use cellRender instead. */ monthCellRender?: (date: DateType) React.ReactNode; cellRender?: (date: DateType, info: CellRenderInfoDateType) React.ReactNode; fullCellRender?: (date: DateType, info: CellRenderInfoDateType) React.ReactNode;并且组件在开发环境下会显式发出弃用警告L194-L204if (process.env.NODE_ENV ! production) { const warning devUseWarning(Calendar); [ [dateFullCellRender, fullCellRender], [dateCellRender, cellRender], [monthFullCellRender, fullCellRender], [monthCellRender, cellRender], ].forEach(([deprecatedName, newName]) { warning.deprecated(!(deprecatedName in props), deprecatedName, newName); }); }也就是说dateCellRender/monthCellRender会触发“请改用cellRender”的 console 警告dateFullCellRender/monthFullCellRender会触发“请改用fullCellRender”的警告。这正是本示例把两者统一收进cellRender的原因——功能等价但不产生弃用告警也符合当前版本的前瞻写法。旧 API 的降级路径仍然保留cellRender与旧 API 并非“非此即彼”。查看日期格渲染回调dateRenderL265-L302内部按以下优先级取内容若传入了fullCellRenderisFunction(fullCellRender)——整体替换单元格含日期数字本身否则若传入了dateFullCellRender——同样整体替换兼容旧 API否则渲染默认结构日期数字 内容区内容区里取cellRender(date, info)没有cellRender时再降级到dateCellRender?.(date)div className{${calendarPrefixCls}-date-content} /* ... */ {isFunction(cellRender) ? cellRender(date, info) : dateCellRender?.(date)} /div月份格回调monthRenderL304-L345逻辑同构fullCellRendermonthFullCellRender 默认月份名 cellRender或monthCellRender。从源码结构看dateCellRender/monthCellRender的产物只填充格子下半部分的内容区-date-content不会覆盖格子顶部的日期数字或月份名而fullCellRender返回的内容是整个单元格。本示例正利用这一差异保留“8”“15”等日期数字仅在内容区叠加事件列表。单元格类型如何路由到对应渲染函数日历面板内部通过统一的mergedCellRenderL351-L362分发const mergedCellRender: RcBasePickerPanelProps[cellRender] (current, info) { if (info.type date) { return dateRender(current, info); } if (info.type month) { return monthRender(current, { ...info, locale: locale?.lang }); } };月视图面板走month分支且会把组件 locale 语言包locale?.lang合入info供月份名国际化年/月切换面板则走date分支渲染日期格。示例中info.type date | month的判断与这里的内部路由一一对应因此业务侧的cellRender能精确命中两类格子。相关参数速查围绕本示例涉及的 Calendar 参数以组件文档 API 表为准参数说明类型默认值cellRender自定义单元格内容本示例使用推荐写法function(current: Dayjs, info: { prefixCls, originNode, today, range?, type, locale?, subType? }) ReactNode-fullCellRender自定义单元格内容返回内容整体覆盖单元格dateFullCellRender的替代function(current: Dayjs, info) ReactNode-dateCellRender已废弃请用cellRender日期格内容区渲染function(date: Dayjs) ReactNode-monthCellRender已废弃请用cellRender月份格内容区渲染function(date: Dayjs) ReactNode-mode初始模式month \| yearmonthvalue/defaultValue展示日期Dayjs-onSelect选择日期回调可据info.sourceyear \| month \| date \| customize区分来源function(date: Dayjs, info: { source })-onPanelChange日期面板变化回调function(date: Dayjs, mode: string)-fullscreen是否全屏显示booleantrueclassNames/styles自定义语义化结构root/header/body/content/item/itemContent的 class 与内联样式RecordSemanticDOM, string \| (info: { props }) ...-若希望给事件列表所在的内容区统一加样式如固定高度、滚动除了示例中的createStyles方案还可以从 6.0.0 起使用语义化classNames.itemContent/styles.itemContent源码中它会直接合入内容区节点generateCalendar.tsx 的mergedItemContentClassName/mergedItemContentStyle。实用注意事项区分“内容区渲染”与“整体替换”本示例的cellRender返回值落在-date-content内容区日期数字仍然可见若需连日期数字一起替换例如把整个格子画成色块应使用fullCellRender。无数据格要返回null或空容器否则可能把布局撑高示例中monthCellRender返回null、dateCellRender返回空ul是两种常见做法。文案溢出必须自己约束日历格子高度固定事件文案默认不会截断。示例通过white-space: nowrap; text-overflow: ellipsis; overflow: hidden控制单行省略若需要更多行可自行改用-webkit-line-clamp。Badge status的取值要用预置状态色success | processing | default | error | warning示例中as BadgeProps[status]的断言就是为了从{ type: string }收窄到该联合类型。国际化前提Calendar 部分文案如月份名来自 dayjs locale组件文档 提示“请先正确设置 dayjs 的 locale”否则非中文环境下月份格会显示英文月份名。迁移建议旧项目中若已有dateCellRender/monthCellRender写法可平滑迁移到示例所示的cellRender分发模式——先把两个函数保留为内部工具函数再包一层按info.type判断的回调行为不变且消除开发环境下的弃用警告。小结notice-calendar示例展示了 antd Calendar 定制的标准范式数据层纯函数取数、dateCellRender/monthCellRender或统一的cellRender负责把数据映射到格子内容区、Badge 局部样式控制事件行的视觉与溢出。源码层面当前版本已用cellRender/fullCellRender统一替代四个旧 API 并保留降级兼容generateCalendar.tsx新代码按info.type分发即可同时覆盖日期格与月份格两类自定义需求。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考