TimePicker - Vant 4

TimePicker

Intro

Used to select time, usually used with the Popup component.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

import { createApp } from'vue'; import { TimePicker } from'vant'; const app = createApp(); app.use(TimePicker);

Usage

Basic Usage

import { ref } from'vue'; exportdefault { setup() { const currentTime = ref(['12', '00']); return { currentTime }; }, };

Columns Type

Using columns-type prop to control the type of columns.

For example:

• Pass in ['hour'] to select hour.
• Pass in ['minute'] to select minute.
• Pass in ['minute', 'second'] to select minute and second.
• Pass in ['hour', 'minute', 'second'] to select hour, minute and second.

import { ref } from'vue'; exportdefault { setup() { const currentTime = ref(['12', '00', '00']); const columnsType = ['hour', 'minute', 'second']; return { currentTime, columnsType, }; }, };

Time Range

You can use props like min-hour and max-hour to limit the range of hours, min-minute and max-minute to limit the range of minutes, and min-second and max-second to limit the range of seconds.

For example, in the following example, users can only select hours between 10 and 20, and minutes between 30 and 40.

import { ref } from'vue'; exportdefault { setup() { const currentTime = ref(['12', '35']); return { currentTime }; }, };

Overall Time Range

You can use min-time and max-time attributes to limit the overall time range, with the format 10:00:00.

• When min-time is set, attributes like min-hour, min-minute, and min-second will not take effect.
• When max-time is set, attributes like max-hour, max-minute, and max-second will not take effect.

For example, in the following example, users can select any time between 09:40:10 and 20:20:50.

import { ref } from'vue'; exportdefault { setup() { const currentTime = ref(['12', '00', '00']); return { currentTime }; }, };

Options Formatter

Using formatter prop to format option text.

import { ref } from'vue'; exportdefault { setup() { const currentTime = ref(['12', '00']); constformatter = (type, option) => { if (type === 'hour') { option.text += 'h'; } if (type === 'minute') { option.text += 'm'; } return option; }; return { formatter, currentTime, }; }, };

Options Filter

Using filter prop to filter options.

import { ref } from'vue'; exportdefault { setup() { const currentTime = ref(['12', '00']); constfilter = (type, options) => { if (type === 'minute') { return options.filter((option) =>Number(option.value) % 10 === 0); } return options; }; return { filter, currentTime, }; }, };

Advanced Usage

The third parameter of the filter function can get the currently selected time, which can be used to filter unwanted times more flexibly when using the uncontrolled mode.

exportdefault { setup() { constfilter = (type, options, values) => { const hour = +values[0]; if (type === 'hour') { return options.filter( (option) =>Number(option.value) >= 8 && Number(option.value) <= 18, ); } if (type === 'minute') { options = options.filter((option) =>Number(option.value) % 10 === 0); if (hour === 8) { return options.filter((option) =>Number(option.value) >= 40); } if (hour === 18) { return options.filter((option) =>Number(option.value) <= 20); } } return options; }; return { filter, }; }, };

API

Props

Attribute	Description	Type	Default
v-model	Current time	string[]	-
columns-type	Columns type	string[]	['hour', 'minute']
min-hour	Min hour	*number	string*
max-hour	Max hour	*number	string*
min-minute	Min minute	*number	string*
max-minute	Max minute	*number	string*
min-second	Min second	*number	string*
max-second	Max second	*number	string*
min-time v4.5.0	Min time, format reference 07:40:00, min-hour``min-minute``min-second is invalid when used	string	-
max-time v4.5.0	Max time, format reference 10:20:00, min-hour``min-minute``max-second is invalid when used	string	-
title	Toolbar title	string	''
confirm-button-text	Text of confirm button	string	Confirm
cancel-button-text	Text of cancel button	string	Cancel
show-toolbar	Whether to show toolbar	boolean	true
loading	Whether to show loading prompt	boolean	false
readonly	Whether to be readonly	boolean	false
filter	Option filter	(type: string, options: PickerOption[], values: string[]) => PickerOption[]	-
formatter	Option text formatter	(type: string, option: PickerOption) => PickerOption	-
option-height	Option height, supports px``vw``vh``rem unit, default px	*number	string*
visible-option-num	Count of visible columns	*number	string*
swipe-duration	Duration of the momentum animation, unit ms	*number	string*

Events

Event	Description	Arguments
confirm	Emitted when the confirm button is clicked	{ selectedValues, selectedOptions, selectedIndexes }
cancel	Emitted when the cancel button is clicked	{ selectedValues, selectedOptions, selectedIndexes }
change	Emitted when current option is changed	{ selectedValues, selectedOptions, selectedIndexes, columnIndex }

Slots

Name	Description	SlotProps
toolbar	Custom toolbar content	-
title	Custom title	-
confirm	Custom confirm button text	-
cancel	Custom cancel button text	-
option	Custom option content	option: PickerOption, index: number
columns-top	Custom content above columns	-
columns-bottom	Custom content below columns	-

Methods

Use ref to get Picker instance and call instance methods.

Name	Description	Attribute	Return value
confirm	Stop scrolling and emit confirm event	-	-
getSelectedTime	Get current selected time	-	string[]

Types

The component exports the following type definitions:

importtype { TimePickerProps, TimePickerColumnType, TimePickerInstance, } from'vant';

TimePickerInstance is the type of component instance:

import { ref } from'vue'; importtype { TimePickerInstance } from'vant'; const timePickerRef = ref<TimePickerInstance>(); timePickerRef.value?.confirm();