RSUITE DateRangePicker 日期时间格式自定义实战：format、showMeridiem 与 defaultCalendarValue 组合用法

前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载导读RSUITE 的DateRangePicker组件默认以dd/MM/yyyy格式展示日期范围但在真实业务中我们往往需要携带具体时刻、切换 12 小时制甚至只选择时间段。本文以官方文档示例 format-date-time.md 为骨架系统讲解如何通过format、showMeridiem、defaultCalendarValue、ranges等属性组合出「日期时间范围」「纯时间范围」「12 小时制AM/PM」三类典型场景并结合 DateRangePicker 源码 揭示format字符串是如何驱动日历面板、时间选择器与输入框行为的。读完本文你将能根据自己的业务任意定制日期时间格式并理解其背后的实现原理。一、示例总览三种典型时间格式官方文档 format-date-time.md 给出了一个覆盖三种典型场景的完整示例import { DateRangePicker } from rsuite; const App () ( div classNamefield pDate Time Range/p DateRangePicker formatyyyy-MM-dd HH:mm:ss defaultCalendarValue{[new Date(2022-02-01 00:00:00), new Date(2022-05-01 23:59:59)]} / pTime Range/p DateRangePicker formatHH:mm:ss ranges{[]} defaultCalendarValue{[new Date(2022-02-01 00:00:00), new Date(2022-05-01 23:59:59)]} / pMeridiem format/p DateRangePicker formathh:mm aa showMeridiem defaultCalendarValue{[new Date(2022-02-01 00:00:00), new Date(2022-05-01 23:59:59)]} / /div ); ReactDOM.render(App /, document.getElementById(root));三组示例分别对应场景format 取值关键属性日期 时间范围yyyy-MM-dd HH:mm:ssdefaultCalendarValue纯时间范围HH:mm:ssranges{[]}、defaultCalendarValue12 小时制Meridiemhh:mm aashowMeridiem、defaultCalendarValue三组示例都通过defaultCalendarValue预先指定日历面板的默认展示区间保证打开弹层时前后两个日历月处于2022-02与2022-05让示例效果稳定可复现。二、认识 format组件的“显示与行为”开关format是DateRangePicker的核心属性之一。根据 官方 Props 文档属性名format类型string默认值dd/MM/yyyy作用设置日期范围在输入框中渲染时的格式在 DateRangePicker 源码 中format的解析起点是const formatStr format || locale?.shortDateFormat || yyyy-MM-dd; const rangeFormatStr ${formatStr}${character}${formatStr};即未显式传入format时会回退到locale.shortDateFormat最后兜底为yyyy-MM-dd而输入框最终展示的字符串是「起始日期格式化结果 分隔符character 结束日期格式化结果」character默认值为 ~ 见同文件character ~ 的默认参数解构。format使用的是类 date-fns 的令牌token语法常见令牌如下令牌含义示例输出yyyy四位数年份2022MM两位数月份02MMM/MMMM缩写 / 全称月份Feb/Februarydd两位数日期01HH24 小时制小时00–2314hh12 小时制小时01–1202mm分钟30ss秒45aaAM / PM 标记AM、PM除英文字母令牌外格式串中也可以嵌入任意文字例如yyyy年MM月dd日这一点在 format.md 示例 中直接使用。format 决定面板形态源码级原理format不仅是显示格式还直接决定了日历弹层“长什么样”。源码在 DateRangePicker.tsx 中通过useDateMode对格式串做模式判定const { mode, has } useDateMode(formatStr); // Show only the calendar month panel. formatStr yyyy-MM const onlyShowMonth mode DateMode.Month; // Only show the time panel. formatStr HH:mm:ss const onlyShowTime mode DateMode.Time; // Allows two calendar panels to display the same month. const allowSameMonth onlyShowMonth || showOneCalendar || onlyShowTime; // Default gap between two calendars, if showOneCalendar is set, the gap is 0 const calendarGap allowSameMonth ? 0 : 1;模式判定逻辑实现在 useDateMode.ts 与 formatCheck.ts 中shouldRenderTime(format)正则/([Hhms])/只要格式串包含H、h、m、s中的任一字符即视为含时间shouldOnlyRenderTime(format)包含[Hhms]且不包含[YyMDd]如HH:mm:ss判定为纯时间模式DateMode.TimeshouldRenderDate(format)同时包含[Yy]、[ML]、[Dd]判定为日期模式DateMode.Date日期与时间同时存在时判定为DateMode.DateTime。由此可以理解本文示例的三种行为差异formatyyyy-MM-dd HH:mm:ss→DateTime模式同时渲染双月日历与时间选择器formatHH:mm:ss→Time模式onlyShowTime为 true弹层只展示时间选择面板不再渲染日历网格这也是该示例需要配合ranges{[]}的原因——面板上只有时间可操作formathh:mm aa→ 同样是纯时间模式但配合showMeridiem以 12 小时制呈现。在Time模式下两个日历面板允许展示同一个月allowSameMonth为 truecalendarGap变为 0而在普通日期模式下前后两个日历默认间隔 1 个月源码中getSafeCalendarDate的默认区间为「当月 下月」。时间模式下改变日期会保留时间当格式同时包含日期与时间时用户点击日期只会改变年月日而不会重置时分秒。这一行为由 DateRangePicker.tsx 中的copyTime保证// The time should remain the same when the dates in the date range are changed. if ( has(time) dateRange?.length (eventName changeDate || eventName changeMonth) ) { const startDate copyTime({ from: getCalendarDatetime(start), to: dateRange[0] }); const endDate copyTime({ from: getCalendarDatetime(end), to: dateRange.length 1 ? addMonths(startDate, calendarGap) : dateRange[1] }); nextValue [startDate, endDate]; }即日期变更事件changeDate/changeMonth发生时从当前日历基准时间getCalendarDatetime(start/end)中取出时分秒拷贝到新选中的日期上从而保证「先选日期、后调时间」的交互符合预期。三、场景一日期 时间范围Date Time RangeDateRangePicker formatyyyy-MM-dd HH:mm:ss defaultCalendarValue{[new Date(2022-02-01 00:00:00), new Date(2022-05-01 23:59:59)]} /要点说明formatyyyy-MM-dd HH:mm:ss让输入框按「年-月-日 时:分:秒」显示例如2022-02-01 00:00:00 ~ 2022-05-01 23:59:59defaultCalendarValue的类型为[Date, Date]作用是设置日历面板的默认展示日期而非输入框的值源码中在getSafeCalendarDate({ value: value ?? defaultCalendarValue ?? null, allowSameMonth })处被消费DateRangePicker.tsx。当组件没有受控值或默认值时弹层打开即定位到该区间用户可在日历上先后点击起始日期与结束日期完成范围选择再通过面板内的时间选择器时/分/秒下拉微调具体时刻最后点击 OK 确认。需要区分的是defaultCalendarValue只影响日历面板的初始展示月份与defaultValue非受控默认值是两个不同概念详见 官方 Props 表。四、场景二纯时间范围Time RangeDateRangePicker formatHH:mm:ss ranges{[]} defaultCalendarValue{[new Date(2022-02-01 00:00:00), new Date(2022-05-01 23:59:59)]} /要点说明formatHH:mm:ss由于不包含任何年/月/日令牌被 formatCheck.ts 判定为纯时间模式日历弹层只渲染时间选择面板ranges{[]}清空预置快捷范围。ranges默认提供Today、Yesterday、Last 7 days三个快捷选项见 官方 Props 表 中ranges的默认说明纯时间场景下这些日期快捷项没有意义因此置空时间选择器通过点击即可完成开始时间与结束时间的两次选择。测试用例中也验证了纯时间格式的行为——DateRangePicker.spec.tsx 中以formathh:mm:ss渲染组件后通过设置起始时间的时/分/秒为 6:6:6 断言时间选择生效。五、场景三12 小时制Meridiem格式DateRangePicker formathh:mm aa showMeridiem defaultCalendarValue{[new Date(2022-02-01 00:00:00), new Date(2022-05-01 23:59:59)]} /要点说明formathh:mm aa中hh表示 12 小时制小时01–12aa表示 AM/PM 标记两者必须配合使用showMeridiem是布尔属性源码注释为「Meridiem format for 12-hour time」DateRangePicker.tsx它在时间选择面板中展示 AM/PM 切换项。注意源码中还存在已废弃的showMeridian属性注释明确建议「UseshowMeridieminstead」showMeridiem会被透传给日历组件calendarProps中的showMeridiem并参与时间选项的渲染见 DateRangePicker.tsx。实际渲染效果类似02:00 AM ~ 05:00 PM。需要 24 小时制时使用HH:mm且不要设置showMeridiem。六、与 format 强相关的配套属性除了format本身官方文档 中还有一批属性与日期时间格式配合使用在定制格式时常被一并调整属性类型 / 默认值说明characterstring默认 ~ 两个日期之间的分隔符例如设为 – 后展示为2022-02-01 – 2022-05-01defaultCalendarValue[Date, Date]日历面板默认展示的日期区间defaultValue[Date, Date]非受控模式下的默认选中值value[Date, Date]受控模式下的当前值editableboolean默认true是否允许通过键盘在输入框内直接输入日期时间placeholderstring输入框占位提示showHeaderboolean默认true是否在日历顶部展示格式化后的日期范围v5.52.0 起rangesRange[]预置快捷范围纯时间或纯月份场景通常置为[]其中editable值得注意DateRangePicker默认允许键盘直接录入日期时间editable{true}输入内容同样按formatStr解析校验若希望禁止键盘输入、只允许点选可设editable{false}。更多 format 组合示例format.md 还提供了大量可直接套用的组合摘录如下DateRangePicker formatMM/dd/yyyy character – / DateRangePicker formatdd.MM.yyyy / DateRangePicker formatMMM dd, yyyy / DateRangePicker formatMMMM dd, yyyy / DateRangePicker formatyyyy年MM月dd日 / DateRangePicker formatMM/dd/yyyy HH:mm / DateRangePicker formatMM/dd/yyyy hh:mm aa showMeridiem / DateRangePicker formatMMM yyyy caretAs{BsCalendar2MonthFill} ranges{[]} / DateRangePicker formatHH:mm:ss caretAs{FaClock} ranges{[]} / DateRangePicker formatdd MMM yyyy hh:mm:ss aa showMeridiem caretAs{FaCalendar} ranges{[]} /其中formatMMM yyyy仅含年与月会被判定为DateMode.Month模式弹层直接展示月份选择面板onlyShowMonthcaretAs则用于替换输入框右侧的日历图标与纯时间/纯月份场景搭配更语义化。七、源码验证格式与输入渲染format还参与输入框尺寸的计算与值的渲染getInputHtmlSize 会按rangeFormatStr或选中值经formatDate格式化后的完整字符串的长度动态计算输入框 HTML 宽度因此长格式如yyyy-MM-dd HH:mm:ss会自动获得更宽的输入框输入框展示值由formatDate(startDate, formatStr)与formatDate(endDate, formatStr)拼接而成formatDate来自useCustom(DateRangePicker, props)的国际化格式化函数日历顶部的Header同样接收formatStr与character将当前选中/悬停区间实时格式化展示DateRangePicker.tsx。测试用例也验证了格式化渲染结果例如 DateRangePicker.spec.tsx 中const template MM/dd/yyyy hh:mm:ss; render(DateRangePicker value{value} format{template} /); expect(screen.getByRole(textbox)).to.have.value(11/11/2019 01:00:00 ~ 11/12/2019 01:00:00);即输入框严格按起始值 character( ~ ) 结束值的规则渲染与 format-date-time.md 示例中的预期展示一致。八、实践建议与小结先定业务粒度再写 format只要日期 →yyyy-MM-dd类日期时刻 → 追加HH:mm或HH:mm:ss只要时刻 → 纯时间格式并配ranges{[]}只要月份 →yyyy-MM或MMM yyyy12 小时制必须成对使用hhaashowMeridiem缺一不可24 小时制使用HH且不设置showMeridiem注意默认值对象粒度defaultCalendarValue是[Date, Date]形式的 Date 对象数组传入的起始时刻如00:00:00、23:59:59会成为该侧日历的时间基准配合copyTime机制在后续日期变更时被保留纯时间/纯月份场景记得清空ranges避免出现语义不符的「Today / Yesterday」快捷项若希望展示更紧凑可同时调整character分隔符如 – 该字符同样会出现在日历头部与输入框渲染结果中。通过formatshowMeridiemdefaultCalendarValueranges的组合DateRangePicker足以覆盖绝大多数业务中的日期时间范围选择需求而理解useDateMode对格式串的模式判定能帮助你预判日历面板的最终形态做到「改一行 format面板随之自适应」。赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐RSuite DateRangeInput 日期格式自定义完全指南format 与 character 深入解析RSuite DateRangeInput 日期格式自定义完全指南format 与 character 深入解析 DateRangeInput 是 RSuit前端UI组件rsuite DateInput 日期格式定制指南掌握 format 属性的全部写法rsuite DateInput 日期格式定制指南掌握 format 属性的全部写法 导读 DateInput 是 rsuite 中允许用户 通过键盘逐段输入前端UI组件antd DatePicker 日期格式化实战用 format 属性自定义 yyyy/MM/dd 等显示格式antd DatePicker 日期格式化实战用 format 属性自定义 yyyy/MM/dd 等显示格式 format 是 ant designantdUI组件前端设计系统上一篇Zcash 6.20.0 与 zcashd 全节点隐私共识实现、从源码构建与生命周期管理指南下一篇基于 Eleventy 的零配置博客模板从本地构建到一键部署 Vercel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考