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
263## Example
264
265```ts
266// xxx.ets
267class bottom {
268  bottom:number = 50
269}
270let bott:bottom = new bottom()
271@Entry
272@Component
273struct TextPickerExample {
274  private select: number = 1
275  private apfruits: string[] = ['apple1', 'apple2', 'apple3', 'apple4']
276  private orfruits: string[] = ['orange1', 'orange2', 'orange3', 'orange4']
277  private pefruits: string[] = ['peach1', 'peach2', 'peach3', 'peach4']
278  private multi: string[][] = [this.apfruits, this.orfruits, this.pefruits]
279  private cascade: TextCascadePickerRangeContent[] = [
280    {
281      text: 'Category 1',
282      children: [{ text: 'Subcategory 1', children: [{ text: 'Subcategory 2' }, { text: 'Subcategory 3' }, { text: 'Subcategory 4' }] },
283        { text: 'Item 1', children: [{ text: ''Item 2' }, { text: ''Item 3' }, { text: ''Item 4' }] }]
284    },
285    {
286      text: 'Category 2',
287      children: [{ text: 'Subcategory 1', children: [{ text: 'Subcategory 2' }, { text: 'Subcategory 3' }, { text: 'Subcategory 4' }] },
288        { text: 'Item 1', children: [{ text: ''Item 2' }, { text: ''Item 3' }, { text: ''Item 4' }] }]
289    },
290    {
291      text: 'Category 3',
292      children: [{ text: 'Subcategory 1', children: [{ text: 'Subcategory 2' }, { text: 'Subcategory 3' }, { text: 'Subcategory 4' }] },
293        { text: 'Item 1', children: [{ text: ''Item 2' }, { text: ''Item 3' }, { text: ''Item 4' }] }]
294    }
295  ]
296
297  build() {
298    Column() {
299
300      TextPicker({ range: this.apfruits, selected: this.select })
301        .onChange((value: string | string[], index: number | number[]) => {
302          console.info('Picker item changed, value: ' + value + ', index: ' + index)
303        }).margin(bott)
304
305      TextPicker({ range: this.multi })
306        .onChange((value: string | string[], index: number | number[]) => {
307          console.info('TextPicker multi-column: onChange' + JSON.stringify(value) + ',' + 'index:' + JSON.stringify(index))
308        }).margin(bott)
309
310      TextPicker({ range: this.cascade })
311        .onChange((value: string | string[], index: number | number[]) => {
312          console.info('TextPicker multi-column linkage: onChange' + JSON.stringify(value) + ',' + 'index:' + JSON.stringify(index))
313        })
314    }
315  }
316}
317```
318
319![textpicker](figures/textpicker.gif)
320
321```ts
322// xxx.ets
323@Entry
324@Component
325struct TextPickerExample {
326  private select: number = 1
327  private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4']
328
329  build() {
330    Column() {
331      TextPicker({ range: this.fruits, selected: this.select })
332        .onChange((value: string | string[], index: number | number[]) => {
333          console.info('Picker item changed, value: ' + value + ', index: ' + index)
334        })
335        .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}})
336        .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}})
337        .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}})
338    }.width('100%').height('100%')
339  }
340}
341```
342
343![textpicker](figures/textpicker1.gif)
344
345```ts
346// xxx.ets
347@Entry
348@Component
349struct TextPickerExample {
350  private select: number = 1
351  private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4']
352
353  build() {
354    Column() {
355      TextPicker({ range: this.fruits, selected: this.select })
356        .onChange((value: string | string[], index: number | number[]) => {
357          console.info('Picker item changed, value: ' + value + ', index: ' + index)
358        })
359        .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}})
360        .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}})
361        .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}})
362        .divider(null)
363    }.width('100%').height('100%')
364  }
365}
366```
367![textpicker](figures/textpicker2.gif)
368
369```ts
370// xxx.ets
371@Entry
372@Component
373struct TextPickerExample {
374  private select: number = 1
375  private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4']
376
377  build() {
378    Column() {
379      TextPicker({ range: this.fruits, selected: this.select })
380        .onChange((value: string | string[], index: number | number[]) => {
381          console.info('Picker item changed, value: ' + value + ', index: ' + index)
382        })
383        .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}})
384        .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}})
385        .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}})
386        .divider({
387          strokeWidth: 10,
388          color: Color.Red,
389          startMargin: 10,
390          endMargin: 20
391        } as DividerOptions)
392    }.width('100%').height('100%')
393  }
394}
395```
396![textpicker](figures/textpicker3.gif)
397```ts
398// xxx.ets. This example customizes the height the gradient effect for the text picker through gradientHeight().
399@Entry
400@Component
401struct TextPickerExample {
402  private select: number = 1
403  private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4']
404
405  build() {
406    Column() {
407      TextPicker({ range: this.fruits, selected: this.select })
408        .onChange((value: string | string[], index: number | number[]) => {
409          console.info('Picker item changed, value: ' + value + ', index: ' + index)
410        })
411        .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}})
412        .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}})
413        .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}})
414        .gradientHeight(100)
415    }.width('100%').height('100%')
416  }
417}
418```
419
420![textpicker](figures/textpicker4.gif)
421