DatePicker 日期选择

选择日期/月份/年份(可带具体时间点)的组件。

DatePicker 日期选择框

日期选择模式

DatePicker/RangePicker 在交互上增加了操作焦点的设置,意味着,如果某个输入框处于 focus 态,那么当前选择的日期将会作用于该输入框对应的日期。

如上图所示,带时间的 RangePicker 有 4 个输入焦点,分别为开始日期、开始时间、结束日期、结束时间。当用户激活某个输入框时,此时下拉选择的日期将会作用域该输入框。同时设置了如下两个规则:

  1. 已选定日期范围后,当焦点在开始日期时,如果即将选择的日期大于结束日期,将会重设开始日期。

  2. 已选定日期范围后,当焦点在结束日期时,如果即将选择的日期小于开始日期,将会重设开始日期。

日期值的多语言

由于 Calendar 组件内部使用 moment 对象来设置日期(请使用最新版 moment),部分 Locale 读取自 moment,因此用户需要在外部使用时正确的设置 moment 的 locale

  • Q: 文档站点上看是中式日历,为什么我本地却是美式日历呢?如何进行多语言适配?
    A: 日期的多语言情况比较复杂,涉及到年、月、日、星期、阅读习惯等多方面(美式从周日到周六,中式从周一到周日),因此我们借助了成熟的时间库 moment.js 来进行日期的多语言处理。 moment.js 默认支持美式表达,如需中文等其他语言,请引入moment-with-locales.js语言包。

import moment from 'moment';

moment.locale('zh-cn');

此外,当改变 moment 的全局 locale 时并不会修改之前的已有实例,例如:

moment.locale('fr');
const m = moment(1316116057189);
m.fromNow(); // il y a une heure

moment.locale('en');
m.fromNow(); // il y a une heure
moment(1316116057189).fromNow(); // an hour ago

除了全局设置 moment 的多语言,还可以只对某个 moment 实例设置多语言。比如:

const value = moment();
value.locale('fr'); // set this instance to use French

Moment 对象和字符串

DatePicker 默认情况下接收和返回的数据类型都是 Moment 对象。为了便于用户的使用,DatePikcer 还支持直接传入字符串(组件内部仍然会格式化为 Moment 对象)。使用方法如下:

标准非受控

<DatePicker onChange={val => console.log(val)} />
// select 2019-01-23
// >> MomentObject

<DatePicker defaultValue={moment()} onChange={val => console.log(val)} />
// select 2019-01-23
// >> MomentObject

<DatePicker defaultValue="2018-01-23" onChange={val => console.log(val)} />
// select 2019-01-23
// >> "2019-01-23"

标准受控

<DatePicker value={moment()} onChange={val => console.log(val)} />
// setProps({ value: moment().add(1, 'months') })
// >> MomentObject

<DatePicker value="2018-01-23" onChange={val => console.log(val)} />
// setProps({ value: '2019-01-23' })
// >> "2019-01-23"






基本用法

最基本的用法。可以通过 onChange 监听选中值的变化。







提供默认值

可以通过 defaultValue 属性为日期选择器提供初值,所提供的初值必须为 moment 对象。

Setting last month as default visible month





Setting 2017 as default visible year

面板的默认展现日期

可以通过 defaultVisibleMonthdefaultVisibleYear 属性可以修改面板的默认展现日期。

  

不同尺寸

通过 size 属性可以改变 Input 组件的尺寸,默认为 medium







禁止选择某些日期

可以通过 disabledDate 属性来禁止用户选择或输入某些特定日期。

DatePicker With Time

DatePicker with Time, reset 00:00:00 for every select

DatePicker with Time, with default time value

RangePicker with Time

RangePicker with Time, reset 00:00:00 for every select

RangePicker with Time, with default time value, hide seconds

日期时间选择

如果需要同时选择时间,可以通过 showTime 属性开启,showTime 支持传入 TimePickerPanel 的属性,例如 format, defaultValue 等。

  

禁用日期选择

当开启 disabled 属性时,选择框处于完全禁用状态。







日期格式

通过 format 属性可以约束日期选择器的日期格式,该格式同时会限定用户的输入格式。

-

自定义日期范围选择

如果默认的 RangePicker 在交互上无法满足您的使用需求,还可以基于 DatePicker 封装实现类似的功能。 例如,示例中的日期选择可以自由的更改开始或结束日期,而不必每次选择时重置日期。

Change popup align

Change popup container

自定义日期选择器弹层

