1# TimePicker
2
3The **TimePicker** component allows users to select a time (with the hour and minute) from the given range.
4
5>  **NOTE**
6>
7>  This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
8
9
10## Child Components
11
12Not supported
13
14
15## APIs
16
17TimePicker(options?: TimePickerOptions)
18
19Creates a time picker, which is in 24-hour format by default.
20
21**Atomic service API**: This API can be used in atomic services since API version 11.
22
23**System capability**: SystemCapability.ArkUI.ArkUI.Full
24
25**Parameters**
26
27| Name | Type                                           | Mandatory| Description                    |
28| ------- | ----------------------------------------------- | ---- | ------------------------ |
29| options | [TimePickerOptions](#timepickeroptions) | No  | Parameters of the time picker.|
30
31## TimePickerOptions
32
33**System capability**: SystemCapability.ArkUI.ArkUI.Full
34
35| Name                | Type                                           | Mandatory| Description                                                        |
36| -------------------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
37| selected             | Date                                            | No  | Time of the selected item.<br>Default value: current system time<br>Since API version 10, this parameter supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
38| format<sup>11+</sup> | [TimePickerFormat](#timepickerformat11)| No  | Time format.<br>Default value: **TimePickerFormat.HOUR_MINUTE**<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
39
40## TimePickerFormat<sup>11+</sup>
41
42**Atomic service API**: This API can be used in atomic services since API version 12.
43
44**System capability**: SystemCapability.ArkUI.ArkUI.Full
45
46| Name              | Description                    |
47| ------------------ | ------------------------ |
48| HOUR_MINUTE        | Display hours and minutes.      |
49| HOUR_MINUTE_SECOND | Display hours, minutes, and seconds.|
50
51## Attributes
52
53In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
54
55### useMilitaryTime
56
57useMilitaryTime(value: boolean)
58
59Sets whether to display time in 24-hour format. When the display time is in 12-hour format, the AM/PM zone does not change depending on the hour portion.
60
61**Atomic service API**: This API can be used in atomic services since API version 11.
62
63**System capability**: SystemCapability.ArkUI.ArkUI.Full
64
65**Parameters**
66
67| Name| Type   | Mandatory| Description                                      |
68| ------ | ------- | ---- | ------------------------------------------ |
69| value  | boolean | Yes  | Whether the display time is in 24-hour format.<br>Default value: **false**|
70
71### disappearTextStyle<sup>10+</sup>
72
73disappearTextStyle(value: PickerTextStyle)
74
75Sets the font color, font size, and font weight for the top and bottom items.
76
77**Atomic service API**: This API can be used in atomic services since API version 11.
78
79**System capability**: SystemCapability.ArkUI.ArkUI.Full
80
81**Parameters**
82
83| Name| Type                                                        | Mandatory| Description                                                        |
84| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
85| value  | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Yes  | Font color, font size, and font weight of the top and bottom items.<br>Default value:<br>{<br>color: '#ff182431',<br>font: {<br>size: '14fp', <br>weight: FontWeight.Regular<br>}<br>} |
86
87### textStyle<sup>10+</sup>
88
89textStyle(value: PickerTextStyle)
90
91Sets the font color, font size, and font weight for all items except the top, bottom, and selected items.
92
93**Atomic service API**: This API can be used in atomic services since API version 11.
94
95**System capability**: SystemCapability.ArkUI.ArkUI.Full
96
97**Parameters**
98
99| Name| Type                                                        | Mandatory| Description                                                        |
100| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
101| value  | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Yes  | Font color, font size, and font weight of all items except the top, bottom, and selected items.<br>Default value:<br>{<br>color: '#ff182431',<br>font: {<br>size: '16fp', <br>weight: FontWeight.Regular<br>}<br>} |
102
103### selectedTextStyle<sup>10+</sup>
104
105selectedTextStyle(value: PickerTextStyle)
106
107Sets the font color, font size, and font weight for the selected item.
108
109**Atomic service API**: This API can be used in atomic services since API version 11.
110
111**System capability**: SystemCapability.ArkUI.ArkUI.Full
112
113**Parameters**
114
115| Name| Type                                                        | Mandatory| Description                                                        |
116| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
117| value  | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Yes  | Font color, font size, and font weight of the selected item.<br>Default value:<br>{<br>color: '#ff007dff',<br>font: {<br>size: '20vp', <br>weight: FontWeight.Medium<br>}<br>} |
118
119### loop<sup>11+</sup>
120
121loop(value: boolean)
122
123Sets whether to enable the loop mode.
124
125**Atomic service API**: This API can be used in atomic services since API version 12.
126
127**System capability**: SystemCapability.ArkUI.ArkUI.Full
128
129**Parameters**
130
131| Name| Type   | Mandatory| Description                                                        |
132| ------ | ------- | ---- | ------------------------------------------------------------ |
133| value  | boolean | Yes  | Whether to enable the loop mode.<br>Default value: **true**<br>The value **true** means to enable  loop mode, and **false** means the opposite.|
134
135### dateTimeOptions<sup>12+</sup>
136
137dateTimeOptions(value: DateTimeOptions)
138
139Sets whether to display a leading zero for the hours, minutes, and seconds.
140
141**Atomic service API**: This API can be used in atomic services since API version 12.
142
143**System capability**: SystemCapability.ArkUI.ArkUI.Full
144
145**Parameters**
146
147| Name| Type                                                        | Mandatory| Description                                                        |
148| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
149| value  | [DateTimeOptions](../../apis-localization-kit/js-apis-intl.md#datetimeoptions) | Yes  | Whether to display a leading zero for the hours, minutes, and seconds. Currently only the configuration of the **hour**, **minute**, and **second** parameters is supported.<br>Default value:<br>**hour**: In the 24-hour format, it defaults to **2-digit**, which means a leading zero is used; In the 12-hour format, it defaults to **numeric**, which means no leading zero is used.<br>**minute**: defaults to **2-digit**, which means a leading zero is used.<br>**second**: defaults to **2-digit**, which means a leading zero is used.<br>|
150
151### enableHapticFeedback<sup>12+</sup>
152
153enableHapticFeedback(enable: boolean)
154
155**Atomic service API**: This API can be used in atomic services since API version 12.
156
157**System capability**: SystemCapability.ArkUI.ArkUI.Full
158
159| Name| Type                                         | Mandatory | Description                                                                                 |
160| ------ | --------------------------------------------- |-----|-------------------------------------------------------------------------------------|
161| enable  | boolean | Yes  | Whether haptic feedback is enabled.<br>**true** (default): Haptic feedback is enabled.<br>**false**: Haptic feedback is disabled.<br>Whether this parameter takes effect after being set to true depends on hardware support.|
162
163## Events
164
165In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
166
167### onChange
168
169onChange(callback: (value: TimePickerResult ) =&gt; void)
170
171Triggered when a time is selected.
172
173**Atomic service API**: This API can be used in atomic services since API version 11.
174
175**System capability**: SystemCapability.ArkUI.ArkUI.Full
176
177**Parameters**
178
179| Name| Type                                         | Mandatory| Description          |
180| ------ | --------------------------------------------- | ---- | -------------- |
181| value  | [TimePickerResult](#timepickerresult)| Yes  | Time in 24-hour format.|
182
183## TimePickerResult
184
185Describes a time in 24-hour format.
186
187**Atomic service API**: This API can be used in atomic services since API version 11.
188
189**System capability**: SystemCapability.ArkUI.ArkUI.Full
190
191| Name                | Type  | Read Only| Optional| Description                               |
192| -------------------- | ------ | ---- | ---- | ----------------------------------- |
193| hour                 | number | No  | No  | Hour portion of the selected time.<br>Value range: [0-23]|
194| minute               | number | No  | No  | Minute portion of the selected time.<br>Value range: [0-59]|
195| second<sup>11+</sup> | number | No  | No  | Second portion of the selected time.<br>Value range: [0-59]|
196
197## Example
198
199This example implements a time picker that allows users to switch between 12-hour and 24-hour formats by clicking a button.
200
201```ts
202// xxx.ets
203@Entry
204@Component
205struct TimePickerExample {
206  @State isMilitaryTime: boolean = false
207  private selectedTime: Date = new Date('2022-07-22T08:00:00')
208
209  build() {
210    Column() {
211      Button('Switch Time Format')
212        .margin(30)
213        .onClick(() => {
214          this.isMilitaryTime = !this.isMilitaryTime
215        })
216      TimePicker({
217        selected: this.selectedTime,
218      })
219        .useMilitaryTime(this.isMilitaryTime)
220        .onChange((value: TimePickerResult) => {
221          if(value.hour >= 0) {
222            this.selectedTime.setHours(value.hour, value.minute)
223            console.info('select current date is: ' + JSON.stringify(value))
224          }
225        })
226        .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}})
227        .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}})
228        .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}})
229    }.width('100%')
230  }
231}
232```
233
234![timePicker](figures/timePicker.gif)
235