1# Text Picker Dialog Box (TextPickerDialog) 2 3A text picker dialog box is a dialog box that allows users to select text 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> 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 [showTextPickerDialog](../js-apis-arkui-UIContext.md#showtextpickerdialog) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext), which ensures that the text picker dialog box is shown in the intended UI instance. 12 13## TextPickerDialog 14 15### show 16 17static show(options?: TextPickerDialogOptions) 18 19Shows a text picker in the given settings. 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 | [TextPickerDialogOptions](#textpickerdialogoptions) | No | Parameters of the text picker dialog box.| 30 31## TextPickerDialogOptions 32 33Inherits from [TextPickerOptions](ts-basic-components-textpicker.md#textpickeroptions). 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37| Name| Type| Mandatory| Description| 38| -------- | -------- | -------- | -------- | 39| defaultPickerItemHeight | number \| string | No| Height of the picker item.<br>Default value: 56 vp (selected) and 36 vp (unselected). The set value applies to both selected and unselected items.<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 of 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| canLoop<sup>10+</sup> | boolean | No| Whether to support scroll looping. The value **true** means to support scroll looping, and **false** means the opposite.<br>Default value: **true**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 46| 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.| 47| 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.| 48| 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.| 49| onAccept | (value: [TextPickerResult](#textpickerresult)) => 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.| 50| 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.| 51| onChange | (value: [TextPickerResult](#textpickerresult)) => void | No| Callback invoked when the selected item changes.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 52| onScrollStop<sup>14+</sup> | (value: [TextPickerResult](#textpickerresult)) => void | No| Callback invoked when the scrolling in the text picker of the dialog box stops.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 53| 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.| 54| 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.| 55| 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.| 56| 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.| 57| 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.| 58| 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.| 59| 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.| 60| 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.| 61| 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.| 62 63## TextPickerResult 64 65**Atomic service API**: This API can be used in atomic services since API version 11. 66 67**System capability**: SystemCapability.ArkUI.ArkUI.Full 68 69| Name| Type| Read Only| Optional| Description| 70| -------- | -------- | -------- | -------- | -------- | 71| value | string \| string []<sup>10+</sup> | No| No| Text of the selected item.<br>**NOTE**<br>When the picker contains text only or both text and imagery, **value** indicates the text value of the selected item. (For a multi-column picker, **value** is of the array type.)<br>For an image list, **value** is empty.<br>The value cannot contain the following escape character: \\| 72| index | number \| number []<sup>10+</sup> | No| No| Index of the selected item in the range. (For a multi-column picker, **index** is of the array type.)| 73 74## Example 75 76> **NOTE** 77> 78> For clarity in UI execution context, you are advised to use the [showTextPickerDialog](../js-apis-arkui-UIContext.md#showtextpickerdialog) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext). 79 80### Example 1: Displaying a Text Picker Dialog Box 81 82This example demonstrates how to display a text picker dialog box when a button is touched. 83 84```ts 85// xxx.ets 86@Entry 87@Component 88struct TextPickerDialogExample { 89 private select: number | number[] = 0 90 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4', 'banana5'] 91 @State v:string = ''; 92 93 build() { 94 Row() { 95 Column() { 96 Button("TextPickerDialog:" + this.v) 97 .margin(20) 98 .onClick(() => { 99 TextPickerDialog.show({ // You are advised to use this.getUIContext().showTextPickerDialog(). 100 range: this.fruits, 101 selected: this.select, 102 disappearTextStyle: {color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}, 103 textStyle: {color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}, 104 selectedTextStyle: {color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}, 105 onAccept: (value: TextPickerResult) => { 106 // Set select to the index of the item selected when the OK button is touched. In this way, when the text picker dialog box is displayed again, the selected item is the one last confirmed. 107 this.select = value.index 108 console.log(this.select + '') 109 // After OK is clicked, the selected item is displayed on the page. 110 this.v = value.value as string 111 console.info("TextPickerDialog:onAccept()" + JSON.stringify(value)) 112 }, 113 onCancel: () => { 114 console.info("TextPickerDialog:onCancel()") 115 }, 116 onChange: (value: TextPickerResult) => { 117 console.info("TextPickerDialog:onChange()" + JSON.stringify(value)) 118 }, 119 onScrollStop: (value: TextPickerResult) => { 120 console.info("TextPickerDialog:onScrollStop()" + JSON.stringify(value)) 121 }, 122 onDidAppear: () => { 123 console.info("TextPickerDialog:onDidAppear()") 124 }, 125 onDidDisappear: () => { 126 console.info("TextPickerDialog:onDidDisappear()") 127 }, 128 onWillAppear: () => { 129 console.info("TextPickerDialog:onWillAppear()") 130 }, 131 onWillDisappear: () => { 132 console.info("TextPickerDialog:onWillDisappear()") 133 } 134 }) 135 }) 136 }.width('100%') 137 }.height('100%') 138 } 139} 140``` 141 142 143 144 145### Example 2: Customizing the Style 146 147In this example, **disappearTextStyle**, **textStyle**, **selectedTextStyle**, **acceptButtonStyle**, and **cancelButtonStyle** are configured to customize the text and button style. 148 149```ts 150// xxx.ets 151@Entry 152@Component 153struct TextPickerDialogExample { 154 private select: number | number[] = 0 155 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4', 'banana5'] 156 @State v:string = ''; 157 158 build() { 159 Row() { 160 Column() { 161 Button("TextPickerDialog:" + this.v) 162 .margin(20) 163 .onClick(() => { 164 TextPickerDialog.show({ // You are advised to use this.getUIContext().showTextPickerDialog(). 165 range: this.fruits, 166 selected: this.select, 167 disappearTextStyle: {color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}, 168 textStyle: {color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}, 169 selectedTextStyle: {color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}, 170 acceptButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Red, 171 fontSize: '26fp', fontWeight: FontWeight.Bolder, fontStyle: FontStyle.Normal, fontFamily: 'sans-serif', backgroundColor:'#80834511', 172 borderRadius: 20 }, 173 cancelButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Blue, 174 fontSize: '16fp', fontWeight: FontWeight.Normal, fontStyle: FontStyle.Italic, fontFamily: 'sans-serif', backgroundColor:'#50182431', 175 borderRadius: 10 }, 176 onAccept: (value: TextPickerResult) => { 177 // Set select to the index of the item selected when the OK button is touched. In this way, when the text picker dialog box is displayed again, the selected item is the one last confirmed. 178 this.select = value.index 179 console.log(this.select + '') 180 // After OK is clicked, the selected item is displayed on the page. 181 this.v = value.value as string 182 console.info("TextPickerDialog:onAccept()" + JSON.stringify(value)) 183 }, 184 onCancel: () => { 185 console.info("TextPickerDialog:onCancel()") 186 }, 187 onChange: (value: TextPickerResult) => { 188 console.info("TextPickerDialog:onChange()" + JSON.stringify(value)) 189 }, 190 onScrollStop: (value: TextPickerResult) => { 191 console.info("TextPickerDialog:onScrollStop()" + JSON.stringify(value)) 192 }, 193 onDidAppear: () => { 194 console.info("TextPickerDialog:onDidAppear()") 195 }, 196 onDidDisappear: () => { 197 console.info("TextPickerDialog:onDidDisappear()") 198 }, 199 onWillAppear: () => { 200 console.info("TextPickerDialog:onWillAppear()") 201 }, 202 onWillDisappear: () => { 203 console.info("TextPickerDialog:onWillDisappear()") 204 } 205 }) 206 }) 207 }.width('100%') 208 }.height('100%') 209 } 210} 211``` 212 213 214 215### Example 3: Configuring a Dialog Box in the Hover State 216 217This example demonstrates how to set the layout area of a dialog box in hover mode on a foldable device. 218 219```ts 220@Entry 221@Component 222struct TextPickerDialogExample { 223 private select: number | number[] = 0; 224 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4', 'banana5']; 225 @State v: string = ''; 226 227 build() { 228 Row() { 229 Column() { 230 Button("TextPickerDialog:" + this.v) 231 .margin(20) 232 .onClick(() => { 233 TextPickerDialog.show({ // You are advised to use this.getUIContext().showTextPickerDialog(). 234 range: this.fruits, 235 selected: this.select, 236 disappearTextStyle: { color: Color.Red, font: { size: 15, weight: FontWeight.Lighter }}, 237 textStyle: { color: Color.Black, font: { size: 20, weight: FontWeight.Normal }}, 238 selectedTextStyle: { color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder }}, 239 onAccept: (value: TextPickerResult) => { 240 // Set select to the index of the item selected when the OK button is touched. In this way, when the text picker dialog box is displayed again, the selected item is the one last confirmed. 241 this.select = value.index; 242 console.log(this.select + ''); 243 // After OK is clicked, the selected item is displayed on the page. 244 this.v = value.value as string; 245 console.info("TextPickerDialog:onAccept()" + JSON.stringify(value)); 246 }, 247 onCancel: () => { 248 console.info("TextPickerDialog:onCancel()"); 249 }, 250 onChange: (value: TextPickerResult) => { 251 console.info("TextPickerDialog:onChange()" + JSON.stringify(value)); 252 }, 253 onScrollStop: (value: TextPickerResult) => { 254 console.info("TextPickerDialog:onScrollStop()" + JSON.stringify(value)) 255 }, 256 onDidAppear: () => { 257 console.info("TextPickerDialog:onDidAppear()"); 258 }, 259 onDidDisappear: () => { 260 console.info("TextPickerDialog:onDidDisappear()"); 261 }, 262 onWillAppear: () => { 263 console.info("TextPickerDialog:onWillAppear()"); 264 }, 265 onWillDisappear: () => { 266 console.info("TextPickerDialog:onWillDisappear()"); 267 }, 268 enableHoverMode: true, 269 hoverModeArea: HoverModeAreaType.TOP_SCREEN 270 }) 271 }) 272 }.width('100%') 273 }.height('100%') 274 } 275} 276``` 277 278
