1# TextPicker 2 3The **TextPicker** component allows users to scroll to select text. 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 10## Child Components 11 12Not supported 13 14 15## APIs 16 17TextPicker(options?: TextPickerOptions) 18 19Creates a text picker based on the selection range specified by **range**. 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 | [TextPickerOptions](#textpickeroptions) | No | Parameters of the text picker.| 30 31## TextPickerOptions 32 33**Atomic service API**: This API can be used in atomic services since API version 11. 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37| Name| Type| Mandatory| Description| 38| -------- | -------- | -------- | -------- | 39| range | string[] \| string[] []<sup>10+</sup> \| [Resource](ts-types.md#resource) \|<br>[TextPickerRangeContent](#textpickerrangecontent10)[]<sup>10+</sup> \| [TextCascadePickerRangeContent](#textcascadepickerrangecontent10)[]<sup>10+</sup> | Yes| Data selection range of the picker. This parameter cannot be set to an empty array. If set to an empty array, it will not be displayed. If it is dynamically changed to an empty array, the current value remains displayed.<br>**NOTE**<br>For a single-column picker, use a value of the string[], Resource, or TextPickerRangeContent[] type.<br>For a multi-column picker, use a value of the string[] type.<br>For a multi-column linked picker, use a value of the TextCascadePickerRangeContent[] type.<br>The Resource type supports only [strarray.json](../../../quick-start/resource-categories-and-access.md#resource-group-directories).<br>The type and number of columns in the range cannot be dynamically modified.| 40| selected | number \| number[]<sup>10+</sup> | No| Index of the default selected item in the array. The index is zero-based.<br>Default value: **0**<br>**NOTE**<br>For a single-column picker, use a value of the number type.<br>For a multi-column (linked) picker, use a value of the number[] type.<br>Since API version 10, this parameter supports two-way binding through [$$](../../../ui/state-management/arkts-two-way-sync.md).| 41| value | string \| string[]<sup>10+</sup> | No| Value of the default item in the range. The priority of this parameter is lower than that of **selected**.<br>Default value: value of the first item<br>**NOTE**<br>This parameter works only when the picker contains text only. <br>For a single-column picker, use a value of the string type.<br>For a multi-column (linked) picker, use a value of the string[] type.<br>Since API version 10, this parameter supports two-way binding through [$$](../../../ui/state-management/arkts-two-way-sync.md).| 42| columnWidths<sup>18+</sup> | LengthMetrics[] | No| Width of each column in the picker.<br>Default value: All columns have equal widths.<br>**NOTE**<br>If the text is longer than the column width, it will be truncated.| 43 44## TextPickerRangeContent<sup>10+</sup> 45 46**Atomic service API**: This API can be used in atomic services since API version 11. 47 48**System capability**: SystemCapability.ArkUI.ArkUI.Full 49 50| Name| Type | Mandatory| Description | 51| ---- | ---------------------------------------------------- | ---- | ---------- | 52| icon | string \| [Resource](ts-types.md#resource) | Yes | Image resource. If the value is a string, such as **"/common/hello.png"**, it represents the path to the image.| 53| text | string \| [Resource](ts-types.md#resource) | No | Text information.<br>An empty character string is used by default.<br>**NOTE**<br>If the text is longer than the column width, it will be truncated.| 54 55## TextCascadePickerRangeContent<sup>10+</sup> 56 57**Atomic service API**: This API can be used in atomic services since API version 11. 58 59**System capability**: SystemCapability.ArkUI.ArkUI.Full 60 61| Name| Type | Mandatory| Description | 62| ------ | -------------------------------------------------------- | ---- | ---------- | 63| text | string \| [Resource](ts-types.md#resource) | Yes | Text information.<br>**NOTE**<br>If the text is longer than the column width, it will be truncated.| 64| children | [TextCascadePickerRangeContent](#textcascadepickerrangecontent10)[] | No | Linkage data.| 65## DividerOptions<sup>12+</sup> 66 67**Atomic service API**: This API can be used in atomic services since API version 12. 68 69**System capability**: SystemCapability.ArkUI.ArkUI.Full 70 71| Name | Type | Mandatory| Description | 72| ----------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 73| strokeWidth | [Dimension](ts-types.md#dimension10) | No | Stroke width of the divider. The unit is vp by default. You can also specify it as px. The percentage type is not supported.<br>If the value is less than 0, the default value is used. The maximum value allowed is half the height of the column.<br>Default value: **2.0px**| 74| startMargin | [Dimension](ts-types.md#dimension10) | No | Distance between the divider and the start edge of the picker. The unit is vp by default. You can also specify it as px. The percentage type is not supported.<br>Values less than 0 are invalid. The maximum value allowed is the width of the column.<br>Default value: **0**| 75| endMargin | [Dimension](ts-types.md#dimension10) | No | Distance between the divider and the end edge of the picker. The unit is vp by default. You can also specify it as px. The percentage type is not supported.<br>Values less than 0 are invalid. The maximum value allowed is the width of the column.<br>Default value: **0**| 76| color | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the divider.<br>Default value: **'#33000000'** 77 78## Attributes 79 80In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 81 82### defaultPickerItemHeight 83 84defaultPickerItemHeight(value: number | string) 85 86Sets the height of each item in the picker. 87 88**Atomic service API**: This API can be used in atomic services since API version 11. 89 90**System capability**: SystemCapability.ArkUI.ArkUI.Full 91 92**Parameters** 93 94| Name| Type | Mandatory| Description | 95| ------ | -------------------------- | ---- | ---------------------- | 96| value | number \| string | Yes | Height of each item in the picker. For the number type, the value range is [0, +∞). For the string type, only numeric string values, for example, **"56"**, are supported.<br>Default value: 56 vp (selected) and 36 vp (unselected).<br>**NOTE**<br>The set value applies to both selected and unselected items.| 97 98### defaultPickerItemHeight<sup>18+</sup> 99 100defaultPickerItemHeight(height: Optional\<number | string>) 101 102Sets the height of each item in the picker. Compared with [defaultPickerItemHeight](#defaultpickeritemheight), this API supports the **undefined** type for the **height** parameter. 103 104**Atomic service API**: This API can be used in atomic services since API version 18. 105 106**System capability**: SystemCapability.ArkUI.ArkUI.Full 107 108**Parameters** 109 110| Name| Type | Mandatory| Description | 111| ------ | -------------------------- | ---- | ---------------------- | 112| height | [Optional](ts-universal-attributes-custom-property.md#optional12)\<number \| string> | Yes | Height of each item in the picker. For the number type, the value range is [0, +∞). For the string type, only numeric string values, for example, **"56"**, are supported.<br>Default value: 56 vp (selected) and 36 vp (unselected).<br>**NOTE**<br>The set value applies to both selected and unselected items.<br>If **height** is set to **undefined**, the previous value is retained.| 113 114### disappearTextStyle<sup>10+</sup> 115 116disappearTextStyle(value: PickerTextStyle) 117 118Sets the font color, font size, and font weight for the top and bottom items. 119 120**Atomic service API**: This API can be used in atomic services since API version 11. 121 122**System capability**: SystemCapability.ArkUI.ArkUI.Full 123 124**Parameters** 125 126| Name| Type | Mandatory| Description | 127| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 128| value | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Yes | 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>} | 129 130### disappearTextStyle<sup>18+</sup> 131 132disappearTextStyle(style: Optional\<PickerTextStyle>) 133 134Sets the font color, font size, and font weight for the top and bottom items. Compared with [disappearTextStyle](#disappeartextstyle10)<sup>10+</sup>, this API supports the **undefined** type for the **style** parameter. 135 136**Atomic service API**: This API can be used in atomic services since API version 18. 137 138**System capability**: SystemCapability.ArkUI.ArkUI.Full 139 140**Parameters** 141 142| Name| Type | Mandatory| Description | 143| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 144| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10)> | Yes | Font color, font size, and font weight of the top and bottom items.<br>If **style** is set to **undefined**, the default value is used:<br>{<br>color: '#ff182431',<br>font: {<br>size: '14fp', <br>weight: FontWeight.Regular<br>}<br>} | 145 146### textStyle<sup>10+</sup> 147 148textStyle(value: PickerTextStyle) 149 150Sets the font color, font size, and font weight for all items except the top, bottom, and selected items. 151 152**Atomic service API**: This API can be used in atomic services since API version 11. 153 154**System capability**: SystemCapability.ArkUI.ArkUI.Full 155 156**Parameters** 157 158| Name| Type | Mandatory| Description | 159| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 160| value | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Yes | 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>} | 161 162### textStyle<sup>18+</sup> 163 164textStyle(style: Optional\<PickerTextStyle>) 165 166Sets the font color, font size, and font weight for all items except the top, bottom, and selected items. Compared with [textStyle](#textstyle10)<sup>10+</sup>, this API supports the **undefined** type for the **style** parameter. 167 168**Atomic service API**: This API can be used in atomic services since API version 18. 169 170**System capability**: SystemCapability.ArkUI.ArkUI.Full 171 172**Parameters** 173 174| Name| Type | Mandatory| Description | 175| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 176| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10)> | Yes | Font color, font size, and font weight of all items except the top, bottom, and selected items.<br>If **style** is set to **undefined**, the default value is used:<br>{<br>color: '#ff182431',<br>font: {<br>size: '16fp', <br>weight: FontWeight.Regular<br>}<br>} | 177 178### selectedTextStyle<sup>10+</sup> 179 180selectedTextStyle(value: PickerTextStyle) 181 182Sets the font color, font size, and font weight for the selected item. 183 184**Atomic service API**: This API can be used in atomic services since API version 11. 185 186**System capability**: SystemCapability.ArkUI.ArkUI.Full 187 188**Parameters** 189 190| Name| Type | Mandatory| Description | 191| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 192| value | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Yes | Font color, font size, and font weight of the selected item.<br>Default value:<br>{<br>color: '#ff007dff',<br>font: {<br>size: '20fp', <br>weight: FontWeight.Medium<br>}<br>} | 193 194### selectedTextStyle<sup>18+</sup> 195 196selectedTextStyle(style: Optional\<PickerTextStyle>) 197 198Sets the font color, font size, and font weight for the selected item. Compared with [selectedTextStyle](#selectedtextstyle10)<sup>10+</sup>, this API supports the **undefined** type for the **style** parameter. 199 200**Atomic service API**: This API can be used in atomic services since API version 18. 201 202**System capability**: SystemCapability.ArkUI.ArkUI.Full 203 204**Parameters** 205 206| Name| Type | Mandatory| Description | 207| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 208| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10)> | Yes | Font color, font size, and font weight of the selected item.<br>If **style** is set to **undefined**, the default value is used:<br>{<br>color: '#ff007dff',<br>font: {<br>size: '20fp', <br>weight: FontWeight.Medium<br>}<br>} | 209 210### selectedIndex<sup>10+</sup> 211 212selectedIndex(value: number | number[]) 213 214Sets the index of the default selected item in the array. Its priority is higher than that of the selected value in **options**. For a single-column picker, use a value of the number type. For a multi-column (linked) picker, use a value of the number[] type. 215 216**Atomic service API**: This API can be used in atomic services since API version 11. 217 218**System capability**: SystemCapability.ArkUI.ArkUI.Full 219 220**Parameters** 221 222| Name| Type | Mandatory| Description | 223| ------ | ---------------------------- | ---- | ---------------------------- | 224| value | number \| number[] | Yes | Index of the default selected item in the array. The index is zero-based.<br>Default value: **0**<br>If the value of **value** is **undefined**, the default value is the same as the value of **selected** in [options](#textpickeroptions). If the value of **selected** in [options](#textpickeroptions) is also **undefined**, the default value is **0**.<br>| 225 226### selectedIndex<sup>18+</sup> 227 228selectedIndex(index: Optional\<number | number[]>) 229 230Sets the index of the default selected item in the array. Its priority is higher than that of the selected value in **options**. For a single-column picker, use a value of the number type. For a multi-column (linked) picker, use a value of the number[] type. Compared with [selectedIndex](#selectedindex10), this API supports the **undefined** type for the **index** parameter. 231 232**Atomic service API**: This API can be used in atomic services since API version 18. 233 234**System capability**: SystemCapability.ArkUI.ArkUI.Full 235 236**Parameters** 237 238| Name| Type | Mandatory| Description | 239| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 240| index | [Optional](ts-universal-attributes-custom-property.md#optional12)\<number \| number[]> | Yes | Index of the default selected item in the array. The index is zero-based.<br>Default value: **0**<br>If the value of **index** is **undefined**, the default value is the same as the value of **selected** in [options](#textpickeroptions). If the value of **selected** in [options](#textpickeroptions) is also **undefined**, the default value is **0**.<br>| 241 242### canLoop<sup>10+</sup> 243 244canLoop(value: boolean) 245 246Sets whether scrolling is loopable. 247 248**Atomic service API**: This API can be used in atomic services since API version 11. 249 250**System capability**: SystemCapability.ArkUI.ArkUI.Full 251 252**Parameters** 253 254| Name| Type | Mandatory| Description | 255| ------ | ------- | ---- | ------------------------------------------------------------ | 256| value | boolean | Yes | Whether scrolling is loopable.<br>**true**: loopable<br>**false**: not loopable<br>Default value: **true**| 257 258### canLoop<sup>18+</sup> 259 260canLoop(isLoop: Optional\<boolean>) 261 262Sets whether scrolling is loopable. Compared with [canLoop](#canloop10)<sup>10+</sup>, this API supports the **undefined** type for the **isLoop** parameter. 263 264**Atomic service API**: This API can be used in atomic services since API version 18. 265 266**System capability**: SystemCapability.ArkUI.ArkUI.Full 267 268**Parameters** 269 270| Name| Type | Mandatory| Description | 271| ------ | ------- | ---- | ------------------------------------------------------------ | 272| isLoop | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | Yes | Whether scrolling is loopable.<br>**true**: loopable<br>**false**: not loopable<br>If **isLoop** is set to **undefined**, the default value **true** is used.| 273 274### divider<sup>12+</sup> 275 276divider(value: DividerOptions | null) 277 278Sets the divider style. If this attribute is not set, the divider is displayed based on the default value. 279 280If the sum of **startMargin** and **endMargin** exceeds the component width, both **startMargin** and **endMargin** will be set to **0**. 281 282**Atomic service API**: This API can be used in atomic services since API version 12. 283 284**System capability**: SystemCapability.ArkUI.ArkUI.Full 285 286**Parameters** 287| Name| Type | Mandatory| Description | 288| ------ | ------- | ---- | --------------------------------------------------------------------- | 289| value | [DividerOptions](#divideroptions12) \| null | Yes | Divider options.<br>1. If **DividerOptions** is set, the divider is displayed in the configured style.<br>Default value:<br>{<br>strokeWidth: '2px', <br>startMargin: 0, <br>endMargin: 0, <br>color: '#33000000'<br>}<br>2. If this parameter is set to **null**, the divider is not displayed.| 290 291### divider<sup>18+</sup> 292 293divider(textDivider: Optional\<DividerOptions | null>) 294 295Sets the divider style. If this attribute is not set, the divider is displayed based on the default value. Compared with [divider](#divider12)<sup>12+</sup>, this API supports the **undefined** type for the **textDivider** parameter. 296 297If the sum of **startMargin** and **endMargin** exceeds the component width, both **startMargin** and **endMargin** will be set to **0**. 298 299**Atomic service API**: This API can be used in atomic services since API version 18. 300 301**System capability**: SystemCapability.ArkUI.ArkUI.Full 302 303**Parameters** 304 305| Name| Type | Mandatory| Description | 306| ------ | ------- | ---- | --------------------------------------------------------------------- | 307| textDivider | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[DividerOptions](#divideroptions12) \| null> | Yes | Divider options.<br>1. If **DividerOptions** is set, the divider is displayed in the configured style.<br>If **textDivider** is set to **undefined**, the default value is used:<br>{<br>strokeWidth: '2px', <br>startMargin: 0, <br>endMargin: 0, <br>color: '#33000000'<br>}<br>2. If this parameter is set to **null**, the divider is not displayed.| 308 309### gradientHeight<sup>12+</sup> 310 311gradientHeight(value: Dimension) 312 313Sets the height for the fade effect. If this attribute is not set, the default fade effect is displayed. 314 315**Atomic service API**: This API can be used in atomic services since API version 12. 316 317**System capability**: SystemCapability.ArkUI.ArkUI.Full 318 319**Parameters** 320 321| Name| Type | Mandatory| Description | 322| ------ | ------- | ---- | ------------------------------------------------------------ | 323| value | [Dimension](ts-types.md#dimension10) | Yes | Height of the fade effect at the top and bottom edges of the content area. It can be set in percentage, with 100% (the maximum value) being half the height of the picker. Setting it to **0** results in no fade effect, while negative numbers or other invalid values display the default fade effect. Default value: **36vp**| 324 325### gradientHeight<sup>18+</sup> 326 327gradientHeight(height: Optional\<Dimension>) 328 329Sets the height for the fade effect. If this attribute is not set, the default fade effect is displayed. Compared with [gradientHeight](#gradientheight12)<sup>12+</sup>, this API supports the **undefined** type for the **height** parameter. 330 331**Atomic service API**: This API can be used in atomic services since API version 18. 332 333**System capability**: SystemCapability.ArkUI.ArkUI.Full 334 335**Parameters** 336 337| Name| Type | Mandatory| Description | 338| ------ | ------- | ---- | ------------------------------------------------------------ | 339| height | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[Dimension](ts-types.md#dimension10)> | Yes | Height of the fade effect at the top and bottom edges of the content area. It can be set in percentage, with 100% (the maximum value) being half the height of the picker. Setting it to **0** results in no fade effect, while negative numbers or other invalid values display the default fade effect. Default value: **36vp**<br>If **height** is set to **undefined**, the default value **36vp** is used.| 340 341> **NOTE** 342> 343> Avoid changing the attribute data during the animation process of this component. 344 345### disableTextStyleAnimation<sup>15+</sup> 346 347disableTextStyleAnimation(disabled: boolean) 348 349Sets whether to enable the text style change animation during the scrolling process. When this API is used with **true**, there are no text style changes, including the font size, weight, and color, during scrolling, and all text is displayed in the style set by [defaultTextStyle](#defaulttextstyle15). If **defaultTextStyle** is not set, the text is displayed in the default style of the **Text** component. 350 351**Atomic service API**: This API can be used in atomic services since API version 15. 352 353**System capability**: SystemCapability.ArkUI.ArkUI.Full 354 355**Parameters** 356 357| Name| Type | Mandatory| Description | 358| ------ | ------- | ---- | ------------------------------------------------------------ | 359| disabled | boolean | Yes | 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**| 360 361### defaultTextStyle<sup>15+</sup> 362 363defaultTextStyle(style: TextPickerTextStyle) 364 365Sets the style of the text items when the text style change animation during the scrolling process is disabled. 366 367**Atomic service API**: This API can be used in atomic services since API version 15. 368 369**System capability**: SystemCapability.ArkUI.ArkUI.Full 370 371**Parameters** 372 373| Name| Type | Mandatory| Description | 374| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 375| style | [TextPickerTextStyle](#textpickertextstyle15) | Yes | 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| 376 377> **NOTE** 378> 379> Avoid changing the attribute data during the animation process of this component. 380 381### enableHapticFeedback<sup>18+</sup> 382 383enableHapticFeedback(enable: Optional\<boolean>) 384 385Specifies whether to enable haptic feedback. 386 387**Atomic service API**: This API can be used in atomic services since API version 18. 388 389**System capability**: SystemCapability.ArkUI.ArkUI.Full 390 391| Name| Type | Mandatory | Description | 392| ------ | --------------------------------------------- |-----|-------------------------------------------------------------------------------------| 393| enable | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | Yes | Whether to enable haptic feedback.<br>**true** (default): Haptic feedback is enabled.<br>**false**: Haptic feedback is disabled.| 394 395> **NOTE** 396> 397> To enable haptic feedback, you must declare the ohos.permission.VIBRATE permission under **requestPermissions** in the **module.json5** file of the project. 398> ```json 399> "requestPermissions": [ 400> { 401> "name": "ohos.permission.VIBRATE", 402> } 403> ] 404> ``` 405 406### digitalCrownSensitivity<sup>18+</sup> 407digitalCrownSensitivity(sensitivity: Optional\<CrownSensitivity>) 408 409Sets the sensitivity to the digital crown rotation. 410 411**Atomic service API**: This API can be used in atomic services since API version 18. 412 413**System capability**: SystemCapability.ArkUI.ArkUI.Full 414 415| Name | Type | Mandatory | Description | 416| ----- | ---------------------------------------- | ---- | ------------------------- | 417| sensitivity | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[CrownSensitivity](ts-appendix-enums.md#crownsensitivity18)> | Yes | Sensitivity to the digital crown rotation.<br>Default value: **CrownSensitivity.MEDIUM** | 418 419> **NOTE** 420> 421> This API is only available to circular screens on wearable devices. The component needs to obtain focus before responding to the [crown event](ts-universal-events-crown.md). 422 423## Events 424 425In addition to the [universal events](ts-component-general-events.md), the following events are supported. 426 427### onChange 428 429onChange(callback: (value: string \| string[], index: number \| number[]) => void) 430 431Triggered when an item in the picker is selected. When the picker contains text only or both text and imagery, **value** indicates the text of the selected item. When the picker contains imagery only, **value** is empty. 432 433**Atomic service API**: This API can be used in atomic services since API version 11. 434 435**System capability**: SystemCapability.ArkUI.ArkUI.Full 436 437**Parameters** 438 439| Name| Type | Mandatory| Description | 440| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 441| value | string \| string[]<sup>10+</sup> | Yes | Text of the selected item. For a multi-column picker, **value** is of the array type. | 442| index | number \| number[]<sup>10+</sup> | Yes | Index of the selected item. The index is zero-based. For a multi-column picker, **index** is of the array type.| 443 444### onChange<sup>18+</sup> 445 446onChange(callback: Optional\<OnTextPickerChangeCallback>) 447 448Triggered when the text picker snaps to the selected item. Compared with [onChange](#onchange), this API supports the **undefined** type for the **callback** parameter. 449 450**Atomic service API**: This API can be used in atomic services since API version 18. 451 452**System capability**: SystemCapability.ArkUI.ArkUI.Full 453 454**Parameters** 455 456| Name | Type | Mandatory| Description | 457| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 458| callback | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[OnTextPickerChangeCallback](#ontextpickerchangecallback18)> | Yes | Callback invoked when an item in the picker is selected.<br>If **callback** is set to **undefined**, the callback function is not used.| 459 460### onScrollStop<sup>14+</sup> 461 462onScrollStop(callback: TextPickerScrollStopCallback) 463 464Triggered when the scrolling in the text picker stops. 465 466If the scrolling is initiated by a gesture, this event is triggered when the finger is lifted from the screen and the scrolling stops. 467 468**Atomic service API**: This API can be used in atomic services since API version 14. 469 470**System capability**: SystemCapability.ArkUI.ArkUI.Full 471 472**Parameters** 473 474| Name| Type | Mandatory| Description | 475| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 476| callback | [TextPickerScrollStopCallback](#textpickerscrollstopcallback14) | Yes | Triggered when the scrolling in the text picker stops.| 477 478### onScrollStop<sup>18+</sup> 479 480onScrollStop(callback: Optional\<TextPickerScrollStopCallback>) 481 482Triggered when the scrolling in the text picker stops. Compared with [onScrollStop](#onscrollstop14)<sup>14+</sup>, this API supports the **undefined** type for the **callback** parameter. 483 484If the scrolling is initiated by a gesture, this event is triggered when the finger is lifted from the screen and the scrolling stops. 485 486**Atomic service API**: This API can be used in atomic services since API version 18. 487 488**System capability**: SystemCapability.ArkUI.ArkUI.Full 489 490**Parameters** 491 492| Name| Type | Mandatory| Description | 493| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 494| callback | [TextPickerScrollStopCallback](#textpickerscrollstopcallback14) | Yes | Triggered when the scrolling in the text picker stops.<br>If **callback** is set to **undefined**, the callback function is not used.| 495 496### onEnterSelectedArea<sup>18+</sup> 497 498onEnterSelectedArea(callback: TextPickerEnterSelectedAreaCallback) 499 500Triggered during the scrolling of the text picker when an item enters the divider area. 501 502Compared with the **onChange** event, this event is triggered earlier, specifically when the scroll distance of the current column exceeds half the height of the selected item, which indicates that the item has entered the divider area. 503 504When the picker contains text only or a combination of images and text, **value** indicates the text of the selected item. When the picker contains images only, **value** is empty. 505 506**Atomic service API**: This API can be used in atomic services since API version 18. 507 508**System capability**: SystemCapability.ArkUI.ArkUI.Full 509 510**Parameters** 511 512| Name | Type | Mandatory| Description | 513| -------- | -------------------------- | ---- | ------------------------------------------ | 514| callback | [TextPickerEnterSelectedAreaCallback](#textpickerenterselectedareacallback18) | Yes | Triggered during the scrolling of the text picker when an item enters the divider area.| 515 516### onAccept<sup>(deprecated) </sup> 517 518onAccept(callback: (value: string, index: number) => void) 519 520Triggered when the OK button in the dialog box is clicked. This event can be triggered only in the [text picker dialog box](ts-methods-textpicker-dialog.md). 521 522This API is deprecated since API version 10. 523 524**System capability**: SystemCapability.ArkUI.ArkUI.Full 525 526**Parameters** 527 528| Name| Type | Mandatory| Description | 529| ------ | ------ | ---- | -------------------- | 530| value | string | Yes | Text of the selected item. | 531| index | number | Yes | Index of the selected item. The index is zero-based.| 532 533### onCancel<sup>(deprecated) </sup> 534 535onCancel(callback: () => void) 536 537Triggered when the Cancel button in the dialog box is clicked. This event can be triggered only in the [text picker dialog box](ts-methods-textpicker-dialog.md). 538 539This API is deprecated since API version 10. 540 541**System capability**: SystemCapability.ArkUI.ArkUI.Full 542 543## TextPickerTextStyle<sup>15+</sup> 544 545Defines the text style options. Inherits [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10). 546 547**Atomic service API**: This API can be used in atomic services since API version 15. 548 549| Name | Type | Mandatory | Description | 550| ----- | ---------------------------------------- | ---- | ------------------------- | 551| color | [ResourceColor](ts-types.md#resourcecolor) | No | Text color. | 552| font | [Font](ts-types.md#font) | No | Text style.| 553| minFontSize | number \| string \| [Resource](ts-types.md#resource) | No | Minimum font size, used in conjunction with **maxFontSize**. When **minFontSize** and **maxFontSize** are set, the **size** setting in **font** is ineffective. The default maximum number of lines is 1, and the default height adaptation mode is **MIN_FONT_SIZE_FIRST**. | 554| maxFontSize | number \| string \| [Resource](ts-types.md#resource) | No | Maximum font size. | 555| overflow | [TextOverflow](ts-appendix-enums.md#textoverflow) | No | Display mode when the text is too long. Ineffective when set to **MARQUEE**. | 556 557## OnTextPickerChangeCallback<sup>18+</sup> 558 559type OnTextPickerChangeCallback = (value: string | string[], index: number | number[]) => void 560 561Triggered when an item in the picker is selected. When the picker contains text only or both text and imagery, **value** indicates the text of the selected item. When the picker contains imagery only, **value** is empty. 562 563**Widget capability**: This API can be used in ArkTS widgets since API version 18. 564 565**Atomic service API**: This API can be used in atomic services since API version 18. 566 567**System capability**: SystemCapability.ArkUI.ArkUI.Full 568 569**Parameters** 570 571| Name| Type | Mandatory| Description | 572| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 573| value | string \| string[]<sup>10+</sup> | Yes | Text of the selected item. For a multi-column picker, **value** is of the array type. | 574| index | number \| number[]<sup>10+</sup> | Yes | Index of the selected item. The index is zero-based. For a multi-column picker, **index** is of the array type.| 575 576## TextPickerScrollStopCallback<sup>14+</sup> 577 578type TextPickerScrollStopCallback = (value: string | string[], index: number | number[]) => void 579 580Triggered when the scrolling in the text picker stops. 581 582When the picker contains text only or both text and imagery, **value** indicates the text of the selected item. When the picker contains imagery only, **value** is empty. 583 584**Widget capability**: This API can be used in ArkTS widgets since API version 14. 585 586**Atomic service API**: This API can be used in atomic services since API version 14. 587 588**System capability**: SystemCapability.ArkUI.ArkUI.Full 589 590**Parameters** 591 592| Name| Type | Mandatory| Description | 593| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 594| value | string \| string[] | Yes | Text of the selected item. For a multi-column picker, **value** is of the array type. | 595| index | number \| number[] | Yes | Index of the selected item. The index is zero-based. For a multi-column picker, **index** is of the array type.| 596 597## TextPickerEnterSelectedAreaCallback<sup>18+</sup> 598 599type TextPickerEnterSelectedAreaCallback = (value: string | string[], index: number | number[]) => void 600 601Represents the callback triggered during the scrolling of the text picker when an item enters the divider area. 602 603In scenarios where the picker contains linked columns, the use of this callback is not recommended. The reason is that it identifies nodes where items enter the divider area during scrolling. However, items that change in response to the scrolling do not themselves scroll. As a result, the callback's return values will only reflect changes for the currently scrolling column, while other non-scrolling columns will remain unchanged. 604 605**Widget capability**: This API can be used in ArkTS widgets since API version 18. 606 607**Atomic service API**: This API can be used in atomic services since API version 18. 608 609**System capability**: SystemCapability.ArkUI.ArkUI.Full 610 611**Parameters** 612 613| Name| Type | Mandatory| Description | 614| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 615| value | string \| string[] | Yes | Text of the selected item. For a multi-column picker, **value** is of the array type. | 616| index | number \| number[] | Yes | Index of the selected item. The index is zero-based. For a multi-column picker, **index** is of the array type.| 617 618## Example 619 620### Example 1: Setting the Number of Columns in the Picker 621 622This example demonstrates how to configure a single-column or multi-column text picker by setting **range** and customizing the width of each column using **columnWidths**. 623 624```ts 625// xxx.ets 626import { LengthMetrics } from '@kit.ArkUI' 627class bottom { 628 bottom:number = 50 629} 630let bott:bottom = new bottom() 631@Entry 632@Component 633struct TextPickerExample { 634 private select: number = 1 635 private apfruits: string[] = ['apple1', 'apple2', 'apple3', 'apple4'] 636 private orfruits: string[] = ['orange1', 'orange2', 'orange3', 'orange4'] 637 private pefruits: string[] = ['peach1', 'peach2', 'peach3', 'peach4'] 638 private multi: string[][] = [this.apfruits, this.orfruits, this.pefruits] 639 private cascade: TextCascadePickerRangeContent[] = [ 640 { 641 text: 'Liaoning Province', 642 children: [{ text: 'Shenyang', children: [{ text: 'Shenhe District' }, { text: 'Heping District' }, { text: 'Hunnan District' }] }, 643 { text: 'Dalian', children: [{ text: 'Zhongshan District' }, { text: 'Jinzhou District' }, { text: 'Changhai County' }] }] 644 }, 645 { 646 text: 'Jilin Province', 647 children: [{ text: 'Changchun', children: [{ text: 'Nanguan District' }, { text: 'Kuancheng District' }, { text: 'Chaoyang District' }] }, 648 { text: 'Siping', children: [{ text: 'Tiexi District' }, { text: 'Tiedong District' }, { text: 'Lishu County' }] }] 649 }, 650 { 651 text: 'Heilongjiang Province', 652 children: [{ text: 'Harbin', children: [{ text: 'Daoli District' }, { text: 'Daowai District' }, { text: 'Nangang District' }] }, 653 { text: 'Mudanjiang', children: [{ text: 'Dong'an District' }, { text: 'Xi'an District' }, { text: 'Aimin District' }] }] 654 } 655 ] 656 private singleColumnWidths: LengthMetrics[] = [ 657 LengthMetrics.percent(50) 658 ] 659 660 private multipleColumnWidths: LengthMetrics[] = [ 661 LengthMetrics.vp(100), 662 LengthMetrics.vp(200), 663 LengthMetrics.vp(100) 664 ] 665 666 private cascadeColumnWidths: LengthMetrics[] = [ 667 LengthMetrics.percent(20), 668 LengthMetrics.percent(30), 669 LengthMetrics.percent(50) 670 ] 671 build() { 672 Column() { 673 674 TextPicker({ range: this.apfruits, selected: this.select, columnWidths: this.singleColumnWidths }) 675 .onChange((value: string | string[], index: number | number[]) => { 676 console.info('Picker item changed, value: ' + value + ', index: ' + index) 677 }) 678 .onScrollStop((value: string | string[], index: number | number[]) => { 679 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 680 }).margin(bott) 681 .onEnterSelectedArea((value: string | string[], index: number | number[]) => { 682 console.info('Picker item enter selected area, value: ' + value + ', index: ' + index) 683 }) 684 685 TextPicker({ range: this.multi, columnWidths: this.multipleColumnWidths }) 686 .onChange((value: string | string[], index: number | number[]) => { 687 console.info('TextPicker multi-column: onChange' + JSON.stringify(value) + ',' + 'index:' + JSON.stringify(index)) 688 }) 689 .onScrollStop((value: string | string[], index: number | number[]) => { 690 console.info('TextPicker multi-column: onScrollStop ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 691 }).margin(bott) 692 .onEnterSelectedArea((value: string | string[], index: number | number[]) => { 693 console.info('TextPicker multi-column: onEnterSelectedArea ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 694 }) 695 696 TextPicker({ range: this.cascade, columnWidths: this.cascadeColumnWidths }) 697 .onChange((value: string | string[], index: number | number[]) => { 698 console.info('TextPicker multi-column linkage: onChange' + JSON.stringify(value) + ',' + 'index:' + JSON.stringify(index)) 699 }) 700 .onScrollStop((value: string | string[], index: number | number[]) => { 701 console.info('TextPicker multi-column linkage: onScrollStop ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 702 }) 703 .onEnterSelectedArea((value: string | string[], index: number | number[]) => { 704 console.info('TextPicker multi-column linkage: onEnterSelectedArea ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 705 }) 706 } 707 } 708} 709``` 710 711 712 713### Example 2: Setting the Text Style 714 715This example demonstrates how to configure **disappearTextStyle**, **textStyle**, and **selectedTextStyle** to customize the text style in a text picker. 716 717```ts 718// xxx.ets 719@Entry 720@Component 721struct TextPickerExample { 722 private select: number = 1 723 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 724 725 build() { 726 Column() { 727 TextPicker({ 728 range: this.fruits, 729 selected: this.select, 730 value: this.fruits[this.select] 731 }) 732 .onChange((value: string | string[], index: number | number[]) => { 733 console.info('Picker item changed, value: ' + value + ', index: ' + index) 734 }) 735 .onScrollStop((value: string | string[], index: number | number[]) => { 736 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 737 }) 738 .disappearTextStyle({ color: Color.Red, font: { size: 15, weight: FontWeight.Lighter } }) 739 .textStyle({ color: Color.Black, font: { size: 20, weight: FontWeight.Normal } }) 740 .selectedTextStyle({ color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } }) 741 .defaultPickerItemHeight(50) 742 .canLoop(false) 743 .selectedIndex(2) 744 }.width('100%').height('100%') 745 } 746} 747``` 748 749 750 751### Example 3: Using the No-Divider Style 752 753This example demonstrates how to configure a text picker with no divider by setting **divider** to **null**. 754 755```ts 756// xxx.ets 757@Entry 758@Component 759struct TextPickerExample { 760 private select: number = 1 761 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 762 763 build() { 764 Column() { 765 TextPicker({ range: this.fruits, selected: this.select }) 766 .onChange((value: string | string[], index: number | number[]) => { 767 console.info('Picker item changed, value: ' + value + ', index: ' + index) 768 }) 769 .onScrollStop((value: string | string[], index: number | number[]) => { 770 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 771 }) 772 .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}) 773 .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}) 774 .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}) 775 .divider(null) 776 }.width('100%').height('100%') 777 } 778} 779``` 780 781 782### Example 4: Using the Divider Style 783 784This example demonstrates how to configure a text picker with a custom divider style by setting **divider** with **DividerOptions**. 785 786```ts 787// xxx.ets 788@Entry 789@Component 790struct TextPickerExample { 791 private select: number = 1 792 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 793 794 build() { 795 Column() { 796 TextPicker({ range: this.fruits, selected: this.select }) 797 .onChange((value: string | string[], index: number | number[]) => { 798 console.info('Picker item changed, value: ' + value + ', index: ' + index) 799 }) 800 .onScrollStop((value: string | string[], index: number | number[]) => { 801 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 802 }) 803 .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}) 804 .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}) 805 .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}) 806 .divider({ 807 strokeWidth: 10, 808 color: Color.Red, 809 startMargin: 10, 810 endMargin: 20 811 } as DividerOptions) 812 }.width('100%').height('100%') 813 } 814} 815``` 816 817 818### Example 5: Setting the Fade Effect 819 820This example demonstrates how to customize the height of the fade effect in a text picker using **gradientHeight**. 821 822```ts 823// xxx.ets 824@Entry 825@Component 826struct TextPickerExample { 827 private select: number = 1 828 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 829 830 build() { 831 Column() { 832 TextPicker({ range: this.fruits, selected: this.select }) 833 .onChange((value: string | string[], index: number | number[]) => { 834 console.info('Picker item changed, value: ' + value + ', index: ' + index) 835 }) 836 .onScrollStop((value: string | string[], index: number | number[]) => { 837 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 838 }) 839 .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}) 840 .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}) 841 .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}) 842 .gradientHeight(100) 843 }.width('100%').height('100%') 844 } 845} 846``` 847 848 849 850### Example 6: Setting the Item Height 851 852This example demonstrates how to set the height of the picker items using **defaultPickerItemHeight**. 853 854```ts 855// xxx.ets 856@Entry 857@Component 858struct TextPickerExample { 859 private select: number = 1 860 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 861 862 build() { 863 Column() { 864 TextPicker({ range: this.fruits, selected: this.select }) 865 .defaultPickerItemHeight(60) 866 .onChange((value: string | string[], index: number | number[]) => { 867 console.info('Picker item changed, value: ' + value + ', index: ' + index) 868 }) 869 .onScrollStop((value: string | string[], index: number | number[]) => { 870 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 871 }) 872 }.width('100%').height('100%') 873 } 874} 875``` 876 877 878 879 880### Example 7: Setting Loopable Scrolling 881 882This example demonstrates how to set whether scrolling is loopable in a text picker using **canLoop**. 883 884```ts 885// xxx.ets 886@Entry 887@Component 888struct TextPickerExample { 889 @State isLoop: boolean = false 890 private select: number = 1 891 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 892 893 build() { 894 Column() { 895 TextPicker({ range: this.fruits, selected: this.select }) 896 .onChange((value: string | string[], index: number | number[]) => { 897 console.info('Picker item changed, value: ' + value + ', index: ' + index) 898 }) 899 .onScrollStop((value: string | string[], index: number | number[]) => { 900 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 901 }) 902 .canLoop(this.isLoop) 903 904 Row() { 905 Text('Loopable scrolling').fontSize(20) 906 907 Toggle({ type: ToggleType.Switch, isOn: false }) 908 .onChange((isOn: boolean) => { 909 this.isLoop = isOn 910 }) 911 }.position({ x: '60%', y: '40%' }) 912 913 }.width('100%') 914 } 915} 916``` 917 918 919 920### Example 8: Setting the Selected Item Index 921 922This example demonstrates how to set the index of the default selected item using **selectedIndex**. 923 924```ts 925// xxx.ets 926@Entry 927@Component 928struct TextPickerExample { 929 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 930 931 build() { 932 Column() { 933 TextPicker({ range: this.fruits, selected: 1 }) 934 .selectedIndex(2) 935 .onChange((value: string | string[], index: number | number[]) => { 936 console.info('Picker item changed, value: ' + value + ', index: ' + index) 937 }) 938 .onScrollStop((value: string | string[], index: number | number[]) => { 939 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 940 }) 941 }.width('100%').height('100%') 942 } 943} 944``` 945 946 947 948### Example 9: Disabling the Text Style Animation and Setting the Corresponding Text Style 949 950This example demonstrates how to disable the text style animation and set the corresponding text style using **disableTextStyleAnimation** and **defaultTextStyle**. 951 952```ts 953// xxx.ets 954@Entry 955@Component 956struct TextPickerExample { 957 private select: number = 1 958 private fruits: string[] = ['AAAAA', 'BBBBBBBBBBBBB', 'CCCC', 'DDDDDDDD', 'EEE'] 959 960 build() { 961 Column() { 962 TextPicker({ 963 range: this.fruits, 964 selected: this.select, 965 value: this.fruits[this.select] 966 }) 967 .disableTextStyleAnimation(true) 968 .margin({ bottom: 30 }) 969 TextPicker({ 970 range: this.fruits, 971 selected: this.select, 972 value: this.fruits[this.select] 973 }) 974 .disableTextStyleAnimation(true) 975 .defaultTextStyle({ minFontSize: 18, maxFontSize: 28, overflow: TextOverflow.Ellipsis }) 976 }.width('100%').height('100%') 977 } 978} 979``` 980 981 982