组件对外透出了 visible, defaultVisible, onVisibleChange, popupTriggerType, popupAlign, popupContainer, popupStyle, popupClassName 等属性用于直接定制弹层。此外,如果这些属性仍然无法满足需求,可以通过 popupProps 进行透传。









与 Field 结合

与 Field 结合使用,简单示范自定义返回值

自定义触发器

通过 triggerRender 可以自定义 DatePicker 或 RangePicker 的触发器。



无障碍

支持手动输入或键盘操作,请参考ARIA and KeyBoard

DatePicker

2024 年 11 月
27
28
29
30
31
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
01
02
03
04
05
06
07

RangePicker

~
2024 11 月
2024 12 月
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
1
2
3
4
5
6
7
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11

行内模式

API

DatePicker

参数说明类型默认值
label输入框内置标签ReactNode-
size输入框尺寸

可选值:
'small', 'medium'
Enum'medium'
state输入框状态

可选值:
'success', 'loading', 'error'
Enum-
placeholder输入提示String-
defaultVisibleMonth默认展现的月

签名:
Function() => MomentObject
返回值:
{MomentObject} 返回包含指定月份的 moment 对象实例
Function-
value日期值(受控)moment 对象custom-
defaultValue初始日期值,moment 对象custom-
format日期值的格式(用于限定用户输入和展示)String'YYYY/MM/DD'
showTime是否使用时间控件,传入 TimePicker 的属性 { defaultValue, format, ... }Object/Booleanfalse
resetTime每次选择日期时是否重置时间(仅在 showTime 开启时有效)Booleanfalse
disabledDate禁用日期函数

签名:
Function(日期值: MomentObject, view: String) => Boolean
参数:
日期值: {MomentObject} null
view: {String} 当前视图类型,year: 年, month: 月, date: 日
返回值:
{Boolean} 是否禁用
Function() => false
footerRender自定义面板页脚

签名:
Function() => Node
返回值:
{Node} 自定义的面板页脚组件
Function() => null
onChange日期值改变时的回调

签名:
Function(value: MomentObject/String) => void
参数:
value: {MomentObject/String} 日期值
Functionfunc.noop
onOk点击确认按钮时的回调

签名:
Function() => MomentObject/String
返回值:
{MomentObject/String} 日期值
Functionfunc.noop
disabled是否禁用Boolean-
hasClear是否显示清空按钮Booleantrue
visible弹层显示状态Boolean-
defaultVisible弹层默认是否显示Booleanfalse
onVisibleChange弹层展示状态变化时的回调

签名:
Function(visible: Boolean, type: String) => void
参数:
visible: {Boolean} 弹层是否显示
type: {String} 触发弹层显示和隐藏的来源 calendarSelect 表示由日期表盘的选择触发; okBtnClick 表示由确认按钮触发; fromTrigger 表示由trigger的点击触发; docClick 表示由document的点击触发
Functionfunc.noop
popupTriggerType弹层触发方式

可选值:
'click', 'hover'
Enum'click'
popupAlign弹层对齐方式,具体含义见 OverLay文档String'tl bl'
popupContainer弹层容器

签名:
Function(target: Element) => Element
参数:
target: {Element} 目标元素
返回值:
{Element} 弹层的容器元素
Function-
popupStyle弹层自定义样式Object-
popupClassName弹层自定义样式类String-
popupProps弹层其他属性Object-
followTrigger是否跟随滚动Boolean-
inputProps输入框其他属性Object-
triggerRender自定义触发器渲染函数

签名:
Function(value: Object, state: Object) => ReactNode
参数:
value: {Object} 日期值(moment对象),可能为空 state: {Object} 附加属性 state.popupVisible: 时间选择器弹层打开状态
返回值:
{ReactNode} null
Function-
dateCellRender自定义日期渲染函数

签名:
Function(value: Object) => ReactNode
参数:
value: {Object} 日期值(moment对象)
返回值:
{ReactNode} null
Function-
monthCellRender自定义月份渲染函数

签名:
Function(calendarDate: Object) => ReactNode
参数:
calendarDate: {Object} 对应 Calendar 返回的自定义日期对象
返回值:
{ReactNode} null
Function-
dateInputAriaLabel日期输入框的 aria-label 属性String-
timeInputAriaLabel时间输入框的 aria-label 属性String-

DatePicker.MonthPicker

参数说明类型默认值
label输入框内置标签ReactNode-
size输入框尺寸

可选值:
'small', 'medium'
Enum'medium'
state输入框状态

