1# Time Picker Dialog Box (TimePickerDialog)
2
3A time picker dialog box is a dialog box that allows users to select a time from the 24-hour range through scrolling.
4
5>  **NOTE**
6>
7> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
8>
9> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](../js-apis-arkui-UIContext.md#uicontext).
10>
11> Since API version 10, you can use the [showTimePickerDialog](../js-apis-arkui-UIContext.md#showtimepickerdialog) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext), which ensures that the time picker dialog box is shown in the intended UI instance.
12
13## TimePickerDialog
14
15### show
16
17static show(options?: TimePickerDialogOptions)
18
19Shows a time picker dialog box.
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 | [TimePickerDialogOptions](#timepickerdialogoptions) | No  | Parameters of the time picker dialog box.|
30
31## TimePickerDialogOptions
32
33Inherited from [TimePickerOptions](ts-basic-components-timepicker.md#timepickeroptions).
34
35**System capability**: SystemCapability.ArkUI.ArkUI.Full
36
37| Name| Type| Mandatory| Description|
38| -------- | -------- | -------- | -------- |
39| useMilitaryTime | boolean | No| Whether to display time in 24-hour format. The 12-hour format is used by default.<br>Default value: **false**<br>**NOTE**<br>When in the 12-hour format, the AM/PM zone does not change depending on the hour portion.<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
40| disappearTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font weight for the top and bottom items.<br>Default value:<br>{<br>color: '#ff182431',<br>font: {<br>size: '14fp', <br>weight: FontWeight.Regular<br>}<br>}<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
41| textStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| 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>}<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
42| selectedTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| 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>}<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
43| acceptButtonStyle<sup>12+</sup> | [PickerDialogButtonStyle](ts-methods-datepicker-dialog.md#pickerdialogbuttonstyle12) | No| Style of the accept button.<br>**NOTE**<br>In the **acceptButtonStyle** and **cancelButtonStyle** configurations, only one **primary** field can be set to **true** at most. If both the **primary** fields are set to **true**, neither will take effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
44| cancelButtonStyle<sup>12+</sup> | [PickerDialogButtonStyle](ts-methods-datepicker-dialog.md#pickerdialogbuttonstyle12) | No| Style of the cancel button.<br>**NOTE**<br>In the **acceptButtonStyle** and **cancelButtonStyle** configurations, only one **primary** field can be set to **true** at most. If both the **primary** fields are set to **true**, neither will take effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
45| alignment<sup>10+</sup>  | [DialogAlignment](ts-methods-alert-dialog-box.md#dialogalignment) | No  | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Default**<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
46| offset<sup>10+</sup>     | [Offset](ts-types.md#offset) | No    | Offset of the dialog box based on the **alignment** settings.<br>Default value: **{ dx: 0 , dy: 0 }**<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
47| maskRect<sup>10+</sup>| [Rectangle](ts-methods-alert-dialog-box.md#rectangle8) | No    | Mask area of the dialog box. Events outside the mask area are transparently transmitted, and events within the mask area are not.<br>Default value: **{ x: 0, y: 0, width: '100%', height: '100%' }**<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
48| onAccept | (value: [TimePickerResult](ts-basic-components-timepicker.md#TimePickerResult)) => void | No| Callback invoked when the OK button in the dialog box is clicked.<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
49| onCancel | () => void | No| Callback invoked when the Cancel button in the dialog box is clicked.<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
50| onChange | (value: [TimePickerResult](ts-basic-components-timepicker.md#TimePickerResult)) => void | No| Callback invoked when the selected time changes.<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
51| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor)  | No| Backplane color of the dialog box.<br>Default value: **Color.Transparent**<br>**NOTE**<br>When **backgroundColor** is set to a non-transparent color, **backgroundBlurStyle** must be set to **BlurStyle.NONE**; otherwise, the color display may not meet the expected effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
52| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| Background blur style of the dialog box.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**NOTE**<br>Setting this parameter to **BlurStyle.NONE** disables the background blur. When **backgroundBlurStyle** is set to a value other than **NONE**, do not set **backgroundColor**. If you do, the color display may not produce the expected visual effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
53| onDidAppear<sup>12+</sup> | () => void | No| Event callback when the dialog box appears.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onAccept/onCancel/onChange) > onWillDisappear > onDidDisappear.<br>2. You can set the callback event for changing the dialog box display effect in **onDidAppear**. The settings take effect next time the dialog box appears.<br>3. If the user closes the dialog box immediately after it appears, **onWillDisappear** is invoked before **onDidAppear**.<br>4. If the dialog box is closed before its entrance animation is finished, this callback is not invoked.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
54| onDidDisappear<sup>12+</sup> | () => void | No| Event callback when the dialog box disappears.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onAccept/onCancel/onChange) > onWillDisappear > onDidDisappear.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
55| onWillAppear<sup>12+</sup> | () => void | No| Event callback when the dialog box is about to appear.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onAccept/onCancel/onChange) > onWillDisappear > onDidDisappear.<br>2. You can set the callback event for changing the dialog box display effect in **onWillAppear**. The settings take effect next time the dialog box appears.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
56| onWillDisappear<sup>12+</sup> | () => void | No| Event callback when the dialog box is about to disappear.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onAccept/onCancel/onChange) > onWillDisappear > onDidDisappear.<br>2. If the user closes the dialog box immediately after it appears, **onWillDisappear** is invoked before **onDidAppear**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
57| shadow<sup>12+</sup>              | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) | No  | Shadow of the dialog box.<br>Default value on 2-in-1 devices: **ShadowStyle.OUTER_FLOATING_MD** when the dialog box is focused and **ShadowStyle.OUTER_FLOATING_SM** otherwise<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
58| dateTimeOptions<sup>12+</sup> | [DateTimeOptions](../../apis-localization-kit/js-apis-intl.md#datetimeoptions) | No| Whether to display a leading zero for the hours and minutes. Currently only the configuration of the **hour** and **minute** 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>**Atomic service API**: This API can be used in atomic services since API version 12.|
59| enableHoverMode<sup>14+</sup>     | boolean | No  | Whether to enable the hover mode.<br>Default value: **false**, meaning not to enable the hover mode.<br>**Atomic service API**: This API can be used in atomic services since API version 14.|
60| hoverModeArea<sup>14+</sup>       | [HoverModeAreaType](ts-appendix-enums.md#hovermodeareatype14) | No  | Display area of the dialog box in hover mode.<br>Default value: **HoverModeAreaType.BOTTOM_SCREEN**<br>**Atomic service API**: This API can be used in atomic services since API version 14.|
61
62## Example
63
64>  **NOTE**
65>
66> For clarity in UI execution context, you are advised to use the [showTimePickerDialog](../js-apis-arkui-UIContext.md#showtimepickerdialog) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext).
67
68### Example 1: Displaying a Time Picker Dialog Box
69
70This example demonstrates how to display a time picker dialog box when a button is touched.
71
72```ts
73// xxx.ets
74@Entry
75@Component
76struct TimePickerDialogExample {
77  private selectTime: Date = new Date('2020-12-25T08:30:00')
78
79  build() {
80    Column() {
81      Button("TimePickerDialog 12-hour format")
82        .margin(20)
83        .onClick(() => {
84          TimePickerDialog.show ({ // You are advised to use this.getUIContext().showTimePickerDialog() API.
85            selected: this.selectTime,
86            disappearTextStyle: { color: Color.Red, font: { size: 15, weight: FontWeight.Lighter } },
87            textStyle: { color: Color.Black, font: { size: 20, weight: FontWeight.Normal } },
88            selectedTextStyle: { color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } },
89            onAccept: (value: TimePickerResult) => {
90              // Set selectTime to the time when the OK button is clicked. In this way, when the dialog box is displayed again, the selected time is the time when the operation was confirmed last time.
91              if (value.hour != undefined && value.minute != undefined) {
92                this.selectTime.setHours(value.hour, value.minute)
93                console.info("TimePickerDialog:onAccept()" + JSON.stringify(value))
94              }
95            },
96            onCancel: () => {
97              console.info("TimePickerDialog:onCancel()")
98            },
99            onChange: (value: TimePickerResult) => {
100              console.info("TimePickerDialog:onChange()" + JSON.stringify(value))
101            },
102            onDidAppear: () => {
103              console.info("TimePickerDialog:onDidAppear()")
104            },
105            onDidDisappear: () => {
106              console.info("TimePickerDialog:onDidDisappear()")
107            },
108            onWillAppear: () => {
109              console.info("TimePickerDialog:onWillAppear()")
110            },
111            onWillDisappear: () => {
112              console.info("TimePickerDialog:onWillDisappear()")
113            }
114          })
115        })
116      Button("TimePickerDialog 24-hour format")
117        .margin(20)
118        .onClick(() => {
119          TimePickerDialog.show({
120            selected: this.selectTime,
121            useMilitaryTime: true,
122            disappearTextStyle: { color: Color.Red, font: { size: 15, weight: FontWeight.Lighter } },
123            textStyle: { color: Color.Black, font: { size: 20, weight: FontWeight.Normal } },
124            selectedTextStyle: { color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } },
125            onAccept: (value: TimePickerResult) => {
126              if (value.hour != undefined && value.minute != undefined) {
127                this.selectTime.setHours(value.hour, value.minute)
128                console.info("TimePickerDialog:onAccept()" + JSON.stringify(value))
129              }
130            },
131            onCancel: () => {
132              console.info("TimePickerDialog:onCancel()")
133            },
134            onChange: (value: TimePickerResult) => {
135              console.info("TimePickerDialog:onChange()" + JSON.stringify(value))
136            },
137            onDidAppear: () => {
138              console.info("TimePickerDialog:onDidAppear()")
139            },
140            onDidDisappear: () => {
141              console.info("TimePickerDialog:onDidDisappear()")
142            },
143            onWillAppear: () => {
144              console.info("TimePickerDialog:onWillAppear()")
145            },
146            onWillDisappear: () => {
147              console.info("TimePickerDialog:onWillDisappear()")
148            }
149          })
150        })
151    }.width('100%')
152  }
153}
154```
155
156![TimetPickerDialog](figures/TimePickerDialog.gif)
157
158
159### Example 2: Customizing the Style
160
161In this example, **disappearTextStyle**, **textStyle**, **selectedTextStyle**, **acceptButtonStyle**, and **cancelButtonStyle** are configured to customize the text and button style.
162
163```ts
164// xxx.ets
165@Entry
166@Component
167struct TimePickerDialogExample {
168  private selectTime: Date = new Date('2020-12-25T08:30:00')
169
170  build() {
171    Column() {
172      Button("TimePickerDialog 24-hour format")
173        .margin(20)
174        .onClick(() => {
175          TimePickerDialog.show({
176            selected: this.selectTime,
177            useMilitaryTime: true,
178            disappearTextStyle: { color: Color.Red, font: { size: 15, weight: FontWeight.Lighter } },
179            textStyle: { color: Color.Black, font: { size: 20, weight: FontWeight.Normal } },
180            selectedTextStyle: { color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } },
181            acceptButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Red,
182              fontSize: '26fp', fontWeight: FontWeight.Bolder, fontStyle: FontStyle.Normal, fontFamily: 'sans-serif', backgroundColor:'#80834511',
183              borderRadius: 20 },
184            cancelButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Blue,
185              fontSize: '16fp', fontWeight: FontWeight.Normal, fontStyle: FontStyle.Italic, fontFamily: 'sans-serif', backgroundColor:'#50182431',
186              borderRadius: 10 },
187            onAccept: (value: TimePickerResult) => {
188              if (value.hour != undefined && value.minute != undefined) {
189                this.selectTime.setHours(value.hour, value.minute)
190                console.info("TimePickerDialog:onAccept()" + JSON.stringify(value))
191              }
192            },
193            onCancel: () => {
194              console.info("TimePickerDialog:onCancel()")
195            },
196            onChange: (value: TimePickerResult) => {
197              console.info("TimePickerDialog:onChange()" + JSON.stringify(value))
198            },
199            onDidAppear: () => {
200              console.info("TimePickerDialog:onDidAppear()")
201            },
202            onDidDisappear: () => {
203              console.info("TimePickerDialog:onDidDisappear()")
204            },
205            onWillAppear: () => {
206              console.info("TimePickerDialog:onWillAppear()")
207            },
208            onWillDisappear: () => {
209              console.info("TimePickerDialog:onWillDisappear()")
210            }
211          })
212        })
213    }.width('100%')
214  }
215}
216```
217
218![TimetPickerDialog](figures/TimePickerDialog_CustomButton.png)
219
220### Example 3: Configuring a Dialog Box in the Hover State
221
222This example demonstrates how to set the layout area of a dialog box in hover mode on a foldable device.
223
224```ts
225@Entry
226@Component
227struct TimePickerDialogExample {
228  private selectTime: Date = new Date('2020-12-25T08:30:00');
229
230  build() {
231    Column() {
232      Button("TimePickerDialog 12-hour format")
233        .margin(20)
234        .onClick(() => {
235          TimePickerDialog.show ({ // You are advised to use this.getUIContext().showTimePickerDialog().
236            selected: this.selectTime,
237            disappearTextStyle: { color: Color.Red, font: { size: 15, weight: FontWeight.Lighter } },
238            textStyle: { color: Color.Black, font: { size: 20, weight: FontWeight.Normal } },
239            selectedTextStyle: { color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } },
240            onAccept: (value: TimePickerResult) => {
241              // Set selectTime to the time when the OK button is clicked. In this way, when the dialog box is displayed again, the selected time is the time when the operation was confirmed last time.
242              if (value.hour != undefined && value.minute != undefined) {
243                this.selectTime.setHours(value.hour, value.minute);
244                console.info("TimePickerDialog:onAccept()" + JSON.stringify(value));
245              }
246            },
247            onCancel: () => {
248              console.info("TimePickerDialog:onCancel()");
249            },
250            onChange: (value: TimePickerResult) => {
251              console.info("TimePickerDialog:onChange()" + JSON.stringify(value));
252            },
253            onDidAppear: () => {
254              console.info("TimePickerDialog:onDidAppear()");
255            },
256            onDidDisappear: () => {
257              console.info("TimePickerDialog:onDidDisappear()");
258            },
259            onWillAppear: () => {
260              console.info("TimePickerDialog:onWillAppear()");
261            },
262            onWillDisappear: () => {
263              console.info("TimePickerDialog:onWillDisappear()");
264            },
265            enableHoverMode: true,
266            hoverModeArea: HoverModeAreaType.TOP_SCREEN
267          })
268        })
269    }.width('100%')
270  }
271}
272```
273
274![TimetPickerDialog](figures/TimePickerDialog_HoverMode.gif)
275
276