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/onScrollStop) > 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/onScrollStop) > 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/onScrollStop) > 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/onScrollStop) > 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| disableTextStyleAnimation<sup>15+</sup> | boolean | No | Sets whether to enable the text style change animation during the scrolling process.<br>**true**: Disable the text style change animation.<br>**false**: Enable the text style change animation.<br>Default value: **false**| 63| defaultTextStyle<sup>15+</sup> | [TextPickerTextStyle](ts-basic-components-textpicker.md#textpickertextstyle15) | No | Style of the text items when the text style change animation during the scrolling process is disabled. It is effective only when **disableTextStyleAnimation** is **true**.<br>Default value: same as the default value of the [Text](ts-basic-components-text.md) component| 64 65## TextPickerResult 66 67**Atomic service API**: This API can be used in atomic services since API version 11. 68 69**System capability**: SystemCapability.ArkUI.ArkUI.Full 70 71| Name| Type| Read Only| Optional| Description| 72| -------- | -------- | -------- | -------- | -------- | 73| 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: \\| 74| 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.)| 75 76## Example 77 78> **NOTE** 79> 80> 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). 81 82### Example 1: Displaying a Text Picker Dialog Box 83 84This example demonstrates how to display a text picker dialog box when a button is touched. 85 86```ts 87// xxx.ets 88@Entry 89@Component 90struct TextPickerDialogExample { 91 private select: number | number[] = 0 92 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4', 'banana5'] 93 @State v:string = ''; 94 95 build() { 96 Row() { 97 Column() { 98 Button("TextPickerDialog:" + this.v) 99 .margin(20) 100 .onClick(() => { 101 TextPickerDialog.show({ // You are advised to use this.getUIContext().showTextPickerDialog(). 102 range: this.fruits, 103 selected: this.select, 104 disappearTextStyle: {color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}, 105 textStyle: {color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}, 106 selectedTextStyle: {color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}, 107 onAccept: (value: TextPickerResult) => { 108 // 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. 109 this.select = value.index 110 console.log(this.select + '') 111 // After OK is clicked, the selected item is displayed on the page. 112 this.v = value.value as string 113 console.info("TextPickerDialog:onAccept()" + JSON.stringify(value)) 114 }, 115 onCancel: () => { 116 console.info("TextPickerDialog:onCancel()") 117 }, 118 onChange: (value: TextPickerResult) => { 119 console.info("TextPickerDialog:onChange()" + JSON.stringify(value)) 120 }, 121 onScrollStop: (value: TextPickerResult) => { 122 console.info("TextPickerDialog:onScrollStop()" + JSON.stringify(value)) 123 }, 124 onDidAppear: () => { 125 console.info("TextPickerDialog:onDidAppear()") 126 }, 127 onDidDisappear: () => { 128 console.info("TextPickerDialog:onDidDisappear()") 129 }, 130 onWillAppear: () => { 131 console.info("TextPickerDialog:onWillAppear()") 132 }, 133 onWillDisappear: () => { 134 console.info("TextPickerDialog:onWillDisappear()") 135 } 136 }) 137 }) 138 }.width('100%') 139 }.height('100%') 140 } 141} 142``` 143 144 145 146 147### Example 2: Customizing the Style 148 149In this example, **disappearTextStyle**, **textStyle**, **selectedTextStyle**, **acceptButtonStyle**, and **cancelButtonStyle** are configured to customize the text and button style. 150 151```ts 152// xxx.ets 153@Entry 154@Component 155struct TextPickerDialogExample { 156 private select: number | number[] = 0 157 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4', 'banana5'] 158 @State v:string = ''; 159 160 build() { 161 Row() { 162 Column() { 163 Button("TextPickerDialog:" + this.v) 164 .margin(20) 165 .onClick(() => { 166 TextPickerDialog.show({ // You are advised to use this.getUIContext().showTextPickerDialog(). 167 range: this.fruits, 168 selected: this.select, 169 disappearTextStyle: {color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}, 170 textStyle: {color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}, 171 selectedTextStyle: {color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}, 172 acceptButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Red, 173 fontSize: '26fp', fontWeight: FontWeight.Bolder, fontStyle: FontStyle.Normal, fontFamily: 'sans-serif', backgroundColor:'#80834511', 174 borderRadius: 20 }, 175 cancelButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Blue, 176 fontSize: '16fp', fontWeight: FontWeight.Normal, fontStyle: FontStyle.Italic, fontFamily: 'sans-serif', backgroundColor:'#50182431', 177 borderRadius: 10 }, 178 onAccept: (value: TextPickerResult) => { 179 // 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. 180 this.select = value.index 181 console.log(this.select + '') 182 // After OK is clicked, the selected item is displayed on the page. 183 this.v = value.value as string 184 console.info("TextPickerDialog:onAccept()" + JSON.stringify(value)) 185 }, 186 onCancel: () => { 187 console.info("TextPickerDialog:onCancel()") 188 }, 189 onChange: (value: TextPickerResult) => { 190 console.info("TextPickerDialog:onChange()" + JSON.stringify(value)) 191 }, 192 onScrollStop: (value: TextPickerResult) => { 193 console.info("TextPickerDialog:onScrollStop()" + JSON.stringify(value)) 194 }, 195 onDidAppear: () => { 196 console.info("TextPickerDialog:onDidAppear()") 197 }, 198 onDidDisappear: () => { 199 console.info("TextPickerDialog:onDidDisappear()") 200 }, 201 onWillAppear: () => { 202 console.info("TextPickerDialog:onWillAppear()") 203 }, 204 onWillDisappear: () => { 205 console.info("TextPickerDialog:onWillDisappear()") 206 } 207 }) 208 }) 209 }.width('100%') 210 }.height('100%') 211 } 212} 213``` 214 215 216 217### Example 3: Configuring a Dialog Box in the Hover State 218 219This example demonstrates how to set the layout area of a dialog box in hover mode on a foldable device. 220 221```ts 222@Entry 223@Component 224struct TextPickerDialogExample { 225 private select: number | number[] = 0; 226 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4', 'banana5']; 227 @State v: string = ''; 228 229 build() { 230 Row() { 231 Column() { 232 Button("TextPickerDialog:" + this.v) 233 .margin(20) 234 .onClick(() => { 235 TextPickerDialog.show({ // You are advised to use this.getUIContext().showTextPickerDialog(). 236 range: this.fruits, 237 selected: this.select, 238 disappearTextStyle: { color: Color.Red, font: { size: 15, weight: FontWeight.Lighter }}, 239 textStyle: { color: Color.Black, font: { size: 20, weight: FontWeight.Normal }}, 240 selectedTextStyle: { color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder }}, 241 onAccept: (value: TextPickerResult) => { 242 // 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. 243 this.select = value.index; 244 console.log(this.select + ''); 245 // After OK is clicked, the selected item is displayed on the page. 246 this.v = value.value as string; 247 console.info("TextPickerDialog:onAccept()" + JSON.stringify(value)); 248 }, 249 onCancel: () => { 250 console.info("TextPickerDialog:onCancel()"); 251 }, 252 onChange: (value: TextPickerResult) => { 253 console.info("TextPickerDialog:onChange()" + JSON.stringify(value)); 254 }, 255 onScrollStop: (value: TextPickerResult) => { 256 console.info("TextPickerDialog:onScrollStop()" + JSON.stringify(value)) 257 }, 258 onDidAppear: () => { 259 console.info("TextPickerDialog:onDidAppear()"); 260 }, 261 onDidDisappear: () => { 262 console.info("TextPickerDialog:onDidDisappear()"); 263 }, 264 onWillAppear: () => { 265 console.info("TextPickerDialog:onWillAppear()"); 266 }, 267 onWillDisappear: () => { 268 console.info("TextPickerDialog:onWillDisappear()"); 269 }, 270 enableHoverMode: true, 271 hoverModeArea: HoverModeAreaType.TOP_SCREEN 272 }) 273 }) 274 }.width('100%') 275 }.height('100%') 276 } 277} 278``` 279 280
