DatePicker
日期选择框

输入或选择日期的控件。
使用import{ DatePicker }from"antd";

何时使用

当用户需要输入一个日期,可以点击标准输入框,弹出日期面板进行选择。

代码演示

最简单的用法,在浮层中可以选择或者输入日期。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

多选,不支持 showTime 以及 picker="time"

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.14.0
Time

提供选择器,自由切换不同类型的日期选择器,常用于日期筛选场合。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

增加选择时间功能,当 showTime 为一个对象时,其属性会传递给内建的 TimePicker

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

通过 minDatemaxDate 限定日期范围。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.14.0

可用 disabledDatedisabledTime 分别禁止选择部分日期和时间,其中 disabledTime 需要和 showTime 一起使用。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
7 days range
6 months range

使用 disabledDateinfo.from 来限制动态的日期区间选择。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

使用 cellRender 可以自定义单元格的内容和样式。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

By locale props

By ConfigProvider

通过 locale 配置支持特殊的年历格式。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.14.0

DatePicker 形态变体,可选 outlined filled borderless underlined 四种形态。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.13.0
ab
ab
ab
ab

自定义前缀 prefix 和后缀图标 suffixIcon

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

通过设置 picker 属性,指定范围选择器类型。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

DatePicker 默认会根据 picker 的交互行为,自动选择是否需要确认按钮。你也可以通过 needConfirm 属性来手动设置是否需要确认按钮。当有 needConfirm 时,用户始终需要点击确认按钮才能完成选择。反之,则会在选择或者失去焦点时提交。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.14.0

使用 format 属性,可以自定义日期显示格式。当 format 为数组时,选择器输入框可以输入数组中任意一个有效格式。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

输入格式对齐,通过键盘左右切换焦点。失去焦点时会尝试对齐到最后合法的日期。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.14.0

选择框的不可用状态。你也可以通过数组单独禁用 RangePicker 的其中一项。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

在范围选择时,可以允许留空。这对于需要保留“至今”日期项颇为有用。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

可以预设常用的日期范围以提高用户体验。自 5.8.0 开始,preset value 支持回调函数返回值方式。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

三种大小的输入框,若不设置,则为 middle

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

通过 components 替换对应面板。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.14.0

使用 status 为 DatePicker 添加状态,可选 error 或者 warning

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code




可以通过 placement 手动指定弹出的位置。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

API

通用属性参考:通用属性

日期类组件包括以下五种形式。

  • DatePicker
  • DatePicker[picker="month"]
  • DatePicker[picker="week"]
  • DatePicker[picker="year"]
  • DatePicker[picker="quarter"] (4.1.0 新增)
  • RangePicker

国际化配置

默认配置为 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>;

共同的 API

以下 API 为 DatePicker、 RangePicker 共享的 API。

