ant-design/components/time-picker/index.en-US.md
Guo Yunhe 02fc70eb4b
DatePicker and TimePicker support prefix props ()
* feat(DatePicker): DatePicker supports prefix prop

* feat(TimePicker): TimePicker supports prefix prop
2024-10-23 15:00:35 +08:00

140 lines
6.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
category: Components
group: Data Entry
title: TimePicker
description: To select/input a time.
cover: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*kGmGSLk_1fwAAAAAAAAAAAAADrJ8AQ/original
coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*1hDmQJIDFJQAAAAAAAAAAAAADrJ8AQ/original
demo:
cols: 2
---
## When To Use
By clicking the input box, you can select a time from a popup panel.
## Examples
<!-- prettier-ignore -->
<code src="./demo/basic.tsx">Basic</code>
<code src="./demo/value.tsx">Under Control</code>
<code src="./demo/size.tsx">Three Sizes</code>
<code src="./demo/need-confirm.tsx" version="5.14.0">Need Confirm</code>
<code src="./demo/disabled.tsx">disabled</code>
<code src="./demo/hide-column.tsx">Hour and minute</code>
<code src="./demo/interval-options.tsx">interval option</code>
<code src="./demo/addon.tsx">Addon</code>
<code src="./demo/12hours.tsx">12 hours</code>
<code src="./demo/change-on-scroll.tsx" version="5.14.0">Change on scroll</code>
<code src="./demo/colored-popup.tsx" debug>Colored Popup</code>
<code src="./demo/range-picker.tsx">Time Range Picker</code>
<code src="./demo/variant.tsx" version="5.13.0">Variants</code>
<code src="./demo/status.tsx">Status</code>
<code src="./demo/suffix.tsx">Prefix and Suffix</code>
<code src="./demo/render-panel.tsx" debug>_InternalPanelDoNotUseOrYouWillBeFired</code>
## API
---
Common props ref[Common props](/docs/react/common-props)
```jsx
import dayjs from 'dayjs';
import customParseFormat from 'dayjs/plugin/customParseFormat'
dayjs.extend(customParseFormat)
<TimePicker defaultValue={dayjs('13:30:56', 'HH:mm:ss')} />;
```
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| allowClear | Customize clear icon | boolean \| { clearIcon?: ReactNode } | true | 5.8.0: Support object type |
| autoFocus | If get focus when component mounted | boolean | false | |
| cellRender | Custom rendering function for picker cells | (current: number, info: { originNode: React.ReactElement, today: dayjs, range?: 'start' \| 'end', subType: 'hour' \| 'minute' \| 'second' \| 'meridiem' }) => React.ReactNode | - | 5.4.0 |
| changeOnScroll | Trigger selection when scroll the column | boolean | false | 5.14.0 |
| className | The className of picker | string | - | |
| defaultValue | To set default time | [dayjs](http://day.js.org/) | - | |
| disabled | Determine whether the TimePicker is disabled | boolean | false | |
| disabledTime | To specify the time that cannot be selected | [DisabledTime](#disabledtime) | - | 4.19.0 |
| format | To set the time format | string | `HH:mm:ss` | |
| getPopupContainer | To set the container of the floating layer, while the default is to create a div element in body | function(trigger) | - | |
| hideDisabledOptions | Whether hide the options that can not be selected | boolean | false | |
| hourStep | Interval between hours in picker | number | 1 | |
| inputReadOnly | Set the `readonly` attribute of the input tag (avoids virtual keyboard on touch devices) | boolean | false | |
| minuteStep | Interval between minutes in picker | number | 1 | |
| needConfirm | Need click confirm button to trigger value change | boolean | - | 5.14.0 |
| open | Whether to popup panel | boolean | false | |
| placeholder | Display when there's no value | string \| \[string, string] | `Select a time` | |
| placement | The position where the selection box pops up | `bottomLeft` `bottomRight` `topLeft` `topRight` | bottomLeft | |
| popupClassName | The className of panel | string | - | |
| popupStyle | The style of panel | CSSProperties | - | |
| prefix | The custom prefix | ReactNode | - | 5.22.0 |
| renderExtraFooter | Called from time picker panel to render some addon to its bottom | () => ReactNode | - | |
| secondStep | Interval between seconds in picker | number | 1 | |
| showNow | Whether to show `Now` button on panel | boolean | - | 4.4.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' \| 'success' \| 'validating' | - | 4.19.0 |
| suffixIcon | The custom suffix icon | ReactNode | - | |
| use12Hours | Display as 12 hours format, with default format `h:mm:ss a` | boolean | false | |
| value | To set time | [dayjs](http://day.js.org/) | - | |
| variant | Variants of picker | `outlined` \| `borderless` \| `filled` | `outlined` | 5.13.0 |
| 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 | A callback function, can be executed when the selected time is changing | function(time: dayjs, timeString: string): void | - | |
| onOpenChange | A callback function which will be called while panel opening/closing | (open: boolean) => void | - | |
#### DisabledTime
```typescript
type DisabledTime = (now: Dayjs) => {
disabledHours?: () => number[];
disabledMinutes?: (selectedHour: number) => number[];
disabledSeconds?: (selectedHour: number, selectedMinute: number) => number[];
disabledMilliseconds?: (
selectedHour: number,
selectedMinute: number,
selectedSecond: number,
) => number[];
};
```
Note: `disabledMilliseconds` is added in `5.14.0`.
## Methods
| Name | Description | Version |
| ------- | ------------ | ------- |
| blur() | Remove focus | |
| focus() | Get focus | |
### RangePicker
Same props from [RangePicker](/components/date-picker/#rangepicker) of DatePicker. And includes additional props:
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| disabledTime | To specify the time that cannot be selected | [RangeDisabledTime](#rangedisabledtime) | - | 4.19.0 |
| order | Order start and end time | boolean | true | 4.1.0 |
### RangeDisabledTime
```typescript
type RangeDisabledTime = (
now: Dayjs,
type = 'start' | 'end',
) => {
disabledHours?: () => number[];
disabledMinutes?: (selectedHour: number) => number[];
disabledSeconds?: (selectedHour: number, selectedMinute: number) => number[];
};
```
## Design Token
<ComponentTokenTable component="DatePicker"></ComponentTokenTable>
## FAQ
- [How to use TimePicker with customize date library like dayjs](/docs/react/use-custom-date-library#timepicker)