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 item in the range.<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 attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).|
42
43## TextPickerRangeContent<sup>10+</sup>
44
45**Atomic service API**: This API can be used in atomic services since API version 11.
46
47**System capability**: SystemCapability.ArkUI.ArkUI.Full
48
49| Name| Type                                                | Mandatory| Description  |
50| ------ | -------------------------------------------------------- | ---- | ---------- |
51| icon   | string \| [Resource](ts-types.md#resource) | Yes  | Image resource.|
52| text   | string \| [Resource](ts-types.md#resource) | No  | Text information.|
53
54## TextCascadePickerRangeContent<sup>10+</sup>
55
56**Atomic service API**: This API can be used in atomic services since API version 11.
57
58**System capability**: SystemCapability.ArkUI.ArkUI.Full
59
60| Name| Type                                                | Mandatory| Description  |
61| ------ | -------------------------------------------------------- | ---- | ---------- |
62| text   | string \| [Resource](ts-types.md#resource) | Yes  | Text information.|
63| children   | [TextCascadePickerRangeContent](#textcascadepickerrangecontent10)[] | No  | Linkage data.|
64## DividerOptions<sup>12+</sup>
65
66**Atomic service API**: This API can be used in atomic services since API version 12.
67
68**System capability**: SystemCapability.ArkUI.ArkUI.Full
69
70| Name     | Type     | Mandatory| Description                                                      |
71| ----------- | ------------- | ---- | -------------------------------------------------------------- |
72| 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.|
73| 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.|
74| 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.|
75| color       | [ResourceColor](ts-types.md#resourcecolor)  | No  | Color of the divider.
76
77## Attributes
78
79In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
80
81### defaultPickerItemHeight
82
83defaultPickerItemHeight(value: number | string)
84
85Sets the height of each item in the picker.
86
87**Atomic service API**: This API can be used in atomic services since API version 11.
88
89**System capability**: SystemCapability.ArkUI.ArkUI.Full
90
91**Parameters**
92
93| Name| Type                      | Mandatory| Description                  |
94| ------ | -------------------------- | ---- | ---------------------- |
95| value  | number \| string | Yes  | Height of each item in the picker.|
96
97### disappearTextStyle<sup>10+</sup>
98
99disappearTextStyle(value: PickerTextStyle)
100
101Sets the font color, font size, and font weight for the top and bottom items.
102
103**Atomic service API**: This API can be used in atomic services since API version 11.
104
105**System capability**: SystemCapability.ArkUI.ArkUI.Full
106
107**Parameters**
108
109| Name| Type                                                        | Mandatory| Description                                                        |
110| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
111| 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>} |
112
113### textStyle<sup>10+</sup>
114
115textStyle(value: PickerTextStyle)
116
117Sets the font color, font size, and font weight for all items except the top, bottom, and selected items.
118
119**Atomic service API**: This API can be used in atomic services since API version 11.
120
121**System capability**: SystemCapability.ArkUI.ArkUI.Full
122
123**Parameters**
124
125| Name| Type                                                        | Mandatory| Description                                                        |
126| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
127| 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>} |
128
129### selectedTextStyle<sup>10+</sup>
130
131selectedTextStyle(value: PickerTextStyle)
132
133Sets the font color, font size, and font weight for the selected item.
134
135**Atomic service API**: This API can be used in atomic services since API version 11.
136
137**System capability**: SystemCapability.ArkUI.ArkUI.Full
138
139**Parameters**
140
141| Name| Type                                                        | Mandatory| Description                                                        |
142| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
143| 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>} |
144
145### selectedIndex<sup>10+</sup>
146
147selectedIndex(value: number | number[])
148
149Sets 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.
150
151**Atomic service API**: This API can be used in atomic services since API version 11.
152
153**System capability**: SystemCapability.ArkUI.ArkUI.Full
154
155**Parameters**
156
157| Name| Type                        | Mandatory| Description                        |
158| ------ | ---------------------------- | ---- | ---------------------------- |
159| value  | number \| number[] | Yes  | Index of the default selected item in the array.<br>Default value: **0**<br>|
160
161### canLoop<sup>10+</sup>
162
163canLoop(value: boolean)
164
165Sets whether scrolling is loopable.
166
167**Atomic service API**: This API can be used in atomic services since API version 11.
168
169**System capability**: SystemCapability.ArkUI.ArkUI.Full
170
171**Parameters**
172
173| Name| Type   | Mandatory| Description                                                        |
174| ------ | ------- | ---- | ------------------------------------------------------------ |
175| value  | boolean | Yes  | Whether scrolling is loopable.<br>**true**: loopable<br>**false**: not loopable<br>Default value: **true**|
176
177### divider<sup>12+</sup>
178
179divider(value: DividerOptions | null)
180
181Sets the divider style. If this attribute is not set, the divider is displayed based on the default value.
182
183If the sum of **startMargin** and **endMargin** exceeds the component width, both **startMargin** and **endMargin** will be set to **0**.
184
185**Atomic service API**: This API can be used in atomic services since API version 12.
186
187**System capability**: SystemCapability.ArkUI.ArkUI.Full
188
189**Parameters**
190| Name| Type   | Mandatory| Description                                                                 |
191| ------ | ------- | ---- | --------------------------------------------------------------------- |
192| 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.|
193
194### gradientHeight<sup>12+</sup>
195
196gradientHeight(value: Dimension)
197
198Sets the height for the fade-out effect. If this attribute is not set, the default fade-out effect will be displayed.
199
200**Atomic service API**: This API can be used in atomic services since API version 12.
201
202**System capability**: SystemCapability.ArkUI.ArkUI.Full
203
204**Parameters**
205
206| Name| Type   | Mandatory| Description                                                        |
207| ------ | ------- | ---- | ------------------------------------------------------------ |
208| value  | [Dimension](ts-types.md#dimension10) | Yes  | Height of the gradient 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** will result in no gradient effect, while negative numbers or other invalid values will display the default gradient effect. Default value: **36vp**|
209
210> **NOTE**
211>
212> Avoid changing the attribute data during the animation process of this component.
213
214## Events
215
216In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
217
218### onAccept<sup>(deprecated) </sup>
219
220onAccept(callback: (value: string, index: number) => void)
221
222Triggered 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).
223
224This API is deprecated since API version 10.
225
226**System capability**: SystemCapability.ArkUI.ArkUI.Full
227
228**Parameters**
229
230| Name| Type  | Mandatory| Description                |
231| ------ | ------ | ---- | -------------------- |
232| value  | string | Yes  | Text of the selected item.  |
233| index  | number | Yes  | Index of the selected item.|
234
235### onCancel<sup>(deprecated) </sup>
236
237onCancel(callback: () => void)
238
239Triggered 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).
240
241This API is deprecated since API version 10.
242
243**System capability**: SystemCapability.ArkUI.ArkUI.Full
244
245### onChange
246
247onChange(callback: (value: string \| string[], index: number \| number[]) =&gt; void)
248
249Triggered 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.
250
251**Atomic service API**: This API can be used in atomic services since API version 11.
252
253**System capability**: SystemCapability.ArkUI.ArkUI.Full
254
255**Parameters**
256
257| Name| Type                                      | Mandatory| Description                                             |
258| ------ | ------------------------------------------ | ---- | ------------------------------------------------- |
259| value  | string \| string[]<sup>10+</sup> | Yes  | Text of the selected item. For a multi-column picker, **value** is of the array type.  |
260| index  | number \| number[]<sup>10+</sup> | Yes  | Index of the selected item. For a multi-column picker, **index** is of the array type.|
261
262### onScrollStop<sup>14+</sup>
263
264onScrollStop(callback: (value: string \| string[], index: number \| number[]) =&gt; void)
265
266Triggered when the scrolling in the text picker stops.
267
268If the scrolling is initiated by a gesture, this event is triggered when the finger is lifted from the screen and the scrolling stops.
269
270When 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.
271
272**Atomic service API**: This API can be used in atomic services since API version 14.
273
274**System capability**: SystemCapability.ArkUI.ArkUI.Full
275
276**Parameters**
277
278| Name| Type                                      | Mandatory| Description                                             |
279| ------ | ------------------------------------------ | ---- | ------------------------------------------------- |
280| value  | string \| string[] | Yes  | Text of the selected item. For a multi-column picker, **value** is of the array type.  |
281| index  | number \| number[] | Yes  | Index of the selected item. For a multi-column picker, **index** is of the array type.|
282
283## Example
284
285### Example 1: Setting the Number of Columns in the Picker
286
287This example demonstrates how to set **range** to implement single-column or multi-column text pickers.
288
289```ts
290// xxx.ets
291class bottom {
292  bottom:number = 50
293}
294let bott:bottom = new bottom()
295@Entry
296@Component
297struct TextPickerExample {
298  private select: number = 1
299  private apfruits: string[] = ['apple1', 'apple2', 'apple3', 'apple4']
300  private orfruits: string[] = ['orange1', 'orange2', 'orange3', 'orange4']
301  private pefruits: string[] = ['peach1', 'peach2', 'peach3', 'peach4']
302  private multi: string[][] = [this.apfruits, this.orfruits, this.pefruits]
303  private cascade: TextCascadePickerRangeContent[] = [
304    {
305      text: 'Asia',
306      children: [{ text: 'China', children: [{ text: 'Beijing' }, { text: 'Shanghai' }, { text: 'Chongqing' }] },
307        { text: 'Japan', children: [{ text: 'Tokyo' }, { text: 'Hokkaido' }, { text: 'Osaka' }] }]
308    },
309    {
310      text: 'Europe',
311      children: [{ text: 'Germany', children: [{ text: 'Berlin' }, { text: 'Munich' }, { text: 'Nuremberg' }] },
312        { text: 'France', children: [{ text: 'Paris' }, { text: 'Lille' }, { text: 'Orleans' }] }]
313    },
314    {
315      text: 'Africa',
316      children: [{ text: 'Egypt', children: [{ text: 'Cairo' }, { text: 'Damietta' }, { text: 'Girga' }] },
317        { text: 'Algeria', children: [{ text: 'Alger' }, { text: 'Oran' }, { text: 'Adrar' }] }]
318    }
319  ]
320
321  build() {
322    Column() {
323
324      TextPicker({ range: this.apfruits, selected: this.select })
325        .onChange((value: string | string[], index: number | number[]) => {
326          console.info('Picker item changed, value: ' + value + ', index: ' + index)
327        })
328        .onScrollStop((value: string | string[], index: number | number[]) => {
329          console.info('Picker scroll stopped, value: ' + value + ', index: ' + index)
330        }).margin(bott)
331
332      TextPicker({ range: this.multi })
333        .onChange((value: string | string[], index: number | number[]) => {
334          console.info('TextPicker multi-column: onChange' + JSON.stringify(value) + ',' + 'index:' + JSON.stringify(index))
335        })
336        .onScrollStop((value: string | string[], index: number | number[]) => {
337          console.info('TextPicker multi-column: onScrollStop ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index))
338        }).margin(bott)
339
340      TextPicker({ range: this.cascade })
341        .onChange((value: string | string[], index: number | number[]) => {
342          console.info('TextPicker multi-column linkage: onChange' + JSON.stringify(value) + ',' + 'index:' + JSON.stringify(index))
343        })
344        .onScrollStop((value: string | string[], index: number | number[]) => {
345          console.info('TextPicker multi-column linkage: onScrollStop ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index))
346        })
347    }
348  }
349}
350```
351
352![textpicker](figures/textpicker.gif)
353
354### Example 2: Setting the Text Style
355
356This example demonstrates how to configure **disappearTextStyle**, **textStyle**, and **selectedTextStyle** to customize the text style in a text picker.
357
358```ts
359// xxx.ets
360@Entry
361@Component
362struct TextPickerExample {
363  private select: number = 1
364  private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4']
365
366  build() {
367    Column() {
368      TextPicker({ range: this.fruits, selected: this.select })
369        .onChange((value: string | string[], index: number | number[]) => {
370          console.info('Picker item changed, value: ' + value + ', index: ' + index)
371        })
372        .onScrollStop((value: string | string[], index: number | number[]) => {
373          console.info('Picker scroll stopped, value: ' + value + ', index: ' + index)
374        })
375        .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}})
376        .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}})
377        .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}})
378    }.width('100%').height('100%')
379  }
380}
381```
382
383![textpicker](figures/textpicker1.gif)
384
385### Example 3: Using the No-Divider Style
386
387This example demonstrates how to configure a text picker with no divider by setting **divider** to **null**.
388
389```ts
390// xxx.ets
391@Entry
392@Component
393struct TextPickerExample {
394  private select: number = 1
395  private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4']
396
397  build() {
398    Column() {
399      TextPicker({ range: this.fruits, selected: this.select })
400        .onChange((value: string | string[], index: number | number[]) => {
401          console.info('Picker item changed, value: ' + value + ', index: ' + index)
402        })
403        .onScrollStop((value: string | string[], index: number | number[]) => {
404          console.info('Picker scroll stopped, value: ' + value + ', index: ' + index)
405        })
406        .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}})
407        .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}})
408        .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}})
409        .divider(null)
410    }.width('100%').height('100%')
411  }
412}
413```
414![textpicker](figures/textpicker2.gif)
415
416### Example 3: Using the Divider Style
417
418This example demonstrates how to configure a text picker with a custom divider style by setting **divider** with **DividerOptions**.
419
420```ts
421// xxx.ets
422@Entry
423@Component
424struct TextPickerExample {
425  private select: number = 1
426  private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4']
427
428  build() {
429    Column() {
430      TextPicker({ range: this.fruits, selected: this.select })
431        .onChange((value: string | string[], index: number | number[]) => {
432          console.info('Picker item changed, value: ' + value + ', index: ' + index)
433        })
434        .onScrollStop((value: string | string[], index: number | number[]) => {
435          console.info('Picker scroll stopped, value: ' + value + ', index: ' + index)
436        })
437        .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}})
438        .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}})
439        .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}})
440        .divider({
441          strokeWidth: 10,
442          color: Color.Red,
443          startMargin: 10,
444          endMargin: 20
445        } as DividerOptions)
446    }.width('100%').height('100%')
447  }
448}
449```
450![textpicker](figures/textpicker3.gif)
451
452### Example 5: Setting the Fade Effect
453
454This example demonstrates how to customize the height of the fade effect in a text picker using **gradientHeight**.
455
456```ts
457// xxx.ets
458@Entry
459@Component
460struct TextPickerExample {
461  private select: number = 1
462  private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4']
463
464  build() {
465    Column() {
466      TextPicker({ range: this.fruits, selected: this.select })
467        .onChange((value: string | string[], index: number | number[]) => {
468          console.info('Picker item changed, value: ' + value + ', index: ' + index)
469        })
470        .onScrollStop((value: string | string[], index: number | number[]) => {
471          console.info('Picker scroll stopped, value: ' + value + ', index: ' + index)
472        })
473        .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}})
474        .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}})
475        .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}})
476        .gradientHeight(100)
477    }.width('100%').height('100%')
478  }
479}
480```
481
482![textpicker](figures/textpicker4.gif)
483