参数说明类型默认值版本
allowClear自定义清除按钮boolean | { clearIcon?: ReactNode }true5.8.0: 支持对象类型
autoFocus自动获取焦点booleanfalse
className选择器 classNamestring-
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禁用booleanfalse
disabledDate不可选择的日期(currentDate: dayjs, info: { from?: dayjs, type: Picker }) => boolean-info: 5.14.0
format设置日期格式,为数组时支持多格式匹配,展示以第一个为准。配置参考 dayjs#format。示例:自定义格式formatTyperc-picker
order多选、范围时是否自动排序booleantrue5.14.0
preserveInvalidOnBlur失去焦点是否要清空输入框内无效内容booleanfalse5.14.0
popupClassName额外的弹出日历 classNamestring-4.23.0
getPopupContainer定义浮层的容器,默认为 body 上新建 divfunction(trigger)-
inputReadOnly设置输入框为只读(避免在移动设备上打开虚拟键盘)booleanfalse
locale国际化配置object默认配置
minDate最小日期,同样会限制面板的切换范围dayjs-5.14.0
maxDate最大日期,同样会限制面板的切换范围dayjs-5.14.0
mode日期面板的状态(设置后无法选择年份/月份?time | date | month | year | decade-
needConfirm是否需要确认按钮,为 false 时失去焦点即代表选择。当设置 multiple 时默认为 falseboolean-5.14.0
nextIcon自定义下一个图标ReactNode-4.17.0
open控制弹层是否展开boolean-
panelRender自定义渲染面板(panelNode) => ReactNode-4.5.0
picker设置选择器类型date | week | month | quarter | yeardatequarter: 4.1.0
placeholder输入框提示文字string | [string, string]-
placement选择框弹出的位置bottomLeft bottomRight topLeft topRightbottomLeft
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,默认是 32pxlarge | 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 | underlinedoutlined5.13.0 | underlined: 5.24.0
onOpenChange弹出日历和关闭日历的回调function(open)-
onPanelChange日历面板切换的回调function(value, mode)-

共同的方法

名称描述版本
blur()移除焦点
focus()获取焦点

DatePicker

参数说明类型默认值版本
defaultPickerValue默认面板日期,每次面板打开时会被重置到该日期dayjs-5.14.0
defaultValue默认日期,如果开始时间或结束时间为 null 或者 undefined,日期范围将是一个开区间dayjs-
disabledTime不可选择的时间function(date)-
format展示的日期格式,配置参考 dayjs#formatformatTypeYYYY-MM-DD
multiple是否为多选,不支持 showTimebooleanfalse5.14.0
pickerValue面板日期,可以用于受控切换面板所在日期。配合 onPanelChange 使用。dayjs-5.14.0
renderExtraFooter在面板中添加额外的页脚(mode) => React.ReactNode-
showNow显示当前日期时间的快捷选择boolean-
showTime增加时间选择功能Object | booleanTimePicker Options
showTime.defaultValue设置用户选择日期时默认的时分秒,例子dayjsdayjs()
showWeekDatePicker 下展示当前周booleanfalse5.14.0
value日期dayjs-
onChange时间发生变化的回调function(date: dayjs, dateString: string)-
onOk点击确定按钮的回调function()-
onPanelChange日期面板变化时的回调function(value, mode)-

DatePicker[picker=year]

参数说明类型默认值版本
defaultValue默认日期dayjs-
format展示的日期格式,配置参考 dayjs#formatformatTypeYYYY
multiple是否为多选booleanfalse5.14.0
renderExtraFooter在面板中添加额外的页脚() => React.ReactNode-
value日期dayjs-
onChange时间发生变化的回调,发生在用户选择时间时function(date: dayjs, dateString: string)-

DatePicker[picker=quarter]

4.1.0 新增。

参数说明类型默认值版本
defaultValue默认日期dayjs-
format展示的日期格式,配置参考 dayjs#formatformatTypeYYYY-\QQ
multiple是否为多选booleanfalse5.14.0
renderExtraFooter在面板中添加额外的页脚() => React.ReactNode-
value日期dayjs-
onChange时间发生变化的回调,发生在用户选择时间时function(date: dayjs, dateString: string)-

DatePicker[picker=month]

参数说明类型默认值版本
defaultValue默认日期dayjs-
format展示的日期格式,配置参考 dayjs#formatformatTypeYYYY-MM
multiple是否为多选booleanfalse5.14.0
renderExtraFooter在面板中添加额外的页脚() => React.ReactNode-
value日期dayjs-
onChange时间发生变化的回调,发生在用户选择时间时function(date: dayjs, dateString: string)-

DatePicker[picker=week]

参数说明类型默认值版本
defaultValue默认日期dayjs-
format展示的日期格式,配置参考 dayjs#formatformatTypeYYYY-wo
multiple是否为多选booleanfalse5.14.0
renderExtraFooter在面板中添加额外的页脚(mode) => React.ReactNode-
value日期dayjs-
onChange时间发生变化的回调,发生在用户选择时间时function(date: dayjs, dateString: string)-
showWeekDatePicker 下展示当前周booleantrue5.14.0

RangePicker

参数说明类型默认值版本
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#formatformatTypeYYYY-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|booleanTimePicker 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

formatType

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 新增。

主题变量(Design Token)

组件 Token如何定制?

Token 名称描述类型默认值
activeBg输入框激活状态时背景颜色string#ffffff
activeBorderColor激活态边框色string#1677ff
activeShadow激活态阴影string0 0 0 2px rgba(5,145,255,0.1)
addonBg前/后置标签背景色stringrgba(0,0,0,0.02)
cellActiveWithRangeBg选取范围内的单元格背景色string#e6f4ff
cellBgDisabled单元格禁用态背景色stringrgba(0,0,0,0.04)
cellHeight单元格高度number24
cellHoverBg单元格悬浮态背景色stringrgba(0,0,0,0.04)
cellHoverWithRangeBg选取范围内的单元格悬浮态背景色string#cbe0fd
cellRangeBorderColor选取范围时单元格边框色string#82b4f9
cellWidth单元格宽度number36
errorActiveShadow错误状态时激活态阴影string0 0 0 2px rgba(255,38,5,0.06)
hoverBg输入框hover状态时背景颜色string#ffffff
hoverBorderColor悬浮态边框色string#4096ff
inputFontSize字体大小number14
inputFontSizeLG大号字体大小number16
inputFontSizeSM小号字体大小number14
multipleItemBg多选标签背景色stringrgba(0,0,0,0.06)
multipleItemBorderColor多选标签边框色stringtransparent
multipleItemBorderColorDisabled多选标签禁用边框色stringtransparent
multipleItemColorDisabled多选标签禁用文本颜色stringrgba(0,0,0,0.25)
multipleItemHeight多选标签高度number24
multipleItemHeightLG大号多选标签高度number32
multipleItemHeightSM小号多选标签高度number16
multipleSelectorBgDisabled多选框禁用背景stringrgba(0,0,0,0.04)
paddingBlock输入框纵向内边距number4
paddingBlockLG大号输入框纵向内边距number7
paddingBlockSM小号输入框纵向内边距number0
paddingInline输入框横向内边距number11
paddingInlineLG大号输入框横向内边距number11
paddingInlineSM小号输入框横向内边距number7
presetsMaxWidth预设区域最大宽度number200
presetsWidth预设区域宽度number120
textHeight单元格文本高度number40
timeCellHeight时间单元格高度number28
timeColumnHeight时间列高度number224
timeColumnWidth时间列宽度number56
warningActiveShadow警告状态时激活态阴影string0 0 0 2px rgba(255,215,5,0.1)
withoutTimeCellHeight十年/年/季/月/周单元格高度number66
zIndexPopup弹窗 z-indexnumber1050

全局 Token如何定制?

FAQ

当我指定了 DatePicker/RangePicker 的 mode 属性后,点击后无法选择年份/月份?

请参考常见问答

为何日期选择年份后返回的是日期面板而不是月份面板?

当用户选择完年份后,系统会直接切换至日期面板,而非显式提供月份选择。这样做的设计在于用户只需进行一次点击即可完成年份修改,无需再次点击进入月份选择界面,从而减少了用户的操作负担,同时也避免需要额外感知月份的记忆负担。

如何在 DatePicker 中使用自定义日期库(如 Moment.js )?

请参考《使用自定义日期库》

为什么时间类组件的国际化 locale 设置不生效?

参考 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

如何理解禁用时间日期?

欢迎阅读博客《为什么禁用日期这么难?》了解如何使用。