DatePicker日期选择框
DatePicker
日期选择框
输入或选择日期的控件。
使用import{ DatePicker }from"antd"; |
- 组件总览
- 通用
- 布局
- 导航
- 数据录入
- 数据展示
- 反馈
- 其他
当用户需要输入一个日期，可以点击标准输入框，弹出日期面板进行选择。
最简单的用法，在浮层中可以选择或者输入日期。
多选，不支持 showTime 以及 picker="time"。
DatePicker 默认会根据 picker 的交互行为，自动选择是否需要确认按钮。你也可以通过 needConfirm 属性来手动设置是否需要确认按钮。当有 needConfirm 时，用户始终需要点击确认按钮才能完成选择。反之，则会在选择或者失去焦点时提交。
使用 format 属性，可以自定义日期显示格式。当 format 为数组时，选择器输入框可以输入数组中任意一个有效格式。
输入格式对齐，通过键盘左右切换焦点。失去焦点时会尝试对齐到最后合法的日期。
选择框的不可用状态。你也可以通过数组单独禁用 RangePicker 的其中一项。
在范围选择时，可以允许留空。这对于需要保留“至今”日期项颇为有用。
可以预设常用的日期范围以提高用户体验。自 5.8.0 开始，preset value 支持回调函数返回值方式。
三种大小的输入框，若不设置，则为 middle。
通过 components 替换对应面板。
使用 status 为 DatePicker 添加状态，可选 error 或者 warning。
Filled Debug
通过组合 mode 与 onPanelChange 控制要展示的面板。
自定义前缀 prefix 和后缀图标 suffixIcon。
Component Token Debug.
通过设置 picker 属性，指定范围选择器类型。
非响应式间距测试。
提供选择器，自由切换不同类型的日期选择器，常用于日期筛选场合。
增加选择时间功能，当 showTime 为一个对象时，其属性会传递给内建的 TimePicker。
通过 minDate 和 maxDate 限定日期范围。
可用 disabledDate 和 disabledTime 分别禁止选择部分日期和时间，其中 disabledTime 需要和 showTime 一起使用。
使用 disabledDate 的 info.from 来限制动态的日期区间选择。
在浮层中加入额外的页脚，以满足某些定制信息的需求。
使用 cellRender 可以自定义单元格的内容和样式。
通过 locale 配置支持特殊的年历格式。
可选 outlined filled borderless 三种形态。
可以通过 placement 手动指定弹出的位置。
当 RangePicker 无法满足业务需求时，可以使用两个 DatePicker 实现类似的功能。
- 通过设置
disabledDate方法，来约束开始和结束日期。- 通过
openonOpenChange来优化交互。
调试用组件，请勿直接使用。
通用属性参考：通用属性
日期类组件包括以下五种形式。
默认配置为 en-US，如果你需要设置其他语言，推荐在入口处使用我们提供的国际化组件，详见：ConfigProvider 国际化。
如有特殊需求（仅修改单一组件的语言），请使用 locale 参数，参考：默认配置。
// 默认语言为 en-US，如果你需要设置其他语言，推荐在入口文件全局设置 locale// 确保还导入相关的 dayjs 文件，否则所有文本的区域设置都不会更改（例如范围选择器月份）import locale from 'antd/locale/zh_CN';import dayjs from 'dayjs';import 'dayjs/locale/zh-cn';dayjs.locale('zh-cn');<ConfigProvider locale={locale}><DatePicker defaultValue={dayjs('2015-01-01', 'YYYY-MM-DD')} /></ConfigProvider>;
在搭配 Next.js 的 App Router 使用时，注意在引入 dayjs 的 locale 文件时加上 'use client'。这是由于 Ant Design 的组件都是客户端组件，在 RSC 中引入 dayjs 的 locale 文件将不会在客户端生效。
以下 API 为 DatePicker、 RangePicker 共享的 API。
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| allowClear | 自定义清除按钮 | boolean | { clearIcon?: ReactNode } | true | 5.8.0: 支持对象类型 |
| autoFocus | 自动获取焦点 | boolean | false | |
| className | 选择器 className | string | - | |
| dateRender | 自定义日期单元格的内容，5.4.0 起用 cellRender 代替 | function(currentDate: dayjs, today: dayjs) => React.ReactNode | - | < 5.4.0 |
| cellRender | 自定义单元格的内容 | (current: dayjs, info: { originNode: React.ReactElement,today: DateType, range?: 'start' | 'end', type: PanelMode, locale?: Locale, subType?: 'hour' | 'minute' | 'second' | 'meridiem' }) => React.ReactNode | - | 5.4.0 |
| components | 自定义面板 | Record<Panel | 'input', React.ComponentType> | - | 5.14.0 |
| disabled | 禁用 | boolean | false | |
| disabledDate | 不可选择的日期 | (currentDate: dayjs, info: { from?: dayjs, type: Picker }) => boolean | - | info: 5.14.0 |
| format | 设置日期格式，为数组时支持多格式匹配，展示以第一个为准。配置参考 dayjs#format。示例：自定义格式 | formatType | rc-picker | |
| order | 多选、范围时是否自动排序 | boolean | true | 5.14.0 |
| preserveInvalidOnBlur | 失去焦点是否要清空输入框内无效内容 | boolean | false | 5.14.0 |
| popupClassName | 额外的弹出日历 className | string | - | 4.23.0 |
| getPopupContainer | 定义浮层的容器，默认为 body 上新建 div | function(trigger) | - | |
| inputReadOnly | 设置输入框为只读（避免在移动设备上打开虚拟键盘） | boolean | false | |
| locale | 国际化配置 | object | 默认配置 | |
| minDate | 最小日期，同样会限制面板的切换范围 | dayjs | - | 5.14.0 |
| maxDate | 最大日期，同样会限制面板的切换范围 | dayjs | - | 5.14.0 |
| mode | 日期面板的状态（设置后无法选择年份/月份？） | time | date | month | year | decade | - | |
| needConfirm | 是否需要确认按钮，为 false 时失去焦点即代表选择。当设置 multiple 时默认为 false | boolean | - | 5.14.0 |
| nextIcon | 自定义下一个图标 | ReactNode | - | 4.17.0 |
| open | 控制弹层是否展开 | boolean | - | |
| panelRender | 自定义渲染面板 | (panelNode) => ReactNode | - | 4.5.0 |
| picker | 设置选择器类型 | date | week | month | quarter | year | date | quarter: 4.1.0 |
| placeholder | 输入框提示文字 | string | [string, string] | - | |
| placement | 选择框弹出的位置 | bottomLeft bottomRight topLeft topRight | bottomLeft | |
| popupStyle | 额外的弹出日历样式 | CSSProperties | {} | |
| prefix | 自定义前缀 | ReactNode | - | 5.22.0 |
| prevIcon | 自定义上一个图标 | ReactNode | - | 4.17.0 |
| presets | 预设时间范围快捷选择, 自 5.8.0 起 value 支持函数返回值 | { label: React.ReactNode, value: Dayjs | (() => Dayjs) }[] | - | |
| size | 输入框大小，large 高度为 40px，small 为 24px，默认是 32px | large | middle | small | - | |
| status | 设置校验状态 | 'error' | 'warning' | - | 4.19.0 |
| style | 自定义输入框样式 | CSSProperties | {} | |
| suffixIcon | 自定义的选择框后缀图标 | ReactNode | - | |
| superNextIcon | 自定义 >> 切换图标 | ReactNode | - | 4.17.0 |
| superPrevIcon | 自定义 << 切换图标 | ReactNode | - | 4.17.0 |
| variant | 形态变体 | outlined | borderless | filled | outlined | 5.13.0 |
| onOpenChange | 弹出日历和关闭日历的回调 | function(open) | - | |
| onPanelChange | 日历面板切换的回调 | function(value, mode) | - |
| 名称 | 描述 | 版本 |
|---|---|---|
| blur() | 移除焦点 | |
| focus() | 获取焦点 |
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| defaultPickerValue | 默认面板日期，每次面板打开时会被重置到该日期 | dayjs | - | 5.14.0 |
| defaultValue | 默认日期，如果开始时间或结束时间为 null 或者 undefined，日期范围将是一个开区间 | dayjs | - | |
| disabledTime | 不可选择的时间 | function(date) | - | |
| format | 展示的日期格式，配置参考 dayjs#format。 | formatType | YYYY-MM-DD | |
| multiple | 是否为多选，不支持 showTime | boolean | false | 5.14.0 |
| pickerValue | 面板日期，可以用于受控切换面板所在日期。配合 onPanelChange 使用。 | dayjs | - | 5.14.0 |
| renderExtraFooter | 在面板中添加额外的页脚 | (mode) => React.ReactNode | - | |
| showNow | 显示当前日期时间的快捷选择 | boolean | - | |
| showTime | 增加时间选择功能 | Object | boolean | TimePicker Options | |
| showTime.defaultValue | 设置用户选择日期时默认的时分秒，例子 | dayjs | dayjs() | |
| showWeek | DatePicker 下展示当前周 | boolean | false | 5.14.0 |
| value | 日期 | dayjs | - | |
| onChange | 时间发生变化的回调 | function(date: dayjs, dateString: string) | - | |
| onOk | 点击确定按钮的回调 | function() | - | |
| onPanelChange | 日期面板变化时的回调 | function(value, mode) | - |
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| defaultValue | 默认日期 | dayjs | - | |
| format | 展示的日期格式，配置参考 dayjs#format。 | formatType | YYYY | |
| multiple | 是否为多选 | boolean | false | 5.14.0 |
| renderExtraFooter | 在面板中添加额外的页脚 | () => React.ReactNode | - | |
| value | 日期 | dayjs | - | |
| onChange | 时间发生变化的回调，发生在用户选择时间时 | function(date: dayjs, dateString: string) | - |
4.1.0 新增。
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| defaultValue | 默认日期 | dayjs | - | |
| format | 展示的日期格式，配置参考 dayjs#format。 | formatType | YYYY-\QQ | |
| multiple | 是否为多选 | boolean | false | 5.14.0 |
| renderExtraFooter | 在面板中添加额外的页脚 | () => React.ReactNode | - | |
| value | 日期 | dayjs | - | |
| onChange | 时间发生变化的回调，发生在用户选择时间时 | function(date: dayjs, dateString: string) | - |
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| defaultValue | 默认日期 | dayjs | - | |
| format | 展示的日期格式，配置参考 dayjs#format。 | formatType | YYYY-MM | |
| multiple | 是否为多选 | boolean | false | 5.14.0 |
| renderExtraFooter | 在面板中添加额外的页脚 | () => React.ReactNode | - | |
| value | 日期 | dayjs | - | |
| onChange | 时间发生变化的回调，发生在用户选择时间时 | function(date: dayjs, dateString: string) | - |
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| defaultValue | 默认日期 | dayjs | - | |
| format | 展示的日期格式，配置参考 dayjs#format。 | formatType | YYYY-wo | |
| multiple | 是否为多选 | boolean | false | 5.14.0 |
| renderExtraFooter | 在面板中添加额外的页脚 | (mode) => React.ReactNode | - | |
| value | 日期 | dayjs | - | |
| onChange | 时间发生变化的回调，发生在用户选择时间时 | function(date: dayjs, dateString: string) | - | |
| showWeek | DatePicker 下展示当前周 | boolean | true | 5.14.0 |
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| allowEmpty | 允许起始项部分为空 | [boolean, boolean] | [false, false] | |
| cellRender | 自定义单元格的内容。 | (current: dayjs, info: { originNode: React.ReactElement,today: DateType, range?: 'start' | 'end', type: PanelMode, locale?: Locale, subType?: 'hour' | 'minute' | 'second' | 'meridiem' }) => React.ReactNode | - | 5.4.0 |
| dateRender | 自定义日期单元格的内容，5.4.0 起用 cellRender 代替 | function(currentDate: dayjs, today: dayjs) => React.ReactNode | - | < 5.4.0 |
| defaultPickerValue | 默认面板日期，每次面板打开时会被重置到该日期 | dayjs[] | - | 5.14.0 |
| defaultValue | 默认日期 | dayjs[] | - | |
| disabled | 禁用起始项 | [boolean, boolean] | - | |
| disabledTime | 不可选择的时间 | function(date: dayjs, partial: start | end, info: { from?: dayjs }) | - | info.from: 5.17.0 |
| format | 展示的日期格式，配置参考 dayjs#format。 | formatType | YYYY-MM-DD HH:mm:ss | |
| id | 设置输入框 id 属性。 | { start?: string, end?: string } | - | 5.14.0 |
| pickerValue | 面板日期，可以用于受控切换面板所在日期。配合 onPanelChange 使用。 | dayjs[] | - | 5.14.0 |
| presets | 预设时间范围快捷选择，自 5.8.0 起 value 支持函数返回值 | { label: React.ReactNode, value: (Dayjs | (() => Dayjs))[] }[] | - | |
| renderExtraFooter | 在面板中添加额外的页脚 | () => React.ReactNode | - | |
| separator | 设置分隔符 | React.ReactNode | <SwapRightOutlined /> | |
| showTime | 增加时间选择功能 | Object|boolean | TimePicker Options | |
| showTime.defaultValue | 设置用户选择日期时默认的时分秒，例子 | dayjs[] | [dayjs(), dayjs()] | |
| value | 日期 | dayjs[] | - | |
| onCalendarChange | 待选日期发生变化的回调。info 参数自 4.4.0 添加 | function(dates: [dayjs, dayjs], dateStrings: [string, string], info: { range:start|end }) | - | |
| onChange | 日期范围发生变化的回调 | function(dates: [dayjs, dayjs], dateStrings: [string, string]) | - | |
| onFocus | 聚焦时回调 | function(event, { range: 'start' | 'end' }) | - | range: 5.14.0 |
| onBlur | 失焦时回调 | function(event, { range: 'start' | 'end' }) | - | range: 5.14.0 |
import type { Dayjs } from 'dayjs';type Generic = string;type GenericFn = (value: Dayjs) => string;export type FormatType =| Generic| GenericFn| Array<Generic | GenericFn>| {format: string;type?: 'mask';};
注意：type 定义为 5.14.0 新增。
| Token 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| activeBg | 输入框激活状态时背景颜色 | string | #ffffff |
| activeBorderColor | 激活态边框色 | string | #1677ff |
| activeShadow | 激活态阴影 | string | 0 0 0 2px rgba(5, 145, 255, 0.1) |
| addonBg | 前/后置标签背景色 | string | rgba(0, 0, 0, 0.02) |
| cellActiveWithRangeBg | 选取范围内的单元格背景色 | string | #e6f4ff |
| cellBgDisabled | 单元格禁用态背景色 | string | rgba(0, 0, 0, 0.04) |
| cellHeight | 单元格高度 | number | 24 |
| cellHoverBg | 单元格悬浮态背景色 | string | rgba(0, 0, 0, 0.04) |
| cellHoverWithRangeBg | 选取范围内的单元格悬浮态背景色 | string | #c8dfff |
| cellRangeBorderColor | 选取范围时单元格边框色 | string | #7cb3ff |
| cellWidth | 单元格宽度 | number | 36 |
| errorActiveShadow | 错误状态时激活态阴影 | string | 0 0 0 2px rgba(255, 38, 5, 0.06) |
| hoverBg | 输入框hover状态时背景颜色 | string | #ffffff |
| hoverBorderColor | 悬浮态边框色 | string | #4096ff |
| inputFontSize | 字体大小 | number | 14 |
| inputFontSizeLG | 大号字体大小 | number | 16 |
| inputFontSizeSM | 小号字体大小 | number | 14 |
| multipleItemBg | 多选标签背景色 | string | rgba(0, 0, 0, 0.06) |
| multipleItemBorderColor | 多选标签边框色 | string | transparent |
| multipleItemBorderColorDisabled | 多选标签禁用边框色 | string | transparent |
| multipleItemColorDisabled | 多选标签禁用文本颜色 | string | rgba(0, 0, 0, 0.25) |
| multipleItemHeight | 多选标签高度 | number | 24 |
| multipleItemHeightLG | 大号多选标签高度 | number | 32 |
| multipleItemHeightSM | 小号多选标签高度 | number | 16 |
| multipleSelectorBgDisabled | 多选框禁用背景 | string | rgba(0, 0, 0, 0.04) |
| paddingBlock | 输入框纵向内边距 | number | 4 |
| paddingBlockLG | 大号输入框纵向内边距 | number | 7 |
| paddingBlockSM | 小号输入框纵向内边距 | number | 0 |
| paddingInline | 输入框横向内边距 | number | 11 |
| paddingInlineLG | 大号输入框横向内边距 | number | 11 |
| paddingInlineSM | 小号输入框横向内边距 | number | 7 |
| presetsMaxWidth | 预设区域最大宽度 | number | 200 |
| presetsWidth | 预设区域宽度 | number | 120 |
| textHeight | 单元格文本高度 | number | 40 |
| timeCellHeight | 时间单元格高度 | number | 28 |
| timeColumnHeight | 时间列高度 | number | 224 |
| timeColumnWidth | 时间列宽度 | number | 56 |
| warningActiveShadow | 警告状态时激活态阴影 | string | 0 0 0 2px rgba(255, 215, 5, 0.1) |
| withoutTimeCellHeight | 十年/年/季/月/周单元格高度 | number | 66 |
| zIndexPopup | 弹窗 z-index | number | 1050 |
请参考常见问答
当用户选择完年份后，系统会直接切换至日期面板，而非显式提供月份选择。这样做的设计在于用户只需进行一次点击即可完成年份修改，无需再次点击进入月份选择界面，从而减少了用户的操作负担，同时也避免需要额外感知月份的记忆负担。
请参考《使用自定义日期库》
参考 FAQ 为什么时间类组件的国际化 locale 设置不生效？。
请使用正确的语言包（#5605），或者修改 dayjs 的 locale 配置：https://codesandbox.io/s/dayjs-day-of-week-x9tuj2?file=/demo.tsx
import dayjs from 'dayjs';import 'dayjs/locale/zh-cn';import updateLocale from 'dayjs/plugin/updateLocale';dayjs.extend(updateLocale);dayjs.updateLocale('zh-cn', {weekStart: 0,});
panelRender 时，原来面板无法切换？当你通过 panelRender 动态改变层级结构时，会使得原本的 Panel 被当做新的节点删除并创建。这使得其原本的状态会被重置，保持结构稳定即可。详情请参考 #27263。
欢迎阅读博客《为什么禁用日期这么难？》了解如何使用。