logoAnt Design

⌘ K
  • 设计
  • 研发
  • 组件
  • 博客
  • 资源
  • 国内镜像
5.25.3
  • 组件总览
  • 通用
    • Button按钮
    • FloatButton悬浮按钮
      5.0.0
    • Icon图标
    • Typography排版
  • 布局
    • Divider分割线
    • Flex弹性布局
      5.10.0
    • Grid栅格
    • Layout布局
    • Space间距
    • Splitter分隔面板
      5.21.0
  • 导航
    • Anchor锚点
    • Breadcrumb面包屑
    • Dropdown下拉菜单
    • Menu导航菜单
    • Pagination分页
    • Steps步骤条
    • Tabs标签页
  • 数据录入
    • AutoComplete自动完成
    • Cascader级联选择
    • Checkbox多选框
    • ColorPicker颜色选择器
      5.5.0
    • DatePicker日期选择框
    • Form表单
    • Input输入框
    • InputNumber数字输入框
    • Mentions提及
    • Radio单选框
    • Rate评分
    • Select选择器
    • Slider滑动输入条
    • Switch开关
    • TimePicker时间选择框
    • Transfer穿梭框
    • TreeSelect树选择
    • Upload上传
  • 数据展示
    • Avatar头像
    • Badge徽标数
    • Calendar日历
    • Card卡片
    • Carousel走马灯
    • Collapse折叠面板
    • Descriptions描述列表
    • Empty空状态
    • Image图片
    • List列表
    • Popover气泡卡片
    • QRCode二维码
      5.1.0
    • Segmented分段控制器
    • Statistic统计数值
    • Table表格
    • Tag标签
    • Timeline时间轴
    • Tooltip文字提示
    • Tour漫游式引导
      5.0.0
    • Tree树形控件
  • 反馈
    • Alert警告提示
    • Drawer抽屉
    • Message全局提示
    • Modal对话框
    • Notification通知提醒框
    • Popconfirm气泡确认框
    • Progress进度条
    • Result结果
    • Skeleton骨架屏
    • Spin加载中
    • Watermark水印
      5.1.0
  • 其他
    • Affix固钉
    • App包裹组件
      5.1.0
    • ConfigProvider全局化配置
    • Util工具类
      5.13.0

DatePicker
日期选择框

输入或选择日期的控件。
使用import { DatePicker } from "antd";
源码components/date-picker
文档
编辑此页更新日志

相关资源

Ant Design X
Ant Design Charts
Ant Design Pro
Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Web3
Ant Design Landing-首页模板集
Scaffolds-脚手架市场
Umi-React 应用开发框架
dumi-组件/文档研发工具
qiankun-微前端框架
Ant Motion-设计动效
国内镜像站点 🇨🇳

社区

Awesome Ant Design
Medium
Twitter
yuque logoAnt Design 语雀专栏
Ant Design 知乎专栏
体验科技专栏
seeconf logoSEE Conf-蚂蚁体验科技大会
加入我们

帮助

GitHub
更新日志
常见问题
报告 Bug
议题
讨论区
StackOverflow
SegmentFault

Ant XTech logo更多产品

yuque logo语雀-构建你的数字花园
AntV logoAntV-数据可视化解决方案
Egg logoEgg-企业级 Node.js 框架
Kitchen logoKitchen-Sketch 工具集
Galacean logoGalacean-互动图形解决方案
xtech logo蚂蚁体验科技
主题编辑器
Made with ❤ by
蚂蚁集团和 Ant Design 开源社区
开发
设计

何时使用

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

代码演示

基本

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
+ 2 ...
+ 2 ...
+ 2 ...
多选

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
5.14.0
Time
切换不同的选择器

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
日期时间选择

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
日期限定范围

通过 minDate 和 maxDate 限定日期范围。

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
5.14.0
不可选择日期和时间

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
7 days range
6 months range
选择不超过一定的范围

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
额外的页脚

在浮层中加入额外的页脚,以满足某些定制信息的需求。

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
定制单元格

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
2025-05-26
外部使用面板

自定义菜单,外置选择面板。

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
自定义状态

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code




弹出位置

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
范围选择器

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
选择确认

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
5.14.0
日期格式

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
格式对齐

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
5.14.0
禁用

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
允许留空

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
预设范围

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
三种大小

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
定制面板

通过 components 替换对应面板。

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

By locale props

By ConfigProvider

佛历格式

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
5.14.0
形态变体

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

CodeSandbox Icon
codeblock
codepen icon
External Link Icon
expand codeexpand code
5.13.0
ab
ab
ab
ab
Event Period
Event Period
前后缀

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

CodeSandbox Icon
codeblock
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 参数,参考:默认配置。

jsx
// 默认语言为 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>;
WARNING

在搭配 Next.js 的 App Router 使用时,注意在引入 dayjs 的 locale 文件时加上 'use client'。这是由于 Ant Design 的组件都是客户端组件,在 RSC 中引入 dayjs 的 locale 文件将不会在客户端生效。

共同的 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
defaultOpen是否默认展开控制弹层boolean-
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额外的弹出日历 className,使用 classNames.popup.root 替代string-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额外的弹出日历样式,使用 styles.popup.root 替代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#format。formatTypeYYYY-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#format。formatTypeYYYY
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#format。formatTypeYYYY-\QQ
multiple是否为多选booleanfalse5.14.0
renderExtraFooter在面板中添加额外的页脚() => React.ReactNode-
value日期dayjs-
onChange时间发生变化的回调,发生在用户选择时间时function(date: dayjs, dateString: string)-

DatePicker[picker=month]

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

DatePicker[picker=week]

参数说明类型默认值版本
defaultValue默认日期dayjs-
format展示的日期格式,配置参考 dayjs#format。formatTypeYYYY-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#format。formatTypeYYYY-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

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

Semantic DOM

  • root
    5.25.0
    根元素
  • popup.root
    5.25.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

js
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。

如何理解禁用时间日期?

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