mirror of
https://github.com/element-plus/element-plus.git
synced 2026-03-13 07:51:17 +08:00
0e8b017874
* fix(components): [date-picker] allow array model value type Co-authored-by: DDDDD12138 <43703884+DDDDD12138@users.noreply.github.com> * chore: rebase * chore: docs tweak Co-authored-by: qiang <qw13131wang@gmail.com> --------- Co-authored-by: DDDDD12138 <43703884+DDDDD12138@users.noreply.github.com> Co-authored-by: qiang <qw13131wang@gmail.com>
180 lines
16 KiB
Markdown
180 lines
16 KiB
Markdown
---
|
|
title: DateTimePicker
|
|
lang: en-US
|
|
---
|
|
|
|
# DateTimePicker
|
|
|
|
Select date and time in one picker.
|
|
|
|
:::tip
|
|
|
|
DateTimePicker is derived from DatePicker and TimePicker. For a more detailed explanation on attributes, you can refer to DatePicker and TimePicker.
|
|
|
|
:::
|
|
|
|
## Date and time
|
|
|
|
:::demo You can select date and time in one picker at the same time by setting `type` to `datetime`. The way to use shortcuts is the same as Date Picker.
|
|
|
|
datetime-picker/date-and-time
|
|
|
|
:::
|
|
|
|
## DateTime Formats
|
|
|
|
Use `format` to control displayed text's format in the input box. Use `value-format` to control binding value's format.
|
|
|
|
By default, the component accepts and emits a `Date` object.
|
|
|
|
Check the list [here](https://day.js.org/docs/en/display/format#list-of-all-available-formats) of all available formats of Day.js.
|
|
|
|
:::warning
|
|
|
|
Pay attention to capitalization
|
|
|
|
:::
|
|
|
|
:::demo
|
|
|
|
datetime-picker/date-and-time-formats
|
|
|
|
:::
|
|
|
|
## Date and time formats in dropdown panel
|
|
|
|
Use `date-format` and `time-format` to control displayed text's format in the dropdown panel's input box.
|
|
|
|
:::demo
|
|
|
|
datetime-picker/date-and-time-formats-panel
|
|
|
|
:::
|
|
|
|
## Date and time range
|
|
|
|
:::demo You can select date and time range by setting `type` to `datetimerange`.
|
|
|
|
datetime-picker/date-and-time-range
|
|
|
|
:::
|
|
|
|
## Default time value for start date and end date
|
|
|
|
:::demo When picking date range on the date panel with type `datetimerange`, `00:00:00` will be used as the default time value for start and end date. We can control it with the `default-time` attribute. `default-time` accepts an array of up to two Date objects. The first item controls time value of the start date and the second item controls time value of the end date.
|
|
|
|
datetime-picker/default-time
|
|
|
|
:::
|
|
|
|
## Custom icon ^(2.8.0)
|
|
|
|
Custom icons available with slots.
|
|
|
|
:::demo
|
|
|
|
datetime-picker/custom-icon
|
|
|
|
:::
|
|
|
|
## API
|
|
|
|
### Attributes
|
|
|
|
| Name | Description | Type | Default |
|
|
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------- |
|
|
| model-value / v-model | binding value, if it is an `range` picker, the length of the array should be 2 | ^[number] / ^[string] / ^[Date] / ^[array]`number[] \| string[] \| Date[]` | '' |
|
|
| readonly | whether DatePicker is read only | ^[boolean] | false |
|
|
| disabled | whether DatePicker is disabled | ^[boolean] | false |
|
|
| editable | whether the input is editable | ^[boolean] | true |
|
|
| clearable | whether to show clear button | ^[boolean] | true |
|
|
| size | size of Input | ^[enum]`'large' \| 'default' \| 'small'` | default |
|
|
| placeholder | placeholder in non-range mode | ^[string] | — |
|
|
| start-placeholder | placeholder for the start date in range mode | ^[string] | — |
|
|
| end-placeholder | placeholder for the end date in range mode | ^[string] | — |
|
|
| arrow-control | whether to pick time using arrow buttons | ^[boolean] | false |
|
|
| type | type of the picker | ^[enum]`'year' \| 'month' \| 'date' \| 'datetime' \| 'week' \| 'datetimerange' \| 'daterange'` | date |
|
|
| format | format of the displayed value in the input box | ^[string] see [date formats](/en-US/component/date-picker#date-formats) | YYYY-MM-DD HH:mm:ss |
|
|
| popper-class | custom class name for DateTimePicker's dropdown | ^[string] | — |
|
|
| popper-style | custom style for DateTimePicker's dropdown | ^[string] / ^[object] | — |
|
|
| popper-options | Customized popper option see more at [popper.js](https://popper.js.org/docs/v2/) | ^[object]`Partial<PopperOptions>` | {} |
|
|
| fallback-placements ^(2.8.4) | list of possible positions for Tooltip [popper.js](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | ^[array]`Placement[]` | ['bottom', 'top', 'right', 'left'] |
|
|
| placement ^(2.8.4) | position of dropdown | `Placement` | bottom |
|
|
| range-separator | range separator | ^[string] | '-' |
|
|
| default-value | optional, default date of the calendar | ^[object]`Date \| [Date, Date]` | — |
|
|
| default-time | the default time value after picking a date. Time `00:00:00` will be used if not specified | ^[object]`Date \| [Date, Date]` | — |
|
|
| value-format | optional, format of binding value. If not specified, the binding value will be a Date object | ^[string] see [date formats](https://day.js.org/docs/en/display/format) | — |
|
|
| date-format ^(2.4.0) | optional, format of the date displayed in input's inner panel | ^[string] see [date formats](https://day.js.org/docs/en/display/format) | YYYY-MM-DD |
|
|
| time-format ^(2.4.0) | optional, format of the time displayed in input's inner panel | ^[string] see [date formats](https://day.js.org/docs/en/display/format) | HH:mm:ss |
|
|
| id | same as `id` in native input | ^[string] / ^[object]`[string, string]` | — |
|
|
| name | same as `name` in native input | ^[string] | — |
|
|
| unlink-panels | unlink two date-panels in range-picker | ^[boolean] | false |
|
|
| prefix-icon | Custom prefix icon component | ^[string] / `Component` | Date |
|
|
| clear-icon | Custom clear icon component | ^[string] / `Component` | CircleClose |
|
|
| shortcuts | an object array to set shortcut options | ^[object]`Array<{ text: string, value: Date \| Function }>` | — |
|
|
| disabled-date | a function determining if a date is disabled with that date as its parameter. Should return a Boolean | ^[Function]`(data: Date) => boolean` | — |
|
|
| disabled-hours | To specify the array of hours that cannot be selected | ^[Function]`(role: string, comparingDate?: Dayjs) => number[]` | — |
|
|
| disabled-minutes | To specify the array of minutes that cannot be selected | ^[Function]`(hour: number, role: string, comparingDate?: Dayjs) => number[]` | — |
|
|
| disabled-seconds | To specify the array of seconds that cannot be selected | ^[Function]`(hour: number, minute: number, role: string, comparingDate?: Dayjs) => number[]` | — |
|
|
| cell-class-name | set custom className | ^[Function]`(data: Date) => string` | — |
|
|
| teleported | whether datetime-picker dropdown is teleported to the body | ^[boolean] | true |
|
|
| empty-values ^(2.7.0) | empty values of component, [see config-provider](/en-US/component/config-provider#empty-values-configurations) | ^[array] | — |
|
|
| value-on-clear ^(2.7.0) | clear return value, [see config-provider](/en-US/component/config-provider#empty-values-configurations) | ^[string] / ^[number] / ^[boolean] / ^[Function] | — |
|
|
| show-now ^(2.8.7) | whether to show the now button | ^[boolean] | true |
|
|
| show-footer ^(2.10.5) | whether to show footer where the date picker is one ^[enum]`'datetime' \| 'datetimerange'` | ^[boolean] | true |
|
|
| show-confirm ^(2.11.0) | whether to show the confirm button | ^[boolean] | true |
|
|
| show-week-number ^(2.10.3) | show the week number besides the week | `boolean` | false |
|
|
|
|
### Events
|
|
|
|
| Name | Description | Parameters |
|
|
| --------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
| change | triggers when user confirms the value or click outside | ^[Function]`(val: typeof v-model) => void` |
|
|
| blur | triggers when Input blurs | ^[Function]`(e: FocusEvent) => void` |
|
|
| focus | triggers when Input focuses | ^[Function]`(e: FocusEvent) => void` |
|
|
| clear ^(2.7.7) | triggers when the clear icon is clicked in a clearable DateTimePicker | ^[Function]`() => void` |
|
|
| calendar-change | triggers when the calendar selected date is changed. Only for `range` | ^[Function]`(val: [Date, null \| Date]) => void` |
|
|
| panel-change | triggers when the navigation button click. | ^[Function]`(date: Date \| [Date, Date], mode: 'month' \| 'year', view?: string) => void` |
|
|
| visible-change | triggers when the DateTimePicker's dropdown appears/disappears | ^[Function]`(visibility: boolean) => void` |
|
|
|
|
### Slots
|
|
|
|
| Name | Description |
|
|
| ------------------- | ------------------------------ |
|
|
| default | custom cell content |
|
|
| range-separator | custom range separator content |
|
|
| prev-month ^(2.8.0) | prev month icon |
|
|
| next-month ^(2.8.0) | next month icon |
|
|
| prev-year ^(2.8.0) | prev year icon |
|
|
| next-year ^(2.8.0) | next year icon |
|
|
|
|
### Exposes
|
|
|
|
| Method | Description | Type |
|
|
| ------------- | ------------------------------ | ----------------------- |
|
|
| focus | focus the DatePicker component | ^[Function]`() => void` |
|
|
| blur ^(2.8.7) | blur the DatePicker component | ^[Function]`() => void` |
|
|
|
|
## Type Declarations
|
|
|
|
<details>
|
|
<summary>Show declarations</summary>
|
|
|
|
```ts
|
|
type Placement =
|
|
| 'top'
|
|
| 'top-start'
|
|
| 'top-end'
|
|
| 'bottom'
|
|
| 'bottom-start'
|
|
| 'bottom-end'
|
|
| 'left'
|
|
| 'left-start'
|
|
| 'left-end'
|
|
| 'right'
|
|
| 'right-start'
|
|
| 'right-end'
|
|
```
|
|
|
|
</details>
|