* docs: DatePicker design tab * docs: add design demo * docs: add anchor for design demo * docs: init g6 * docs: behavior map * test: fix test cov * docs: behavior map comp * docs: add map title * docs: fix ssr * docs: update demo * docs: optimize copy ux * docs: update demo * chore: code clean
14 KiB
category | group | title | description | cover | coverDark | demo | ||
---|---|---|---|---|---|---|---|---|
Components | Data Entry | DatePicker | To select or input a date. | https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*xXA9TJ8BTioAAAAAAAAAAAAADrJ8AQ/original | https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*3OpRQKcygo8AAAAAAAAAAAAADrJ8AQ/original |
|
When To Use
By clicking the input box, you can select a date from a popup calendar.
Examples
Basic
Range Picker
Switchable picker
Date Format
Choose Time
Disabled
Disabled Date & Time
Select range dates in 7 days
Preset Ranges
Extra Footer
Three Sizes
Customized Date Rendering
Status
Bordered-less
Placement
Controlled Panels
Customized Range Picker
Suffix
_InternalPanelDoNotUseOrYouWillBeFired
API
There are five kinds of picker:
- DatePicker
- DatePicker[picker="month"]
- DatePicker[picker="week"]
- DatePicker[picker="year"]
- DatePicker[picker="quarter"] (Added in 4.1.0)
- RangePicker
Localization
The default locale is en-US, if you need to use other languages, recommend to use internationalized components provided by us at the entrance. Look at: ConfigProvider.
If there are special needs (only modifying single component language), Please use the property: local. Example: default.
import 'dayjs/locale/zh-cn';
import locale from 'antd/es/date-picker/locale/zh_CN';
<DatePicker locale={locale} />;
// The default locale is en-US, if you want to use other locale, just set locale in entry file globally.
import dayjs from 'dayjs';
import 'dayjs/locale/zh-cn';
import locale from 'antd/locale/zh_CN';
<ConfigProvider locale={locale}>
<DatePicker defaultValue={dayjs('2015-01-01', 'YYYY-MM-DD')} />
</ConfigProvider>;
Common API
The following APIs are shared by DatePicker, RangePicker.
Property | Description | Type | Default | Version |
---|---|---|---|---|
allowClear | Whether to show clear button | boolean | true | |
autoFocus | If get focus when component mounted | boolean | false | |
bordered | Whether has border style | boolean | true | |
className | The picker className | string | - | |
dateRender | Custom rendering function for date cells | function(currentDate: dayjs, today: dayjs) => React.ReactNode | - | |
disabled | Determine whether the DatePicker is disabled | boolean | false | |
disabledDate | Specify the date that cannot be selected | (currentDate: dayjs) => boolean | - | |
popupClassName | To customize the className of the popup calendar | string | - | 4.23.0 |
getPopupContainer | To set the container of the floating layer, while the default is to create a div element in body |
function(trigger) | - | |
inputReadOnly | Set the readonly attribute of the input tag (avoids virtual keyboard on touch devices) |
boolean | false | |
locale | Localization configuration | object | default | |
mode | The picker panel mode( Cannot select year or month anymore? ) | time | date | month | year | decade |
- | |
nextIcon | The custom next icon | ReactNode | - | 4.17.0 |
open | The open state of picker | boolean | - | |
panelRender | Customize panel render | (panelNode) => ReactNode | - | 4.5.0 |
picker | Set picker type | date | week | month | quarter | year |
date |
quarter : 4.1.0 |
placeholder | The placeholder of date input | string | [string,string] | - | |
placement | The position where the selection box pops up | bottomLeft bottomRight topLeft topRight |
bottomLeft | |
popupStyle | To customize the style of the popup calendar | CSSProperties | {} | |
presets | The preset ranges for quick selection | { label: React.ReactNode, value: dayjs }[] | - | |
prevIcon | The custom prev icon | ReactNode | - | 4.17.0 |
size | To determine the size of the input box, the height of large and small , are 40px and 24px respectively, while default size is 32px |
large | middle | small |
- | |
status | Set validation status | 'error' | 'warning' | - | 4.19.0 |
style | To customize the style of the input box | CSSProperties | {} | |
suffixIcon | The custom suffix icon | ReactNode | - | |
superNextIcon | The custom super next icon | ReactNode | - | 4.17.0 |
superPrevIcon | The custom super prev icon | ReactNode | - | 4.17.0 |
onOpenChange | Callback function, can be executed whether the popup calendar is popped up or closed | function(open) | - | |
onPanelChange | Callback when picker panel mode is changed | function(value, mode) | - |
Common Methods
Name | Description | Version |
---|---|---|
blur() | Remove focus | |
focus() | Get focus |
DatePicker
Property | Description | Type | Default | Version |
---|---|---|---|---|
defaultPickerValue | To set default picker date | dayjs | - | |
defaultValue | To set default date, if start time or end time is null or undefined, the date range will be an open interval | dayjs | - | |
disabledTime | To specify the time that cannot be selected | function(date) | - | |
format | To set the date format, refer to dayjs. When an array is provided, all values are used for parsing and first value is used for formatting, support Custom Format | string | (value: dayjs) => string | (string | (value: dayjs) => string)[] | YYYY-MM-DD |
|
renderExtraFooter | Render extra footer in panel | (mode) => React.ReactNode | - | |
showNow | Whether to show 'Now' button on panel when showTime is set |
boolean | - | 4.4.0 |
showTime | To provide an additional time selection | object | boolean | TimePicker Options | |
showTime.defaultValue | To set default time of selected date, demo | dayjs | dayjs() | |
showToday | Whether to show Today button |
boolean | true | |
value | To set date | dayjs | - | |
onChange | Callback function, can be executed when the selected time is changing | function(date: dayjs, dateString: string) | - | |
onOk | Callback when click ok button | function() | - | |
onPanelChange | Callback function for panel changing | function(value, mode) | - |
DatePicker[picker=year]
Property | Description | Type | Default | Version |
---|---|---|---|---|
defaultPickerValue | To set default picker date | dayjs | - | |
defaultValue | To set default date | dayjs | - | |
format | To set the date format, refer to dayjs | string | YYYY |
|
renderExtraFooter | Render extra footer in panel | () => React.ReactNode | - | |
value | To set date | dayjs | - | |
onChange | Callback function, can be executed when the selected time is changing | function(date: dayjs, dateString: string) | - |
DatePicker[picker=quarter]
Added in 4.1.0
.
Property | Description | Type | Default | Version |
---|---|---|---|---|
defaultPickerValue | To set default picker date | dayjs | - | |
defaultValue | To set default date | dayjs | - | |
format | To set the date format, refer to dayjs | string | YYYY-\QQ |
|
renderExtraFooter | Render extra footer in panel | () => React.ReactNode | - | |
value | To set date | dayjs | - | |
onChange | Callback function, can be executed when the selected time is changing | function(date: dayjs, dateString: string) | - |
DatePicker[picker=month]
Property | Description | Type | Default | Version |
---|---|---|---|---|
defaultPickerValue | To set default picker date | dayjs | - | |
defaultValue | To set default date | dayjs | - | |
format | To set the date format, refer to dayjs | string | YYYY-MM |
|
monthCellRender | Custom month cell content render method | function(date, locale): ReactNode | - | |
renderExtraFooter | Render extra footer in panel | () => React.ReactNode | - | |
value | To set date | dayjs | - | |
onChange | Callback function, can be executed when the selected time is changing | function(date: dayjs, dateString: string) | - |
DatePicker[picker=week]
Property | Description | Type | Default | Version |
---|---|---|---|---|
defaultPickerValue | To set default picker date | dayjs | - | |
defaultValue | To set default date | dayjs | - | |
format | To set the date format, refer to dayjs | string | YYYY-wo |
|
renderExtraFooter | Render extra footer in panel | (mode) => React.ReactNode | - | |
value | To set date | dayjs | - | |
onChange | Callback function, can be executed when the selected time is changing | function(date: dayjs, dateString: string) | - |
RangePicker
Property | Description | Type | Default | Version |
---|---|---|---|---|
allowEmpty | Allow start or end input leave empty | [boolean, boolean] | [false, false] | |
dateRender | Customize date cell. info argument is added in 4.3.0 |
function(currentDate: dayjs, today: dayjs, info: { range: start | end }) => React.ReactNode |
- | |
defaultPickerValue | To set default picker date | [dayjs, dayjs] | - | |
defaultValue | To set default date | [dayjs, dayjs] | - | |
disabled | If disable start or end | [boolean, boolean] | - | |
disabledTime | To specify the time that cannot be selected | function(date: dayjs, partial: start | end ) |
- | |
format | To set the date format, refer to dayjs. When an array is provided, all values are used for parsing and first value is used for formatting | string | string[] | YYYY-MM-DD HH:mm:ss |
|
presets | The preset ranges for quick selection | { label: React.ReactNode, value: dayjs[] }[] | - | |
renderExtraFooter | Render extra footer in panel | () => React.ReactNode | - | |
separator | Set separator between inputs | React.ReactNode | <SwapRightOutlined /> |
|
showTime | To provide an additional time selection | object | boolean | TimePicker Options | |
showTime.defaultValue | To set default time of selected date, demo | dayjs[] | [dayjs(), dayjs()] | |
value | To set date | [dayjs, dayjs] | - | |
onCalendarChange | Callback function, can be executed when the start time or the end time of the range is changing. info argument is added in 4.4.0 |
function(dates: [dayjs, dayjs], dateStrings: [string, string], info: { range:start |end }) |
- | |
onChange | Callback function, can be executed when the selected time is changing | function(dates: [dayjs, dayjs], dateStrings: [string, string]) | - |
FAQ
When set mode to DatePicker/RangePicker, cannot select year or month anymore?
Please refer FAQ
How to use DatePicker with customize date library like dayjs?
Please refer Use custom date library
Why config dayjs.locale globally not work?
DatePicker default set locale
as en
in v4. You can config DatePicker locale
prop or ConfigProvider locale
prop instead.
Date-related components locale is not working?
See FAQ Date-related-components-locale-is-not-working?
How to modify start day of week?
Please use correct language (#5605), or update dayjs locale
config:
import dayjs from 'dayjs';
import 'dayjs/locale/zh-cn';
import 'dayjs/plugin/updateLocale';
dayjs.updateLocale('zh-cn', {
weekStart: 0,
});
Why origin panel don't switch when using panelRender
?
When you change the layout of nodes by panelRender
, React will unmount and re-mount it which reset the component state. You should keep the layout stable. Please ref #27263 for more info.