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 attribute supports two-way binding through [$$](../../../quick-start/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 [$$](../../../quick-start/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 length exceeds the column width, the text 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 length exceeds the column width, the text 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 length exceeds the column width, the text 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 to [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 to [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 to [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: '20vp', <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 to [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: '20vp', <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>| 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 to [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>If **index** is set to **undefined**, the default value **0** is used.<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 to [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 to [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 to [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 407### digitalCrownSensitivity<sup>18+</sup> 408digitalCrownSensitivity(sensitivity: Optional\<CrownSensitivity>) 409 410Sets the sensitivity to the digital crown rotation. 411 412**Atomic service API**: This API can be used in atomic services since API version 18. 413 414**System capability**: SystemCapability.ArkUI.ArkUI.Full 415 416| Name | Type | Mandatory | Description | 417| ----- | ---------------------------------------- | ---- | ------------------------- | 418| sensitivity | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[CrownSensitivity](ts-appendix-enums.md#crownsensitivity18)> | Yes | Sensitivity to the digital crown rotation. | 419 420> **NOTE** 421> 422> This API is only available to circular screens on wearable devices. 423 424## Events 425 426In addition to the [universal events](ts-component-general-events.md), the following events are supported. 427 428### onChange 429 430onChange(callback: (value: string \| string[], index: number \| number[]) => void) 431 432Triggered 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. 433 434**Atomic service API**: This API can be used in atomic services since API version 11. 435 436**System capability**: SystemCapability.ArkUI.ArkUI.Full 437 438**Parameters** 439 440| Name| Type | Mandatory| Description | 441| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 442| value | string \| string[]<sup>10+</sup> | Yes | Text of the selected item. For a multi-column picker, **value** is of the array type. | 443| 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.| 444 445### onChange<sup>18+</sup> 446 447onChange(callback: Optional\<OnTextPickerChangeCallback>) 448 449Triggered when the text picker snaps to the selected item. Compared to [onChange](#onchange), this API supports the **undefined** type for the **callback** parameter. 450 451**Atomic service API**: This API can be used in atomic services since API version 18. 452 453**System capability**: SystemCapability.ArkUI.ArkUI.Full 454 455**Parameters** 456 457| Name | Type | Mandatory| Description | 458| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 459| 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.| 460 461### onScrollStop<sup>14+</sup> 462 463onScrollStop(callback: TextPickerScrollStopCallback) 464 465Triggered when the scrolling in the text picker stops. 466 467If the scrolling is initiated by a gesture, this event is triggered when the finger is lifted from the screen and the scrolling stops. 468 469**Atomic service API**: This API can be used in atomic services since API version 14. 470 471**System capability**: SystemCapability.ArkUI.ArkUI.Full 472 473**Parameters** 474 475| Name| Type | Mandatory| Description | 476| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 477| callback | [TextPickerScrollStopCallback](#textpickerscrollstopcallback14) | Yes | Triggered when the scrolling in the text picker stops.| 478 479### onScrollStop<sup>18+</sup> 480 481onScrollStop(callback: Optional\<TextPickerScrollStopCallback>) 482 483Triggered when the scrolling in the text picker stops. Compared to [onScrollStop](#onscrollstop14)<sup>14+</sup>, this API supports the **undefined** type for the **callback** parameter. 484 485If the scrolling is initiated by a gesture, this event is triggered when the finger is lifted from the screen and the scrolling stops. 486 487**Atomic service API**: This API can be used in atomic services since API version 18. 488 489**System capability**: SystemCapability.ArkUI.ArkUI.Full 490 491**Parameters** 492 493| Name| Type | Mandatory| Description | 494| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 495| 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.| 496 497### onEnterSelectedArea<sup>18+</sup> 498 499onEnterSelectedArea(callback: TextPickerEnterSelectedAreaCallback) 500 501Triggered during the scrolling of the text picker when an item enters the divider area. 502 503Compared to 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. 504 505When 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. 506 507**Atomic service API**: This API can be used in atomic services since API version 18. 508 509**System capability**: SystemCapability.ArkUI.ArkUI.Full 510 511**Parameters** 512 513| Name | Type | Mandatory| Description | 514| -------- | -------------------------- | ---- | ------------------------------------------ | 515| callback | [TextPickerEnterSelectedAreaCallback](#textpickerenterselectedareacallback18) | Yes | Triggered during the scrolling of the text picker when an item enters the divider area.| 516 517### onAccept<sup>(deprecated) </sup> 518 519onAccept(callback: (value: string, index: number) => void) 520 521Triggered 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). 522 523This API is deprecated since API version 10. 524 525**System capability**: SystemCapability.ArkUI.ArkUI.Full 526 527**Parameters** 528 529| Name| Type | Mandatory| Description | 530| ------ | ------ | ---- | -------------------- | 531| value | string | Yes | Text of the selected item. | 532| index | number | Yes | Index of the selected item. The index is zero-based.| 533 534### onCancel<sup>(deprecated) </sup> 535 536onCancel(callback: () => void) 537 538Triggered 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). 539 540This API is deprecated since API version 10. 541 542**System capability**: SystemCapability.ArkUI.ArkUI.Full 543 544## TextPickerTextStyle<sup>15+</sup> 545 546Defines the text style options. Inherits [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10). 547 548**Atomic service API**: This API can be used in atomic services since API version 15. 549 550| Name | Type | Mandatory | Description | 551| ----- | ---------------------------------------- | ---- | ------------------------- | 552| color | [ResourceColor](ts-types.md#resourcecolor) | No | Text color. | 553| font | [Font](ts-types.md#font) | No | Text style.| 554| 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**. | 555| maxFontSize | number \| string \| [Resource](ts-types.md#resource) | No | Maximum font size. | 556| overflow | [TextOverflow](ts-appendix-enums.md#textoverflow) | No | Display mode when the text is too long. Ineffective when set to **MARQUEE**. | 557 558## OnTextPickerChangeCallback<sup>18+</sup> 559 560type OnTextPickerChangeCallback = (value: string | string[], index: number | number[]) => void 561 562Triggered 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. 563 564**Widget capability**: This API can be used in ArkTS widgets since API version 18. 565 566**Atomic service API**: This API can be used in atomic services since API version 18. 567 568**System capability**: SystemCapability.ArkUI.ArkUI.Full 569 570**Parameters** 571 572| Name| Type | Mandatory| Description | 573| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 574| value | string \| string[]<sup>10+</sup> | Yes | Text of the selected item. For a multi-column picker, **value** is of the array type. | 575| 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.| 576 577## TextPickerScrollStopCallback<sup>14+</sup> 578 579type TextPickerScrollStopCallback = (value: string | string[], index: number | number[]) => void 580 581Triggered when the scrolling in the text picker stops. 582 583When 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. 584 585**Widget capability**: This API can be used in ArkTS widgets since API version 14. 586 587**Atomic service API**: This API can be used in atomic services since API version 14. 588 589**System capability**: SystemCapability.ArkUI.ArkUI.Full 590 591**Parameters** 592 593| Name| Type | Mandatory| Description | 594| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 595| value | string \| string[] | Yes | Text of the selected item. For a multi-column picker, **value** is of the array type. | 596| 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.| 597 598## TextPickerEnterSelectedAreaCallback<sup>18+</sup> 599 600type TextPickerEnterSelectedAreaCallback = (value: string | string[], index: number | number[]) => void 601 602Represents the callback triggered during the scrolling of the text picker when an item enters the divider area. 603 604In 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. 605 606**Widget capability**: This API can be used in ArkTS widgets since API version 18. 607 608**Atomic service API**: This API can be used in atomic services since API version 18. 609 610**System capability**: SystemCapability.ArkUI.ArkUI.Full 611 612**Parameters** 613 614| Name| Type | Mandatory| Description | 615| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 616| value | string \| string[] | Yes | Text of the selected item. For a multi-column picker, **value** is of the array type. | 617| 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.| 618 619## Example 620 621### Example 1: Setting the Number of Columns in the Picker 622 623This 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**. 624 625```ts 626// xxx.ets 627import { LengthMetrics } from '@kit.ArkUI' 628class bottom { 629 bottom:number = 50 630} 631let bott:bottom = new bottom() 632@Entry 633@Component 634struct TextPickerExample { 635 private select: number = 1 636 private apfruits: string[] = ['apple1', 'apple2', 'apple3', 'apple4'] 637 private orfruits: string[] = ['orange1', 'orange2', 'orange3', 'orange4'] 638 private pefruits: string[] = ['peach1', 'peach2', 'peach3', 'peach4'] 639 private multi: string[][] = [this.apfruits, this.orfruits, this.pefruits] 640 private cascade: TextCascadePickerRangeContent[] = [ 641 { 642 text: 'Liaoning Province', 643 children: [{ text: 'Shenyang', children: [{ text: 'Shenhe District' }, { text: 'Heping District' }, { text: 'Hunnan District' }] }, 644 { text: 'Dalian', children: [{ text: 'Zhongshan District' }, { text: 'Jinzhou District' }, { text: 'Changhai County' }] }] 645 }, 646 { 647 text: 'Jilin Province', 648 children: [{ text: 'Changchun', children: [{ text: 'Nanguan District' }, { text: 'Kuancheng District' }, { text: 'Chaoyang District' }] }, 649 { text: 'Siping', children: [{ text: 'Tiexi District' }, { text: 'Tiedong District' }, { text: 'Lishu County' }] }] 650 }, 651 { 652 text: 'Heilongjiang Province', 653 children: [{ text: 'Harbin', children: [{ text: 'Daoli District' }, { text: 'Daowai District' }, { text: 'Nangang District' }] }, 654 { text: 'Mudanjiang', children: [{ text: 'Dong'an District' }, { text: 'Xi'an District' }, { text: 'Aimin District' }] }] 655 } 656 ] 657 private singleColumnWidths: LengthMetrics[] = [ 658 LengthMetrics.percent(50) 659 ] 660 661 private multipleColumnWidths: LengthMetrics[] = [ 662 LengthMetrics.vp(100), 663 LengthMetrics.vp(200), 664 LengthMetrics.vp(100) 665 ] 666 667 private cascadeColumnWidths: LengthMetrics[] = [ 668 LengthMetrics.percent(20), 669 LengthMetrics.percent(30), 670 LengthMetrics.percent(50) 671 ] 672 build() { 673 Column() { 674 675 TextPicker({ range: this.apfruits, selected: this.select, columnWidths: this.singleColumnWidths }) 676 .onChange((value: string | string[], index: number | number[]) => { 677 console.info('Picker item changed, value: ' + value + ', index: ' + index) 678 }) 679 .onScrollStop((value: string | string[], index: number | number[]) => { 680 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 681 }).margin(bott) 682 .onEnterSelectedArea((value: string | string[], index: number | number[]) => { 683 console.info('Picker item enter selected area, value: ' + value + ', index: ' + index) 684 }) 685 686 TextPicker({ range: this.multi, columnWidths: this.multipleColumnWidths }) 687 .onChange((value: string | string[], index: number | number[]) => { 688 console.info('TextPicker multi-column: onChange' + JSON.stringify(value) + ',' + 'index:' + JSON.stringify(index)) 689 }) 690 .onScrollStop((value: string | string[], index: number | number[]) => { 691 console.info('TextPicker multi-column: onScrollStop ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 692 }).margin(bott) 693 .onEnterSelectedArea((value: string | string[], index: number | number[]) => { 694 console.info('TextPicker multi-column: onEnterSelectedArea ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 695 }) 696 697 TextPicker({ range: this.cascade, columnWidths: this.cascadeColumnWidths }) 698 .onChange((value: string | string[], index: number | number[]) => { 699 console.info('TextPicker multi-column linkage: onChange' + JSON.stringify(value) + ',' + 'index:' + JSON.stringify(index)) 700 }) 701 .onScrollStop((value: string | string[], index: number | number[]) => { 702 console.info('TextPicker multi-column linkage: onScrollStop ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 703 }) 704 .onEnterSelectedArea((value: string | string[], index: number | number[]) => { 705 console.info('TextPicker multi-column linkage: onEnterSelectedArea ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 706 }) 707 } 708 } 709} 710``` 711 712 713 714### Example 2: Setting the Text Style 715 716This example demonstrates how to configure **disappearTextStyle**, **textStyle**, and **selectedTextStyle** to customize the text style in a text picker. 717 718```ts 719// xxx.ets 720@Entry 721@Component 722struct TextPickerExample { 723 private select: number = 1 724 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 725 726 build() { 727 Column() { 728 TextPicker({ 729 range: this.fruits, 730 selected: this.select, 731 value: this.fruits[this.select] 732 }) 733 .onChange((value: string | string[], index: number | number[]) => { 734 console.info('Picker item changed, value: ' + value + ', index: ' + index) 735 }) 736 .onScrollStop((value: string | string[], index: number | number[]) => { 737 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 738 }) 739 .disappearTextStyle({ color: Color.Red, font: { size: 15, weight: FontWeight.Lighter } }) 740 .textStyle({ color: Color.Black, font: { size: 20, weight: FontWeight.Normal } }) 741 .selectedTextStyle({ color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } }) 742 .defaultPickerItemHeight(50) 743 .canLoop(false) 744 .selectedIndex(2) 745 }.width('100%').height('100%') 746 } 747} 748``` 749 750 751 752### Example 3: Using the No-Divider Style 753 754This example demonstrates how to configure a text picker with no divider by setting **divider** to **null**. 755 756```ts 757// xxx.ets 758@Entry 759@Component 760struct TextPickerExample { 761 private select: number = 1 762 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 763 764 build() { 765 Column() { 766 TextPicker({ range: this.fruits, selected: this.select }) 767 .onChange((value: string | string[], index: number | number[]) => { 768 console.info('Picker item changed, value: ' + value + ', index: ' + index) 769 }) 770 .onScrollStop((value: string | string[], index: number | number[]) => { 771 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 772 }) 773 .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}) 774 .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}) 775 .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}) 776 .divider(null) 777 }.width('100%').height('100%') 778 } 779} 780``` 781 782 783### Example 4: Using the Divider Style 784 785This example demonstrates how to configure a text picker with a custom divider style by setting **divider** with **DividerOptions**. 786 787```ts 788// xxx.ets 789@Entry 790@Component 791struct TextPickerExample { 792 private select: number = 1 793 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 794 795 build() { 796 Column() { 797 TextPicker({ range: this.fruits, selected: this.select }) 798 .onChange((value: string | string[], index: number | number[]) => { 799 console.info('Picker item changed, value: ' + value + ', index: ' + index) 800 }) 801 .onScrollStop((value: string | string[], index: number | number[]) => { 802 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 803 }) 804 .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}) 805 .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}) 806 .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}) 807 .divider({ 808 strokeWidth: 10, 809 color: Color.Red, 810 startMargin: 10, 811 endMargin: 20 812 } as DividerOptions) 813 }.width('100%').height('100%') 814 } 815} 816``` 817 818 819### Example 5: Setting the Fade Effect 820 821This example demonstrates how to customize the height of the fade effect in a text picker using **gradientHeight**. 822 823```ts 824// xxx.ets 825@Entry 826@Component 827struct TextPickerExample { 828 private select: number = 1 829 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 830 831 build() { 832 Column() { 833 TextPicker({ range: this.fruits, selected: this.select }) 834 .onChange((value: string | string[], index: number | number[]) => { 835 console.info('Picker item changed, value: ' + value + ', index: ' + index) 836 }) 837 .onScrollStop((value: string | string[], index: number | number[]) => { 838 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 839 }) 840 .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}) 841 .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}) 842 .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}) 843 .gradientHeight(100) 844 }.width('100%').height('100%') 845 } 846} 847``` 848 849 850 851### Example 6: Setting the Item Height 852 853This example demonstrates how to set the height of the picker items using **defaultPickerItemHeight**. 854 855```ts 856// xxx.ets 857@Entry 858@Component 859struct TextPickerExample { 860 private select: number = 1 861 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 862 863 build() { 864 Column() { 865 TextPicker({ range: this.fruits, selected: this.select }) 866 .defaultPickerItemHeight(60) 867 .onChange((value: string | string[], index: number | number[]) => { 868 console.info('Picker item changed, value: ' + value + ', index: ' + index) 869 }) 870 .onScrollStop((value: string | string[], index: number | number[]) => { 871 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 872 }) 873 }.width('100%').height('100%') 874 } 875} 876``` 877 878 879 880 881### Example 7: Setting Loopable Scrolling 882 883This example demonstrates how to set whether scrolling is loopable in a text picker using **canLoop**. 884 885```ts 886// xxx.ets 887@Entry 888@Component 889struct TextPickerExample { 890 @State isLoop: boolean = false 891 private select: number = 1 892 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 893 894 build() { 895 Column() { 896 TextPicker({ range: this.fruits, selected: this.select }) 897 .onChange((value: string | string[], index: number | number[]) => { 898 console.info('Picker item changed, value: ' + value + ', index: ' + index) 899 }) 900 .onScrollStop((value: string | string[], index: number | number[]) => { 901 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 902 }) 903 .canLoop(this.isLoop) 904 905 Row() { 906 Text('Loopable scrolling').fontSize(20) 907 908 Toggle({ type: ToggleType.Switch, isOn: false }) 909 .onChange((isOn: boolean) => { 910 this.isLoop = isOn 911 }) 912 }.position({ x: '60%', y: '40%' }) 913 914 }.width('100%') 915 } 916} 917``` 918 919 920 921### Example 8: Setting the Selected Item Index 922 923This example demonstrates how to set the index of the default selected item using **selectedIndex**. 924 925```ts 926// xxx.ets 927@Entry 928@Component 929struct TextPickerExample { 930 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 931 932 build() { 933 Column() { 934 TextPicker({ range: this.fruits, selected: 1 }) 935 .selectedIndex(2) 936 .onChange((value: string | string[], index: number | number[]) => { 937 console.info('Picker item changed, value: ' + value + ', index: ' + index) 938 }) 939 .onScrollStop((value: string | string[], index: number | number[]) => { 940 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 941 }) 942 }.width('100%').height('100%') 943 } 944} 945``` 946 947 948 949### Example 9: Disabling the Text Style Animation and Setting the Corresponding Text Style 950 951This example demonstrates how to disable the text style animation and set the corresponding text style using **disableTextStyleAnimation** and **defaultTextStyle**. 952 953```ts 954// xxx.ets 955@Entry 956@Component 957struct TextPickerExample { 958 private select: number = 1 959 private fruits: string[] = ['AAAAA', 'BBBBBBBBBBBBB', 'CCCC', 'DDDDDDDD', 'EEE'] 960 961 build() { 962 Column() { 963 TextPicker({ 964 range: this.fruits, 965 selected: this.select, 966 value: this.fruits[this.select] 967 }) 968 .disableTextStyleAnimation(true) 969 .margin({ bottom: 30 }) 970 TextPicker({ 971 range: this.fruits, 972 selected: this.select, 973 value: this.fruits[this.select] 974 }) 975 .disableTextStyleAnimation(true) 976 .defaultTextStyle({ minFontSize: 18, maxFontSize: 28, overflow: TextOverflow.Ellipsis }) 977 }.width('100%').height('100%') 978 } 979} 980``` 981 982 983