可选值:
'success', 'loading', 'error'
Enum-
placeholder输入提示String-
defaultVisibleYear默认展现的年

签名:
Function() => MomentObject
返回值:
{MomentObject} 返回包含指定年份的 moment 对象实例
Function-
value日期值(受控)moment 对象custom-
defaultValue初始日期值,moment 对象custom-
format日期值的格式(用于限定用户输入和展示)String'YYYY/MM'
disabledDate禁用日期函数

签名:
Function(日期值: MomentObject, view: String) => Boolean
参数:
日期值: {MomentObject} null
view: {String} 当前视图类型,year: 年, month: 月, date: 日
返回值:
{Boolean} 是否禁用
Function() => false
footerRender自定义面板页脚

签名:
Function() => Node
返回值:
{Node} 自定义的面板页脚组件
Function() => null
onChange日期值改变时的回调

签名:
Function(value: MomentObject/String) => void
参数:
value: {MomentObject/String} 日期值
Functionfunc.noop
disabled是否禁用Boolean-
hasClear是否显示清空按钮Booleantrue
visible弹层显示状态Boolean-
defaultVisible弹层默认是否显示Boolean-
onVisibleChange弹层展示状态变化时的回调

签名:
Function(visible: Boolean, type: String) => void
参数:
visible: {Boolean} 弹层是否显示
type: {String} 触发弹层显示和隐藏的来源 calendarSelect 表示由日期表盘的选择触发; fromTrigger 表示由trigger的点击触发; docClick 表示由document的点击触发
Functionfunc.noop
popupTriggerType弹层触发方式

可选值:
'click', 'hover'
Enum'click'
popupAlign弹层对齐方式, 具体含义见 OverLay文档String'tl bl'
popupContainer弹层容器

签名:
Function(target: Element) => Element
参数:
target: {Element} 目标元素
返回值:
{Element} 弹层的容器元素
Function-
popupStyle弹层自定义样式Object-
popupClassName弹层自定义样式类String-
popupProps弹层其他属性Object-
followTrigger是否跟随滚动Boolean-
inputProps输入框其他属性Object-
monthCellRender自定义月份渲染函数

签名:
Function(calendarDate: Object) => ReactNode
参数:
calendarDate: {Object} 对应 Calendar 返回的自定义日期对象
返回值:
{ReactNode} null
Function-
dateInputAriaLabel日期输入框的 aria-label 属性String-

DatePicker.RangePicker

参数说明类型默认值
defaultVisibleMonth默认展示的起始月份

签名:
Function() => MomentObject
返回值:
{MomentObject} 返回包含指定月份的 moment 对象实例
Function-
size输入框尺寸

可选值:
'small', 'medium'
Enum'medium'
value日期范围值数组 moment, momentArray-
defaultValue初始的日期范围值数组 moment, momentArray-
format日期格式String'YYYY/MM/DD'
showTime是否使用时间控件,支持传入 TimePicker 的属性Object/Booleanfalse
resetTime每次选择是否重置时间(仅在 showTime 开启时有效)Booleanfalse
disabledDate禁用日期函数

签名:
Function(日期值: MomentObject, view: String) => Boolean
参数:
日期值: {MomentObject} null
view: {String} 当前视图类型,year: 年, month: 月, date: 日
返回值:
{Boolean} 是否禁用
Function() => false
footerRender自定义面板页脚

签名:
Function() => Node
返回值:
{Node} 自定义的面板页脚组件
Function() => null
onChange日期范围值改变时的回调 [ MomentObjectString, MomentObjectString ]

签名:
Function(value: Array) => void
参数:
value: {Array} 日期值
Functionfunc.noop
onOk点击确认按钮时的回调 返回开始时间和结束时间[ MomentObject|String, MomentObject|String ]

签名:
Function() => Array
返回值:
{Array} 日期范围
Functionfunc.noop
label输入框内置标签ReactNode-
state输入框状态

可选值:
'error', 'loading', 'success'
Enum-
disabled是否禁用Boolean-
hasClear是否显示清空按钮Booleantrue
visible弹层显示状态Boolean-
defaultVisible弹层默认是否显示Booleanfalse
onVisibleChange弹层展示状态变化时的回调

签名:
Function(visible: Boolean, type: String) => void
参数:
visible: {Boolean} 弹层是否显示
type: {String} 触发弹层显示和隐藏的来源 okBtnClick 表示由确认按钮触发; fromTrigger 表示由trigger的点击触发; docClick 表示由document的点击触发
Functionfunc.noop
popupTriggerType弹层触发方式

