ant-design/components/date-picker/index.en-US.md
二货爱吃白萝卜 18e85a7b81
feat: New Picker (#46982)
* chore: init

* chore: link picker

* chore: move files

* chore: update style

* chore: update types

* test: update snapshot

* test: update snapshot

* test: update snapshot

* test: update snapshot

* test: update snapshot

* test: fix test case

* test: update snapshot

* test: update snapshot

* test: update snapshot

* test: update snapshot

* chore: clesn up useless types

* chore: update types

* chore: fix types

* chore: fix types

* chore: fix types

* chore: fix types

* chore: fix types

* chore: fix types

* chore: fix types

* chore: fix types

* chore: fix types

* chore: update style

* chore: clean up

* chore: update types

* test: update snapshot

* test: update snapshot

* test: update snapshot

* test: update snapshot

* fix: format

* chore: update deps

* chore: feature merge master (#46794)

* fix: Fix typo s/Notificaiton/Notification/ (#46775)

* docs: supplement form preserve field description (#46788)

close https://github.com/ant-design/ant-design/issues/46773

* docs: tweak changelog drawer width in small screen (#46791)

* docs: Update compatible-style.zh-CN.md (#46790)

Signed-off-by: afc163 <afc163@gmail.com>

---------

Signed-off-by: afc163 <afc163@gmail.com>
Co-authored-by: hugo-syn <61210734+hugo-syn@users.noreply.github.com>
Co-authored-by: Shunze Chen <qianlonwork@outlook.com>
Co-authored-by: afc163 <afc163@gmail.com>

* chore: update locale size

* chore: lock dumi

* test: update snapshot

* test: update snapshot

* test: update snapshot

* test: update snapshot

* test: update snapshot

* test: update snapshot

* chore: bump version

* test: update snapshot

* test: update snapshot

* chore: bump version

* chore: update limit

* test: update snapshot

* docs: update 7 days sample

* chore: rm useless style

* chore: clean up style

* docs: add buddihist era demo

* refactor: interface

* chore: add multiple types

* docs: add demo

* chore: init style

* chore: init style

* chore: fill style

* chore: fill style

* chore: style

* chore: size of it

* chore: size style

* docs: add align demo

* docs: needConfirm

* chore: fix showWeek style

* test: update snapshot

* chore: fix ts

* chore: fix ts

* chore: fix ts

* chore: fix ts

* fix: week style

* docs: update dayjs note

* fix: style missing

* chore: fix footer extra style missing

* test: update snapshot

* test: update snapshot

* test: update snapshot

* test: update snapshot

* chore: demo update

* docs: update demo

* docs: min & max date

* test: update snapshot

* docs: add order

* chore: update deps

* test: update snapshot

* test: update snapshot

* chore: adjust style

* chore: clean up style

* test: update snapshot

* chore: fix comment

* chore: update align

* chore: bump rc-picker

* test: update snapshot

* test: update snapshot

* test: update snapshot

---------

Signed-off-by: afc163 <afc163@gmail.com>
Signed-off-by: lijianan <574980606@qq.com>
Co-authored-by: hugo-syn <61210734+hugo-syn@users.noreply.github.com>
Co-authored-by: Shunze Chen <qianlonwork@outlook.com>
Co-authored-by: afc163 <afc163@gmail.com>
Co-authored-by: lijianan <574980606@qq.com>
2024-01-29 15:34:48 +08:00

17 KiB
Raw Blame History

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
cols
2

When To Use

By clicking the input box, you can select a date from a popup calendar.

Examples

Basic Range Picker Multiple Switchable picker Date Format Choose Time Mask Format Limit Date Range Disabled Disabled Date & Time Allow Empty Select range dates in 7 days Preset Ranges Extra Footer Three Sizes Customized Cell Rendering Customize Panel Buddhist Era Status Variants Filled Debug Placement Controlled Panels Customized Range Picker Suffix _InternalPanelDoNotUseOrYouWillBeFired Component Token

API

Common props refCommon props

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.

:::warning When use with Nextjs App Router, make sure to add 'use client' before import locale file of dayjs. It's because all components of Ant Design only works in client, importing locale in RSC will not work. :::

import locale from 'antd/es/date-picker/locale/zh_CN';

import 'dayjs/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 locale from 'antd/locale/zh_CN';
import dayjs from 'dayjs';

import 'dayjs/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 Customize clear button boolean | { clearIcon?: ReactNode } true 5.8.0: Support object type
autoFocus If get focus when component mounted boolean false
className The picker className string -
dateRender Custom rendering function for date cells, >= 5.4.0 use cellRender instead. function(currentDate: dayjs, today: dayjs) => React.ReactNode - < 5.4.0
cellRender Custom rendering function for picker cells (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 Custom panels Record<Panel | 'input', React.ComponentType> - 5.14.0
disabled Determine whether the DatePicker is disabled boolean false
disabledDate Specify the date that cannot be selected (currentDate: dayjs, info: { from?: dayjs }) => boolean - info: 5.14.0
format To set the date format, support multi-format matching when it is an array, display the first one shall prevail. refer to dayjs#format. for example: Custom Format formatType rc-picker
order Auto order date when multiple or range selection boolean true 5.14.0
popupClassName To customize the className of the popup calendar string - 4.23.0
preserveInvalidOnBlur Not clean input on blur even when the typing is invalidate boolean false 5.14.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
minDate The minimum date, which also limits the range of panel switching dayjs - 5.14.0
maxDate The maximum date, which also limits the range of panel switching dayjs - 5.14.0
mode The picker panel mode Cannot select year or month anymore? ) time | date | month | year | decade -
needConfirm Need click confirm button to trigger value change boolean - 5.14.0
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, Since 5.8.0, preset value supports callback function. { label: React.ReactNode, value: Dayjs | (() => 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
variant Variants of picker outlined | borderless | filled outlined 5.14.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 Default panel date, will be reset when panel open dayjs - 5.14.0
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#format formatType YYYY-MM-DD
pickerValue Panel date. Used for controlled switching of panel date. Work with onPanelChange dayjs - 5.14.0
renderExtraFooter Render extra footer in panel (mode) => React.ReactNode -
showNow Show the fast access of current datetime 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()
showWeek Show week info when in DatePicker boolean false 5.14.0
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
defaultValue To set default date dayjs -
format To set the date format. refer to dayjs#format formatType 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
defaultValue To set default date dayjs -
format To set the date format. refer to dayjs#format formatType 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
defaultValue To set default date dayjs -
format To set the date format. refer to dayjs#format formatType YYYY-MM
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
defaultValue To set default date dayjs -
format To set the date format. refer to dayjs#format formatType 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]
cellRender Custom rendering function for picker cells (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 Custom rendering function for date cells, >= 5.4.0 use cellRender instead. function(currentDate: dayjs, today: dayjs) => React.ReactNode - < 5.4.0
defaultPickerValue Default panel date, will be reset when panel open dayjs - 5.14.0
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#format formatType YYYY-MM-DD HH:mm:ss
id Config input ids { start?: string, end?: string } - 5.14.0
pickerValue Panel date. Used for controlled switching of panel date. Work with onPanelChange dayjs - 5.14.0
presets The preset ranges for quick selection, Since 5.8.0, preset value supports callback function. { label: React.ReactNode, value: (Dayjs | (() => 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]) -
onFocus Trigger when get focus function(event, { range: 'start' | 'end' }) - range: 5.14.0
onBlur Trigger when lose focus 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';
    };

Note: type is added in 5.14.0.

Design Token

FAQ

When set mode to DatePicker/RangePicker, cannot select year or month anymore?

Please refer FAQ

Why does the date picker switch to the date panel after selecting the year instead of the month panel?

After selecting the year, the system directly switches to the date panel instead of month panel. This design is intended to reduce the user's operational burden by allowing them to complete the year modification with just one click, without having to enter the month selection interface again. At the same time, it also avoids additional cognitive burden of remembering the month.

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.

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 updateLocale from 'dayjs/plugin/updateLocale';

dayjs.extend(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.