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) to obtain the UI context. 12 13## TimePickerDialog.show 14 15static show(options?: TimePickerDialogOptions) 16 17Shows a time picker dialog box. 18 19**Atomic service API**: This API can be used in atomic services since API version 11. 20 21**System capability**: SystemCapability.ArkUI.ArkUI.Full 22 23**Parameters** 24 25| Name | Type | Mandatory| Description | 26| ------- | ----------------------------------------------------------- | ---- | -------------------------- | 27| options | [TimePickerDialogOptions](#timepickerdialogoptions) | No | Parameters of the time picker dialog box.| 28 29## TimePickerDialogOptions 30 31Inherited from [TimePickerOptions](ts-basic-components-timepicker.md#timepickeroptions). 32 33**System capability**: SystemCapability.ArkUI.ArkUI.Full 34 35| Name| Type| Mandatory| Description| 36| -------- | -------- | -------- | -------- | 37| 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.| 38| 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.| 39| 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.| 40| 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.| 41| 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.| 42| 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.| 43| 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.| 44| 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.| 45| 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.| 46| 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.| 47| 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.| 48| 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.| 49| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Backplane color of the dialog box.<br>Default value: **Color.Transparent**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 50| 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>**Atomic service API**: This API can be used in atomic services since API version 12.| 51| 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.| 52| 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.| 53| 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.| 54| 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.| 55| 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.| 56| 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.| 57 58## Example 59 60### Example 1 61 62This example shows the basic usage of **TimePickerDialog**. 63 64```ts 65// xxx.ets 66@Entry 67@Component 68struct TimePickerDialogExample { 69 private selectTime: Date = new Date('2020-12-25T08:30:00') 70 71 build() { 72 Column() { 73 Button ("TimePickerDialog 12-hour format") 74 .margin(20) 75 .onClick(() => { 76 TimePickerDialog.show({ 77 selected: this.selectTime, 78 disappearTextStyle: { color: Color.Red, font: { size: 15, weight: FontWeight.Lighter } }, 79 textStyle: { color: Color.Black, font: { size: 20, weight: FontWeight.Normal } }, 80 selectedTextStyle: { color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } }, 81 onAccept: (value: TimePickerResult) => { 82 // 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. 83 if (value.hour != undefined && value.minute != undefined) { 84 this.selectTime.setHours(value.hour, value.minute) 85 console.info("TimePickerDialog:onAccept()" + JSON.stringify(value)) 86 } 87 }, 88 onCancel: () => { 89 console.info("TimePickerDialog:onCancel()") 90 }, 91 onChange: (value: TimePickerResult) => { 92 console.info("TimePickerDialog:onChange()" + JSON.stringify(value)) 93 }, 94 onDidAppear: () => { 95 console.info("TimePickerDialog:onDidAppear()") 96 }, 97 onDidDisappear: () => { 98 console.info("TimePickerDialog:onDidDisappear()") 99 }, 100 onWillAppear: () => { 101 console.info("TimePickerDialog:onWillAppear()") 102 }, 103 onWillDisappear: () => { 104 console.info("TimePickerDialog:onWillDisappear()") 105 } 106 }) 107 }) 108 Button ("TimePickerDialog 24-hour format") 109 .margin(20) 110 .onClick(() => { 111 TimePickerDialog.show({ 112 selected: this.selectTime, 113 useMilitaryTime: true, 114 disappearTextStyle: { color: Color.Red, font: { size: 15, weight: FontWeight.Lighter } }, 115 textStyle: { color: Color.Black, font: { size: 20, weight: FontWeight.Normal } }, 116 selectedTextStyle: { color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } }, 117 onAccept: (value: TimePickerResult) => { 118 if (value.hour != undefined && value.minute != undefined) { 119 this.selectTime.setHours(value.hour, value.minute) 120 console.info("TimePickerDialog:onAccept()" + JSON.stringify(value)) 121 } 122 }, 123 onCancel: () => { 124 console.info("TimePickerDialog:onCancel()") 125 }, 126 onChange: (value: TimePickerResult) => { 127 console.info("TimePickerDialog:onChange()" + JSON.stringify(value)) 128 }, 129 onDidAppear: () => { 130 console.info("TimePickerDialog:onDidAppear()") 131 }, 132 onDidDisappear: () => { 133 console.info("TimePickerDialog:onDidDisappear()") 134 }, 135 onWillAppear: () => { 136 console.info("TimePickerDialog:onWillAppear()") 137 }, 138 onWillDisappear: () => { 139 console.info("TimePickerDialog:onWillDisappear()") 140 } 141 }) 142 }) 143 }.width('100%') 144 } 145} 146``` 147 148 149 150 151### Example 2 152 153This example shows how to customize the button style. 154 155```ts 156// xxx.ets 157@Entry 158@Component 159struct TimePickerDialogExample { 160 private selectTime: Date = new Date('2020-12-25T08:30:00') 161 162 build() { 163 Column() { 164 Button ("TimePickerDialog 24-hour format") 165 .margin(20) 166 .onClick(() => { 167 TimePickerDialog.show({ 168 selected: this.selectTime, 169 useMilitaryTime: true, 170 disappearTextStyle: { color: Color.Red, font: { size: 15, weight: FontWeight.Lighter } }, 171 textStyle: { color: Color.Black, font: { size: 20, weight: FontWeight.Normal } }, 172 selectedTextStyle: { color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } }, 173 acceptButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Red, 174 fontSize: '26fp', fontWeight: FontWeight.Bolder, fontStyle: FontStyle.Normal, fontFamily: 'sans-serif', backgroundColor:'#80834511', 175 borderRadius: 20 }, 176 cancelButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Blue, 177 fontSize: '16fp', fontWeight: FontWeight.Normal, fontStyle: FontStyle.Italic, fontFamily: 'sans-serif', backgroundColor:'#50182431', 178 borderRadius: 10 }, 179 onAccept: (value: TimePickerResult) => { 180 if (value.hour != undefined && value.minute != undefined) { 181 this.selectTime.setHours(value.hour, value.minute) 182 console.info("TimePickerDialog:onAccept()" + JSON.stringify(value)) 183 } 184 }, 185 onCancel: () => { 186 console.info("TimePickerDialog:onCancel()") 187 }, 188 onChange: (value: TimePickerResult) => { 189 console.info("TimePickerDialog:onChange()" + JSON.stringify(value)) 190 }, 191 onDidAppear: () => { 192 console.info("TimePickerDialog:onDidAppear()") 193 }, 194 onDidDisappear: () => { 195 console.info("TimePickerDialog:onDidDisappear()") 196 }, 197 onWillAppear: () => { 198 console.info("TimePickerDialog:onWillAppear()") 199 }, 200 onWillDisappear: () => { 201 console.info("TimePickerDialog:onWillDisappear()") 202 } 203 }) 204 }) 205 }.width('100%') 206 } 207} 208``` 209 210 211
