DatePicker日期选择框
DatePicker
日期选择框
输入或选择日期的控件。
使用import { DatePicker } from "antd"; |
- 组件总览
- 通用
- 布局
- 导航
- 数据录入
- 数据展示
- 反馈
- 其他
当用户需要输入一个日期，可以点击标准输入框，弹出日期面板进行选择。
最简单的用法，在浮层中可以选择或者输入日期。
多选，不支持 showTime 以及 picker="time"。
提供选择器，自由切换不同类型的日期选择器，常用于日期筛选场合。
增加选择时间功能，当 showTime 为一个对象时，其属性会传递给内建的 TimePicker。
通过 minDate 和 maxDate 限定日期范围。
可用 disabledDate 和 disabledTime 分别禁止选择部分日期和时间，其中 disabledTime 需要和 showTime 一起使用。
使用 disabledDate 的 info.from 来限制动态的日期区间选择。
在浮层中加入额外的页脚，以满足某些定制信息的需求。
使用 cellRender 可以自定义单元格的内容和样式。
通过 locale 配置支持特殊的年历格式。
DatePicker 形态变体，可选 outlined filled borderless underlined 四种形态。
自定义前缀 prefix 和后缀图标 suffixIcon。
通过设置 picker 属性，指定范围选择器类型。
DatePicker 默认会根据 picker 的交互行为，自动选择是否需要确认按钮。你也可以通过 needConfirm 属性来手动设置是否需要确认按钮。当有 needConfirm 时，用户始终需要点击确认按钮才能完成选择。反之，则会在选择或者失去焦点时提交。
使用 format 属性，可以自定义日期显示格式。当 format 为数组时，选择器输入框可以输入数组中任意一个有效格式。
输入格式对齐，通过键盘左右切换焦点。失去焦点时会尝试对齐到最后合法的日期。
选择框的不可用状态。你也可以通过数组单独禁用 RangePicker 的其中一项。
在范围选择时，可以允许留空。这对于需要保留“至今”日期项颇为有用。
可以预设常用的日期范围以提高用户体验。自 5.8.0 开始，preset value 支持回调函数返回值方式。
三种大小的输入框，若不设置，则为 middle。
通过 components 替换对应面板。
使用 status 为 DatePicker 添加状态，可选 error 或者 warning。
可以通过 placement 手动指定弹出的位置。
通用属性参考：通用属性
日期类组件包括以下五种形式。
默认配置为 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 |
| defaultOpen | 是否默认展开控制弹层 | boolean | - | |
| 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 | underlined | outlined | 5.13.0 | underlined: 5.24.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 | #cbe0fd |
| cellRangeBorderColor | 选取范围时单元格边框色 | string | #82b4f9 |
| 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。
欢迎阅读博客《为什么禁用日期这么难？》了解如何使用。