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> 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 [showTextPickerDialog](../js-apis-arkui-UIContext.md#showtextpickerdialog) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext) to obtain the UI context. 12 13## TextPickerDialog.show 14 15static show(options?: TextPickerDialogOptions) 16 17Shows a text picker in the given settings. 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 | [TextPickerDialogOptions](#textpickerdialogoptions) | No | Parameters of the text picker dialog box.| 28 29## TextPickerDialogOptions 30 31Inherits from [TextPickerOptions](ts-basic-components-textpicker.md#textpickeroptions). 32 33**System capability**: SystemCapability.ArkUI.ArkUI.Full 34 35| Name| Type| Mandatory| Description| 36| -------- | -------- | -------- | -------- | 37| 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.| 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| 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.| 44| 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.| 45| 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.| 46| 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.| 47| 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.| 48| 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.| 49| 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.| 50| 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.| 51| 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.| 52| 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.| 53| 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.| 54| 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.| 55| 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.| 56| 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.| 57 58## TextPickerResult 59 60**Atomic service API**: This API can be used in atomic services since API version 11. 61 62**System capability**: SystemCapability.ArkUI.ArkUI.Full 63 64| Name| Type| Read Only| Optional| Description| 65| -------- | -------- | -------- | -------- | -------- | 66| 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: \\| 67| 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.)| 68 69## Example 70 71### Example 1 72 73This example shows the basic usage of **TextPickerDialog**. 74 75```ts 76// xxx.ets 77@Entry 78@Component 79struct TextPickerDialogExample { 80 private select: number | number[] = 0 81 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4', 'banana5'] 82 @State v:string = ''; 83 84 build() { 85 Row() { 86 Column() { 87 Button("TextPickerDialog:" + this.v) 88 .margin(20) 89 .onClick(() => { 90 TextPickerDialog.show({ 91 range: this.fruits, 92 selected: this.select, 93 disappearTextStyle: {color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}, 94 textStyle: {color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}, 95 selectedTextStyle: {color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}, 96 onAccept: (value: TextPickerResult) => { 97 // 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. 98 this.select = value.index 99 console.log(this.select + '') 100 // After OK is clicked, the selected item is displayed on the page. 101 this.v = value.value as string 102 console.info("TextPickerDialog:onAccept()" + JSON.stringify(value)) 103 }, 104 onCancel: () => { 105 console.info("TextPickerDialog:onCancel()") 106 }, 107 onChange: (value: TextPickerResult) => { 108 console.info("TextPickerDialog:onChange()" + JSON.stringify(value)) 109 }, 110 onDidAppear: () => { 111 console.info("TextPickerDialog:onDidAppear()") 112 }, 113 onDidDisappear: () => { 114 console.info("TextPickerDialog:onDidDisappear()") 115 }, 116 onWillAppear: () => { 117 console.info("TextPickerDialog:onWillAppear()") 118 }, 119 onWillDisappear: () => { 120 console.info("TextPickerDialog:onWillDisappear()") 121 } 122 }) 123 }) 124 }.width('100%') 125 }.height('100%') 126 } 127} 128``` 129 130 131 132 133### Example 2 134 135This example shows how to customize the button style. 136 137```ts 138// xxx.ets 139@Entry 140@Component 141struct TextPickerDialogExample { 142 private select: number | number[] = 0 143 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4', 'banana5'] 144 @State v:string = ''; 145 146 build() { 147 Row() { 148 Column() { 149 Button("TextPickerDialog:" + this.v) 150 .margin(20) 151 .onClick(() => { 152 TextPickerDialog.show({ 153 range: this.fruits, 154 selected: this.select, 155 disappearTextStyle: {color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}, 156 textStyle: {color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}, 157 selectedTextStyle: {color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}, 158 acceptButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Red, 159 fontSize: '26fp', fontWeight: FontWeight.Bolder, fontStyle: FontStyle.Normal, fontFamily: 'sans-serif', backgroundColor:'#80834511', 160 borderRadius: 20 }, 161 cancelButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Blue, 162 fontSize: '16fp', fontWeight: FontWeight.Normal, fontStyle: FontStyle.Italic, fontFamily: 'sans-serif', backgroundColor:'#50182431', 163 borderRadius: 10 }, 164 onAccept: (value: TextPickerResult) => { 165 // 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. 166 this.select = value.index 167 console.log(this.select + '') 168 // After OK is clicked, the selected item is displayed on the page. 169 this.v = value.value as string 170 console.info("TextPickerDialog:onAccept()" + JSON.stringify(value)) 171 }, 172 onCancel: () => { 173 console.info("TextPickerDialog:onCancel()") 174 }, 175 onChange: (value: TextPickerResult) => { 176 console.info("TextPickerDialog:onChange()" + JSON.stringify(value)) 177 }, 178 onDidAppear: () => { 179 console.info("TextPickerDialog:onDidAppear()") 180 }, 181 onDidDisappear: () => { 182 console.info("TextPickerDialog:onDidDisappear()") 183 }, 184 onWillAppear: () => { 185 console.info("TextPickerDialog:onWillAppear()") 186 }, 187 onWillDisappear: () => { 188 console.info("TextPickerDialog:onWillDisappear()") 189 } 190 }) 191 }) 192 }.width('100%') 193 }.height('100%') 194 } 195} 196``` 197 198 199