可选值:
'click', 'hover'
Enum'click'
popupAlign弹层对齐方式, 具体含义见 OverLay文档String'tl bl'
popupContainer弹层容器

签名:
Function(target: Element) => Element
参数:
target: {Element} 目标元素
返回值:
{Element} 弹层的容器元素
Function-
popupStyle弹层自定义样式Object-
popupClassName弹层自定义样式类String-
popupProps弹层其他属性Object-
followTrigger是否跟随滚动Boolean-
inputProps输入框其他属性Object-
triggerRender自定义触发器渲染函数

签名:
Function(value: Array, state: Object) => ReactNode
参数:
value: {Array} 日期值(moment对象)数组,单个值可能为空 state: {Object} 附加属性 state.popupVisible: 时间选择器弹层打开状态
返回值:
{ReactNode} null
Function-
dateCellRender自定义日期单元格渲染

签名:
Function() => void
Function-
monthCellRender自定义月份渲染函数

签名:
Function(calendarDate: Object) => ReactNode
参数:
calendarDate: {Object} 对应 Calendar 返回的自定义日期对象
返回值:
{ReactNode} null
Function-
startDateInputAriaLabel开始日期输入框的 aria-label 属性String-
startTimeInputAriaLabel开始时间输入框的 aria-label 属性String-
endDateInputAriaLabel结束日期输入框的 aria-label 属性String-
endTimeInputAriaLabel结束时间输入框的 aria-label 属性String-

DatePicker.YearPicker

参数说明类型默认值
label输入框内置标签ReactNode-
size输入框尺寸

可选值:
'small', 'medium'
Enum'medium'
state输入框状态

可选值:
'success', 'loading', 'error'
Enum-
placeholder输入提示String-
value日期值(受控)moment 对象custom-
defaultValue初始日期值,moment 对象custom-
format日期值的格式(用于限定用户输入和展示)String'YYYY'
disabledDate禁用日期函数

签名:
Function(日期值: MomentObject, view: String) => Boolean
参数:
日期值: {MomentObject} null
view: {String} 当前视图类型,year: 年, month: 月, date: 日
返回值:
{Boolean} 是否禁用
Function() => false
footerRender自定义面板页脚

签名:
Function() => Node
返回值:
{Node} 自定义的面板页脚组件
Function() => null
onChange日期值改变时的回调

签名:
Function(value: MomentObject/String) => void
参数:
value: {MomentObject/String} 日期值
Functionfunc.noop
disabled是否禁用Boolean-
hasClear是否显示清空按钮Booleantrue
visible弹层显示状态Boolean-
defaultVisible弹层默认是否显示Boolean-
onVisibleChange弹层展示状态变化时的回调

签名:
Function(visible: Boolean, reason: String) => void
参数:
visible: {Boolean} 弹层是否显示
reason: {String} 触发弹层显示和隐藏的来源 calendarSelect 表示由日期表盘的选择触发; fromTrigger 表示由trigger的点击触发; docClick 表示由document的点击触发
Functionfunc.noop
popupTriggerType弹层触发方式

可选值:
'click', 'hover'
Enum'click'
popupAlign弹层对齐方式, 具体含义见 OverLay文档String'tl bl'
popupContainer弹层容器

签名:
Function(target: Element) => Element
参数:
target: {Element} 目标元素
返回值:
{Element} 弹层的容器元素
Function-
popupStyle弹层自定义样式Object-
popupClassName弹层自定义样式类String-
popupProps弹层其他属性Object-
followTrigger是否跟随滚动Boolean-
inputProps输入框其他属性Object-
dateInputAriaLabel日期输入框的 aria-label 属性String-

DatePicker系列组件实例方法

参数说明
getOverlay获取底层的Overlay实例。获取DatePicker实例前用getInstance方法获取真正的实例,详见ConfigProvider章节

ARIA and KeyBoard

同选择框一样聚焦到 DatePiker 后,需要按下 ENTER 键打开弹出框,选择/输入日期, 通过 TAB 切换日期和时间输入框。

按键说明
数字键需要手动输入日期,指定的日期格式
Enter打开日期选择框或输入后选择日期
Esc关闭日期选择框
Up输入上一天(Month Picker 则是上一个月, Year Picker 则是上一年)
Down输入下一天(Month Picker 则是下一个月, Year Picker 则是下一年)
Page Up输入上一月
Page Down输入下一月
Alt + Page Up输入上一年
Alt + Page Down输入下一年