Ant Design DatePicker 日期格式完全指南format 属性、数组多格式与 mask 输入对齐【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design在 Ant Design 中format属性是DatePicker/RangePicker控制日期显示、解析与键盘输入的核心配置。本文基于仓库中的演示文档与源码完整讲清format的四种形态字符串、数组、函数、mask 对象、各picker模式下的默认值以及输入多格式解析、周范围自定义展示等实战写法帮助你在表单录入、报表展示等场景下精确控制日期的呈现与解析行为。核心概念format 与 dayjs 格式化占位符format属性用于自定义日期显示格式。其占位符体系直接复用 dayjs 的format能力如YYYY、MM、DD、HH:mm:ss配置参考 dayjs 官方支持的格式化占位符列表。当format为数组时选择器输入框可以输入数组中任意一个有效格式的值组件会尝试用数组中的各个格式依次解析用户输入而展示时以数组第一个格式为准。这是处理存量数据格式不统一、需要兼容多种录入习惯场景的关键能力。从 API 文档 index.zh-CN.md 的属性表可以确认各选择器模式下的format默认值组件 / 模式format默认值DatePickerYYYY-MM-DDMonthPickerpickermonthYYYY-MMYearPickerpickeryearYYYYQuarterPickerpickerquarterYYYY-\QQWeekPickerpickerweekYYYY-woTimePickerpickertimeYYYY-MM-DD HH:mm:ssFormatTypeformat 的完整类型定义API 文档中给出的FormatType类型见 index.zh-CN.md 的formatType小节定义了format的全部合法形态import type { Dayjs } from dayjs; type Generic string; type GenericFn (value: Dayjs) string; export type FormatType | Generic | GenericFn | ArrayGeneric | GenericFn | { format: string; type?: mask; };四类形态的用途各有侧重字符串Generic最常用的形态直接决定输入框展示与回显格式函数GenericFn接收Dayjs对象返回任意自定义字符串适合周区间、带前缀说明等非标准展示数组ArrayGeneric | GenericFn输入时可匹配任意一个格式展示取第一个{ format, type: mask }对象5.14.0 新增type字段实现输入格式对齐详见下文。实战示例六种典型写法仓库中的 format 演示对应说明文档 format.md覆盖了上述全部形态完整代码如下import React from react; import type { DatePickerProps } from antd; import { DatePicker, Space } from antd; import dayjs from dayjs; import customParseFormat from dayjs/plugin/customParseFormat; // 数组多格式解析依赖 dayjs 的 customParseFormat 插件 dayjs.extend(customParseFormat); const { RangePicker } DatePicker; const dateFormat YYYY/MM/DD; const weekFormat MM/DD; const monthFormat YYYY/MM; /** Manually entering any of the following formats will perform date parsing */ const dateFormatList [DD/MM/YYYY, DD/MM/YY, DD-MM-YYYY, DD-MM-YY]; // 函数格式展示任意自定义字符串 const customFormat: DatePickerProps[format] (value) custom format: ${value.format(dateFormat)}; // 函数格式展示该周周一 ~ 周日的起止日期 const customWeekStartEndFormat: DatePickerProps[format] (value) ${dayjs(value).startOf(week).format(weekFormat)} ~ ${dayjs(value) .endOf(week) .format(weekFormat)}; const App: React.FC () ( Space directionvertical size{12} {/* 1. 字符串格式YYYY/MM/DD */} DatePicker defaultValue{dayjs(2015/01/01, dateFormat)} format{dateFormat} / {/* 2. 数组格式可输入数组中任意一个格式展示以第一个为准 */} DatePicker defaultValue{dayjs(01/01/2015, dateFormatList[0])} format{dateFormatList} / {/* 3. 月份选择器 自定义月格式 */} DatePicker defaultValue{dayjs(2015/01, monthFormat)} format{monthFormat} pickermonth / {/* 4. 周选择器 函数格式展示整个周的起止日期 */} DatePicker defaultValue{dayjs()} format{customWeekStartEndFormat} pickerweek / {/* 5. RangePicker 同样支持 format */} RangePicker defaultValue{[dayjs(2015/01/01, dateFormat), dayjs(2015/01/01, dateFormat)]} format{dateFormat} / {/* 6. 函数格式完全自定义展示文案 */} DatePicker defaultValue{dayjs(2015/01/01, dateFormat)} format{customFormat} / /Space ); export default App;几个值得注意的实现细节数组格式解析需要 dayjs 插件示例中dayjs.extend(customParseFormat)并非可有可无。当format为数组时组件需要按每个格式逐一尝试解析输入文本这一能力来自 dayjs 的customParseFormat插件函数格式的入参是Dayjs对象customWeekStartEndFormat利用startOf(week)/endOf(week)将周选择器的单日值渲染为01/01 ~ 01/07这样的区间展示了函数形态展示层完全自定义的灵活度onChange返回的dateString跟随format无论是字符串还是函数格式回调中的日期字符串都会按展示格式生成可直接用于提交或日志RangePicker继承同一套format配置范围选择器的两个输入框共用该格式。mask 形态输入格式对齐5.14.0 新增FormatType中的对象形态{ format: string; type?: mask }提供的是输入格式对齐能力其官方演示见 mask.md 与 mask.tsxconst App: React.FC () ( Space directionvertical DatePicker format{{ format: YYYY-MM-DD, type: mask, }} onChange{onChange} / DatePicker format{{ format: YYYY-MM-DD HH:mm:ss, type: mask, }} onChange{onChange} / /Space );启用 mask 后的交互行为来自 mask.md 的说明输入框按照format给出的模板逐位对齐用户只需按顺序输入数字可通过键盘左右方向键在数字段之间切换焦点失去焦点时会尝试对齐到最后合法的日期例如输入2025-02-30会自动归位到 2 月的最后一天。这与字符串format的关键区别在于字符串格式下用户可以自由输入任意文本再解析而 mask 格式下输入过程本身就受到模板约束适合作业对输入合法性要求更高的表单场景。底层实现format 如何传递到 rc-picker从源码结构看Ant Design 的 DatePicker 是对底层rc-picker的封装。在 generateSinglePicker.tsx 中getPicker函数通过forwardRef构造各选择器DatePicker、WeekPicker、MonthPicker、YearPicker、QuarterPicker、TimePicker将picker模式、占位符、前后翻页图标等 Ant Design 侧配置注入后其余属性通过{...restProps}原样透传给RCPickerreturn wrapCSSVar( ContextIsolator space RCPickerDateType ref{innerRef} placeholder{getPlaceholder(locale, mergedPicker, placeholder)} picker{picker} {...additionalProps} {...restProps} // format 即在此处透传给 rc-picker ... / /ContextIsolator, );即format并未在 Ant Design 层做二次加工解析与展示逻辑最终由rc-picker结合generateConfigdayjs 配置完成。这解释了为什么数组格式解析依赖 dayjs 的customParseFormat插件也意味着若项目按 FAQ 中的使用自定义日期库方案替换了generateConfigformat的占位符体系需要与新日期库的格式化 API 保持一致。同理generateRangePicker.tsx 中的RangePicker也走同一套透传逻辑format对范围选择器同样生效。使用建议小结场景推荐format形态常规表单录入 / 回显字符串如YYYY-MM-DD需兼容多种历史格式录入数组并确保已dayjs.extend(customParseFormat)展示周区间、带业务前缀等函数(value) string严格受限的逐位输入{ format: YYYY-MM-DD, type: mask }5.14.0时间选择器含时间段的字符串如YYYY-MM-DD HH:mm:ss配置时建议与picker模式匹配月选择器使用YYYY-MM级别粒度即可并注意占位符语义以 dayjs 文档为准函数形态只影响展示不影响解析数组形态的展示始终以第一个格式为准。相关实现可进一步参阅 components/date-picker 目录下的源码与 demo 目录 中的完整示例。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考