1# TextPicker 2 3滑动选择文本内容的组件。 4 5> **说明：** 6> 7> 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 子组件 11 12无 13 14 15## 接口 16 17TextPicker(options?: TextPickerOptions) 18 19根据range指定的选择范围创建文本选择器。 20 21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------- | ----------------------------------------------- | ---- | ---------------------- | 29| options | [TextPickerOptions](#textpickeroptions对象说明) | 否 | 配置文本选择器的参数。 | 30 31## TextPickerOptions对象说明 32 33**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 34 35**系统能力：** SystemCapability.ArkUI.ArkUI.Full 36 37| 名称 | 类型 | 必填 | 说明 | 38| -------- | -------- | -------- | -------- | 39| range | string[] \| string[] []<sup>10+</sup> \| [Resource](ts-types.md#resource类型) \|<br/>[TextPickerRangeContent](#textpickerrangecontent10对象说明)[]<sup>10+</sup> \| [TextCascadePickerRangeContent](#textcascadepickerrangecontent10对象说明)[]<sup>10+</sup> | 是 | 选择器的数据选择列表。不可设置为空数组，若设置为空数组，则不显示；若动态变化为空数组，则保持当前正常值显示。<br/>**说明**：单列数据选择器使用string[]，Resource，TextPickerRangeContent[]类型。<br/>多列数据选择器使用string[][]类型。 <br/>多列联动数据选择器使用TextCascadePickerRangeContent[]类型。<br/>Resource类型只支持[strarray.json](../../../quick-start/resource-categories-and-access.md#资源组目录)。<br>range的类型及列数不可以动态修改。| 40| selected | number \| number[]<sup>10+</sup> | 否 | 设置默认选中项在数组中的索引值，索引从0开始。<br/>默认值：0 <br/>**说明**：单列数据选择器使用number类型。<br/>多列、多列联动数据选择器使用number[]类型。<br />从API version 10开始，该参数支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。| 41| value | string \| string[]<sup>10+</sup> | 否 | 设置默认选中项的值，优先级低于selected。<br/>默认值：第一个元素值<br/>**说明**：只有显示文本列表时该值有效。显示图片或图片加文本的列表时，该值无效。 <br/>单列数据选择器使用string类型。<br/>多列、多列联动数据选择器使用string[]类型。<br />从API version 10开始，该参数支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。| 42| columnWidths<sup>18+</sup> | LengthMetrics[] | 否 | 设置每一个选择项列宽。<br/>默认值：每一个选择项列宽相等<br/>**说明**：如果文本长度大于列宽时，文本被截断。 | 43 44## TextPickerRangeContent<sup>10+</sup>对象说明 45 46**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 47 48**系统能力：** SystemCapability.ArkUI.ArkUI.Full 49 50| 名称 | 类型 | 必填 | 说明 | 51| ---- | ---------------------------------------------------- | ---- | ---------- | 52| icon | string \| [Resource](ts-types.md#resource) | 是 | 图片资源。 icon是string类型时，表示图片存放的路径，例如"/common/hello.png"。 | 53| text | string \| [Resource](ts-types.md#resource) | 否 | 文本信息。<br/>默认值：空字符串<br/>**说明**：如果文本长度大于列宽时，文本被截断。 | 54 55## TextCascadePickerRangeContent<sup>10+</sup>对象说明 56 57**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 58 59**系统能力：** SystemCapability.ArkUI.ArkUI.Full 60 61| 名称 | 类型 | 必填 | 说明 | 62| ------ | -------------------------------------------------------- | ---- | ---------- | 63| text | string \| [Resource](ts-types.md#resource) | 是 | 文本信息。<br/>**说明**：如果文本长度大于列宽时，文本被截断。 | 64| children | [TextCascadePickerRangeContent](#textcascadepickerrangecontent10对象说明)[] | 否 | 联动数据。 | 65## DividerOptions<sup>12+</sup>对象说明 66 67**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 68 69**系统能力：** SystemCapability.ArkUI.ArkUI.Full 70 71| 名称 | 类型 | 必填 | 说明 | 72| ----------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 73| strokeWidth | [Dimension](ts-types.md#dimension10) | 否 | 分割线的线宽（默认单位vp），也可指定单位为px，不支持"百分比"类型。<br/>取值范围：strokeWidth小于0取默认值，最大不得超过列高的一半。<br/>默认值：2.0px | 74| startMargin | [Dimension](ts-types.md#dimension10) | 否 | 分割线与TextPicker侧边起始端的距离（默认单位vp），也可指定单位为px，不支持“百分比”类型。<br/>取值范围：startMargin小于0无效，最大不得超过TextPicker列宽。<br/>默认值：0 | 75| endMargin | [Dimension](ts-types.md#dimension10) | 否 | 分割线与TextPicker侧边结束端的距离（默认单位vp），也可指定单位为px，不支持“百分比”类型。<br/>取值范围：startMargin小于0无效，最大不得超过TextPicker列宽。<br/>默认值：0 | 76| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 分割线的颜色。<br/>默认值：'#33000000' 77 78## 属性 79 80除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 81 82### defaultPickerItemHeight 83 84defaultPickerItemHeight(value: number | string) 85 86设置Picker各选择项的高度。 87 88**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 89 90**系统能力：** SystemCapability.ArkUI.ArkUI.Full 91 92**参数：** 93 94| 参数名 | 类型 | 必填 | 说明 | 95| ------ | -------------------------- | ---- | ---------------------- | 96| value | number \| string | 是 | Picker各选择项的高度。number类型取值范围：[0, +∞)，string类型仅支持number类型取值的字符串形式，例如"56"。<br />默认值：选中项56vp，非选中项36vp。<br />**说明：**<br />设置该参数后，选中项与非选中项的高度均为所设置的值。 | 97 98### defaultPickerItemHeight<sup>18+</sup> 99 100defaultPickerItemHeight(height: Optional\<number | string>) 101 102设置Picker各选择项的高度。与[defaultPickerItemHeight](#defaultpickeritemheight)相比，height参数新增了对undefined类型的支持。 103 104**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 105 106**系统能力：** SystemCapability.ArkUI.ArkUI.Full 107 108**参数：** 109 110| 参数名 | 类型 | 必填 | 说明 | 111| ------ | -------------------------- | ---- | ---------------------- | 112| height | [Optional](ts-universal-attributes-custom-property.md#optional12)\<number \| string> | 是 | Picker各选择项的高度。number类型取值范围：[0, +∞)，string类型仅支持number类型取值的字符串形式，例如"56"。<br/>默认值：选中项56vp，非选中项36vp。<br />**说明：**<br />设置该参数后，选中项与非选中项的高度均为所设置的值。<br/>当height的值为undefined时，维持上次取值。 | 113 114### disappearTextStyle<sup>10+</sup> 115 116disappearTextStyle(value: PickerTextStyle) 117 118设置所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。 119 120**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 121 122**系统能力：** SystemCapability.ArkUI.ArkUI.Full 123 124**参数：** 125 126| 参数名 | 类型 | 必填 | 说明 | 127| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 128| value | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10类型说明) | 是 | 所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。<br/>默认值：<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 134设置所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。与[disappearTextStyle](#disappeartextstyle10)<sup>10+</sup>相比，style参数新增了对undefined类型的支持。 135 136**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 137 138**系统能力：** SystemCapability.ArkUI.ArkUI.Full 139 140**参数：** 141 142| 参数名 | 类型 | 必填 | 说明 | 143| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 144| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10类型说明)> | 是 | 所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。<br/>当style的值为undefined时，默认值：<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 150设置所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。 151 152**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 153 154**系统能力：** SystemCapability.ArkUI.ArkUI.Full 155 156**参数：** 157 158| 参数名 | 类型 | 必填 | 说明 | 159| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 160| value | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10类型说明) | 是 | 所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。<br/>默认值：<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 166设置所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。与[textStyle](#textstyle10)<sup>10+</sup>相比，style参数新增了对undefined类型的支持。 167 168**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 169 170**系统能力：** SystemCapability.ArkUI.ArkUI.Full 171 172**参数：** 173 174| 参数名 | 类型 | 必填 | 说明 | 175| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 176| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10类型说明)> | 是 | 所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。<br/>当style的值为undefined时，默认值：<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 182设置选中项的文本颜色、字号、字体粗细。 183 184**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 185 186**系统能力：** SystemCapability.ArkUI.ArkUI.Full 187 188**参数：** 189 190| 参数名 | 类型 | 必填 | 说明 | 191| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 192| value | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10类型说明) | 是 | 选中项的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff007dff',<br/>font: {<br/>size: '20fp', <br/>weight: FontWeight.Medium<br/>}<br/>} | 193 194### selectedTextStyle<sup>18+</sup> 195 196selectedTextStyle(style: Optional\<PickerTextStyle>) 197 198设置选中项的文本颜色、字号、字体粗细。与[selectedTextStyle](#selectedtextstyle10)<sup>10+</sup>相比，style参数新增了对undefined类型的支持。 199 200**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 201 202**系统能力：** SystemCapability.ArkUI.ArkUI.Full 203 204**参数：** 205 206| 参数名 | 类型 | 必填 | 说明 | 207| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 208| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10类型说明)> | 是 | 选中项的文本颜色、字号、字体粗细。<br/>当style的值为undefined时，默认值：<br/>{<br/>color: '#ff007dff',<br/>font: {<br/>size: '20fp', <br/>weight: FontWeight.Medium<br/>}<br/>} | 209 210### selectedIndex<sup>10+</sup> 211 212selectedIndex(value: number | number[]) 213 214设置默认选中项在数组中的索引值，优先级高于options中的选中值。单列数据选择器使用number类型。多列、多列联动数据选择器使用number[]类型。 215 216**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 217 218**系统能力：** SystemCapability.ArkUI.ArkUI.Full 219 220**参数：** 221 222| 参数名 | 类型 | 必填 | 说明 | 223| ------ | ---------------------------- | ---- | ---------------------------- | 224| value | number \| number[] | 是 | 默认选中项在数组中的索引值，索引从0开始。<br/>默认值：0 <br/>当value的值为undefined时，默认值与[options](#textpickeroptions对象说明)中的selected值保持一致，如果[options](#textpickeroptions对象说明)中的selected值为undefined，则默认值为0。<br/> | 225 226### selectedIndex<sup>18+</sup> 227 228selectedIndex(index: Optional\<number | number[]>) 229 230设置默认选中项在数组中的索引值，优先级高于options中的选中值。单列数据选择器使用number类型。多列、多列联动数据选择器使用number[]类型。与[selectedIndex](#selectedindex10)相比，index参数新增了对undefined类型的支持。 231 232**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 233 234**系统能力：** SystemCapability.ArkUI.ArkUI.Full 235 236**参数：** 237 238| 参数名 | 类型 | 必填 | 说明 | 239| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 240| index | [Optional](ts-universal-attributes-custom-property.md#optional12)\<number \| number[]> | 是 | 默认选中项在数组中的索引值，索引从0开始。<br/>默认值：0 <br/>当index的值为undefined时，默认值与[options](#textpickeroptions对象说明)中的selected值保持一致，如果[options](#textpickeroptions对象说明)中的selected值为undefined，则默认值为0。<br/> | 241 242### canLoop<sup>10+</sup> 243 244canLoop(value: boolean) 245 246设置是否可循环滚动。 247 248**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 249 250**系统能力：** SystemCapability.ArkUI.ArkUI.Full 251 252**参数：** 253 254| 参数名 | 类型 | 必填 | 说明 | 255| ------ | ------- | ---- | ------------------------------------------------------------ | 256| value | boolean | 是 | 是否可循环滚动。<br/>true：可循环，false：不可循环。<br/>默认值：true | 257 258### canLoop<sup>18+</sup> 259 260canLoop(isLoop: Optional\<boolean>) 261 262设置是否可循环滚动。与[canLoop](#canloop10)<sup>10+</sup>相比，isLoop参数新增了对undefined类型的支持。 263 264**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 265 266**系统能力：** SystemCapability.ArkUI.ArkUI.Full 267 268**参数：** 269 270| 参数名 | 类型 | 必填 | 说明 | 271| ------ | ------- | ---- | ------------------------------------------------------------ | 272| isLoop | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | 是 | 是否可循环滚动。<br/>true：可循环，false：不可循环。<br/>当isLoop的值为undefined时，默认值：true | 273 274### divider<sup>12+</sup> 275 276divider(value: DividerOptions | null) 277 278设置分割线样式，不设置该属性则按“默认值”展示分割线。 279 280startMargin + endMargin 超过组件宽度后startMargin和endMargin会被置0。 281 282**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 283 284**系统能力：** SystemCapability.ArkUI.ArkUI.Full 285 286**参数：** 287| 参数名 | 类型 | 必填 | 说明 | 288| ------ | ------- | ---- | --------------------------------------------------------------------- | 289| value | [DividerOptions](#divideroptions12对象说明) \| null | 是 | 1.设置DividerOptions，则按设置的样式显示分割线。<br/>默认值：<br/>{<br/>strokeWidth: '2px', <br/>startMargin: 0, <br/>endMargin: 0, <br/>color: '#33000000'<br/>}<br/>2.设置为null不显示分割线。 | 290 291### divider<sup>18+</sup> 292 293divider(textDivider: Optional\<DividerOptions | null>) 294 295设置分割线样式，不设置该属性则按“默认值”展示分割线。与[divider](#divider12)<sup>12+</sup>相比，textDivider参数新增了对undefined类型的支持。 296 297startMargin + endMargin 超过组件宽度后startMargin和endMargin会被置0。 298 299**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 300 301**系统能力：** SystemCapability.ArkUI.ArkUI.Full 302 303**参数：** 304 305| 参数名 | 类型 | 必填 | 说明 | 306| ------ | ------- | ---- | --------------------------------------------------------------------- | 307| textDivider | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[DividerOptions](#divideroptions12对象说明) \| null> | 是 | 1.设置DividerOptions，则按设置的样式显示分割线。<br/>当textDivider的值为undefined时，默认值：<br/>{<br/>strokeWidth: '2px', <br/>startMargin: 0, <br/>endMargin: 0, <br/>color: '#33000000'<br/>}<br/>2.设置为null不显示分割线。 | 308 309### gradientHeight<sup>12+</sup> 310 311gradientHeight(value: Dimension) 312 313设置渐隐效果高度，不设置该属性则显示默认渐隐效果。 314 315**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 316 317**系统能力：** SystemCapability.ArkUI.ArkUI.Full 318 319**参数：** 320 321| 参数名 | 类型 | 必填 | 说明 | 322| ------ | ------- | ---- | ------------------------------------------------------------ | 323| value | [Dimension](ts-types.md#dimension10) | 是 | 内容区上下边缘的渐隐高度（支持百分比，100%为TextPicker高度的一半即最大值），设置为0时不显示渐隐效果，负数等非法值显示默认渐隐效果。默认值为36vp。| 324 325### gradientHeight<sup>18+</sup> 326 327gradientHeight(height: Optional\<Dimension>) 328 329设置渐隐效果高度，不设置该属性则显示默认渐隐效果。与[gradientHeight](#gradientheight12)<sup>12+</sup>相比，height参数新增了对undefined类型的支持。 330 331**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 332 333**系统能力：** SystemCapability.ArkUI.ArkUI.Full 334 335**参数：** 336 337| 参数名 | 类型 | 必填 | 说明 | 338| ------ | ------- | ---- | ------------------------------------------------------------ | 339| height | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[Dimension](ts-types.md#dimension10)> | 是 | 内容区上下边缘的渐隐高度（支持百分比，100%为TextPicker高度的一半即最大值），设置为0时不显示渐隐效果，负数等非法值显示默认渐隐效果。默认值为36vp。<br/>当height的值为undefined时，默认值为36vp。 | 340 341> **说明：** 342> 343> 该组件不建议开发者在动效过程中修改属性数据。 344 345### disableTextStyleAnimation<sup>15+</sup> 346 347disableTextStyleAnimation(disabled: boolean) 348 349设置滑动过程中是否有文本样式变化动效。设置为true时，滑动过程中无字号、字重、字体颜色等变化动效，且文本均显示为[defaultTextStyle](#defaulttextstyle15)属性设置样式。如未设置defaultTextStyle，则显示为Text组件默认样式。 350 351**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 352 353**系统能力：** SystemCapability.ArkUI.ArkUI.Full 354 355**参数：** 356 357| 参数名 | 类型 | 必填 | 说明 | 358| ------ | ------- | ---- | ------------------------------------------------------------ | 359| disabled | boolean | 是 | 设置滑动过程中是否有文本样式变化动效。<br/>true：无文本样式变化动效，false：有文本样式变化动效。<br/>默认值：false | 360 361### defaultTextStyle<sup>15+</sup> 362 363defaultTextStyle(style: TextPickerTextStyle) 364 365设置关闭滑动过程中文本样式变化动效时，各个选项文本的样式。 366 367**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 368 369**系统能力：** SystemCapability.ArkUI.ArkUI.Full 370 371**参数：** 372 373| 参数名 | 类型 | 必填 | 说明 | 374| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 375| style | [TextPickerTextStyle](#textpickertextstyle15类型说明) | 是 | 设置关闭滑动过程中文本样式变化动效时的各个选项文本的样式，仅当disableTextStyleAnimation为true时生效。<br/>默认值：与[Text](ts-basic-components-text.md)组件默认值相同。 | 376 377> **说明：** 378> 379> 该组件不建议开发者在动效过程中修改属性数据。 380 381### enableHapticFeedback<sup>18+</sup> 382 383enableHapticFeedback(enable: Optional\<boolean>) 384 385设置是否开启触控反馈。 386 387**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 388 389**系统能力：** SystemCapability.ArkUI.ArkUI.Full 390 391| 参数名 | 类型 | 必填 | 说明 | 392| ------ | --------------------------------------------- |-----|-------------------------------------------------------------------------------------| 393| enable | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | 是 | 设置是否开启触控反馈。<br/>默认值：true，true表示开启触控反馈，false表示不开启触控反馈。| 394 395> **说明：** 396> 397> 开启触控反馈时，需要在工程的module.json5中配置requestPermissions字段开启振动权限，配置如下： 398> ```json 399> "requestPermissions": [ 400> { 401> "name": "ohos.permission.VIBRATE", 402> } 403> ] 404> ``` 405 406### digitalCrownSensitivity<sup>18+</sup> 407digitalCrownSensitivity(sensitivity: Optional\<CrownSensitivity>) 408 409设置表冠灵敏度。 410 411**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 412 413**系统能力：** SystemCapability.ArkUI.ArkUI.Full 414 415| 参数名 | 参数类型 | 必填 | 参数描述 | 416| ----- | ---------------------------------------- | ---- | ------------------------- | 417| sensitivity | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[CrownSensitivity](ts-appendix-enums.md#crownsensitivity18)> | 是 | 表冠灵敏度。 | 418 419> **说明：** 420> 421> 用于穿戴设备圆形屏幕使用。 422 423## 事件 424 425除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 426 427### onChange 428 429onChange(callback: (value: string \| string[], index: number \| number[]) => void) 430 431滑动选中TextPicker文本内容后，触发该回调。当显示文本或图片加文本列表时，value值为选中项中的文本值，当显示图片列表时，value值为空。 432 433**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 434 435**系统能力：** SystemCapability.ArkUI.ArkUI.Full 436 437**参数：** 438 439| 参数名 | 类型 | 必填 | 说明 | 440| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 441| value | string \| string[]<sup>10+</sup> | 是 | 当前选中项的文本。多列的情况，value为数组类型。 | 442| index | number \| number[]<sup>10+</sup> | 是 | 当前选中项的索引值，索引从0开始。多列的情况，index为数组类型。 | 443 444### onChange<sup>18+</sup> 445 446onChange(callback: Optional\<OnTextPickerChangeCallback>) 447 448滑动TextPicker文本内容后，选项归位至选中项位置时，触发该回调。与[onChange](#onchange)相比，callback参数新增了对undefined类型的支持。 449 450**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 451 452**系统能力：** SystemCapability.ArkUI.ArkUI.Full 453 454**参数：** 455 456| 参数名 | 类型 | 必填 | 说明 | 457| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 458| callback | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[OnTextPickerChangeCallback](#ontextpickerchangecallback18)> | 是 | 滑动选中TextPicker文本内容后，触发的回调。<br/>当callback的值为undefined时，不使用回调函数。 | 459 460### onScrollStop<sup>14+</sup> 461 462onScrollStop(callback: TextPickerScrollStopCallback) 463 464文本选择器的选项列滑动停止时触发该事件。 465 466手指拖动选项列触发的滑动，手指离开屏幕且滑动停止时会触发该事件。 467 468**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 469 470**系统能力：** SystemCapability.ArkUI.ArkUI.Full 471 472**参数：** 473 474| 参数名 | 类型 | 必填 | 说明 | 475| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 476| callback | [TextPickerScrollStopCallback](#textpickerscrollstopcallback14) | 是 | 文本选择器的选项列滑动停止时触发该事件。 | 477 478### onScrollStop<sup>18+</sup> 479 480onScrollStop(callback: Optional\<TextPickerScrollStopCallback>) 481 482文本选择器的选项列滑动停止时触发该事件。与[onScrollStop](#onscrollstop14)<sup>14+</sup>相比，callback参数新增了对undefined类型的支持。 483 484手指拖动选项列触发的滑动，手指离开屏幕且滑动停止时会触发该事件。 485 486**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 487 488**系统能力：** SystemCapability.ArkUI.ArkUI.Full 489 490**参数：** 491 492| 参数名 | 类型 | 必填 | 说明 | 493| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 494| callback | [TextPickerScrollStopCallback](#textpickerscrollstopcallback14) | 是 | 文本选择器的选项列滑动停止时触发该事件。<br/>当callback的值为undefined时，不使用回调函数。 | 495 496### onEnterSelectedArea<sup>18+</sup> 497 498onEnterSelectedArea(callback: TextPickerEnterSelectedAreaCallback) 499 500滑动TextPicker过程中，选项进入分割线区域内，触发该回调。 501 502与onChange事件的差别在于，该事件的触发时机早于onChange事件，当当前滑动列滑动距离超过选中项高度的一半时，选项此时已经进入分割线区域内，会触发该事件。 503 504当显示文本或图片加文本列表时，value值为选中项中的文本值，当显示图片列表时，value值为空。 505 506**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 507 508**系统能力：** SystemCapability.ArkUI.ArkUI.Full 509 510**参数：** 511 512| 参数名 | 类型 | 必填 | 说明 | 513| -------- | -------------------------- | ---- | ------------------------------------------ | 514| callback | [TextPickerEnterSelectedAreaCallback](#textpickerenterselectedareacallback18) | 是 | 滑动TextPicker过程中，选项进入分割线区域时触发的回调。 | 515 516### onAccept<sup>(deprecated) </sup> 517 518onAccept(callback: (value: string, index: number) => void) 519 520点击弹窗中的“确定”按钮时触发该回调。该事件仅在[文本滑动选择器弹窗](ts-methods-textpicker-dialog.md)中生效。 521 522从API version 10开始废弃。 523 524**系统能力：** SystemCapability.ArkUI.ArkUI.Full 525 526**参数：** 527 528| 参数名 | 类型 | 必填 | 说明 | 529| ------ | ------ | ---- | -------------------- | 530| value | string | 是 | 当前选中项的文本。 | 531| index | number | 是 | 当前选中项的索引值，索引从0开始。 | 532 533### onCancel<sup>(deprecated) </sup> 534 535onCancel(callback: () => void) 536 537点击弹窗中的“取消”按钮时触发该回调。该事件仅在[文本滑动选择器弹窗](ts-methods-textpicker-dialog.md)中生效。 538 539从API version 10开始废弃。 540 541**系统能力：** SystemCapability.ArkUI.ArkUI.Full 542 543## TextPickerTextStyle<sup>15+</sup>类型说明 544 545文本样式选项，继承自[PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10类型说明)。 546 547**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 548 549| 参数名 | 类型 | 必填 | 说明 | 550| ----- | ---------------------------------------- | ---- | ------------------------- | 551| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 文本颜色。 | 552| font | [Font](ts-types.md#font) | 否 | 文本样式。 | 553| minFontSize | number \| string \| [Resource](ts-types.md#resource) | 否 | 文本最小显示字号，与maxFontSize配合使用，当设置minFontSize与maxFontSize时，font中的size设置不生效，默认最大行数为1，默认自适应高度方式为MIN_FONT_SIZE_FIRST。 | 554| maxFontSize | number \| string \| [Resource](ts-types.md#resource) | 否 | 文本最大显示字号。 | 555| overflow | [TextOverflow](ts-appendix-enums.md#textoverflow) | 否 | 文本截断方式，设置为MARQUEE时不生效。 | 556 557## OnTextPickerChangeCallback<sup>18+</sup> 558 559type OnTextPickerChangeCallback = (value: string | string[], index: number | number[]) => void 560 561滑动选中TextPicker文本内容后，触发该回调。当显示文本或图片加文本列表时，value值为选中项中的文本值，当显示图片列表时，value值为空。 562 563**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 564 565**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 566 567**系统能力：** SystemCapability.ArkUI.ArkUI.Full 568 569**参数：** 570 571| 参数名 | 类型 | 必填 | 说明 | 572| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 573| value | string \| string[]<sup>10+</sup> | 是 | 当前选中项的文本。多列的情况，value为数组类型。 | 574| index | number \| number[]<sup>10+</sup> | 是 | 当前选中项的索引值，索引从0开始。多列的情况，index为数组类型。 | 575 576## TextPickerScrollStopCallback<sup>14+</sup> 577 578type TextPickerScrollStopCallback = (value: string | string[], index: number | number[]) => void 579 580文本选择器的选项列滑动停止时触发该事件。 581 582当显示文本或图片加文本列表时，value值为选中项中的文本值，当显示图片列表时，value值为空。 583 584**卡片能力：** 从API version 14开始，该接口支持在ArkTS卡片中使用。 585 586**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 587 588**系统能力：** SystemCapability.ArkUI.ArkUI.Full 589 590**参数：** 591 592| 参数名 | 类型 | 必填 | 说明 | 593| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 594| value | string \| string[] | 是 | 当前选中项的文本。多列的情况，value为数组类型。 | 595| index | number \| number[] | 是 | 当前选中项的索引值，索引从0开始。多列的情况，index为数组类型。 | 596 597## TextPickerEnterSelectedAreaCallback<sup>18+</sup> 598 599type TextPickerEnterSelectedAreaCallback = (value: string | string[], index: number | number[]) => void 600 601滑动过程中选项进入分割线区域内，触发该回调。 602 603在多列联动场景中，不建议使用该回调，由于该回调标识的是滑动过程中选项进入分割线区域内的节点，而跟随变化的选项并不涉及滑动，因此，回调的返回值中，仅当前滑动列的值会正常变化，其余未滑动列的值保持不变。 604 605**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 606 607**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 608 609**系统能力：** SystemCapability.ArkUI.ArkUI.Full 610 611**参数：** 612 613| 参数名 | 类型 | 必填 | 说明 | 614| ------ | ------------------------------------------ | ---- | ------------------------------------------------- | 615| value | string \| string[] | 是 | 当前选中项的文本。多列的情况，value为数组类型。 | 616| index | number \| number[] | 是 | 当前选中项的索引值，索引从0开始。多列的情况，index为数组类型。 | 617 618## 示例 619 620### 示例1（设置选择器列数） 621 622该示例通过配置range实现单列或多列文本选择器，通过配置columnWidths设置每一列宽度。 623 624```ts 625// xxx.ets 626import { LengthMetrics } from '@kit.ArkUI' 627class bottom { 628 bottom:number = 50 629} 630let bott:bottom = new bottom() 631@Entry 632@Component 633struct TextPickerExample { 634 private select: number = 1 635 private apfruits: string[] = ['apple1', 'apple2', 'apple3', 'apple4'] 636 private orfruits: string[] = ['orange1', 'orange2', 'orange3', 'orange4'] 637 private pefruits: string[] = ['peach1', 'peach2', 'peach3', 'peach4'] 638 private multi: string[][] = [this.apfruits, this.orfruits, this.pefruits] 639 private cascade: TextCascadePickerRangeContent[] = [ 640 { 641 text: '辽宁省', 642 children: [{ text: '沈阳市', children: [{ text: '沈河区' }, { text: '和平区' }, { text: '浑南区' }] }, 643 { text: '大连市', children: [{ text: '中山区' }, { text: '金州区' }, { text: '长海县' }] }] 644 }, 645 { 646 text: '吉林省', 647 children: [{ text: '长春市', children: [{ text: '南关区' }, { text: '宽城区' }, { text: '朝阳区' }] }, 648 { text: '四平市', children: [{ text: '铁西区' }, { text: '铁东区' }, { text: '梨树县' }] }] 649 }, 650 { 651 text: '黑龙江省', 652 children: [{ text: '哈尔滨市', children: [{ text: '道里区' }, { text: '道外区' }, { text: '南岗区' }] }, 653 { text: '牡丹江市', children: [{ text: '东安区' }, { text: '西安区' }, { text: '爱民区' }] }] 654 } 655 ] 656 private singleColumnWidths: LengthMetrics[] = [ 657 LengthMetrics.percent(50) 658 ] 659 660 private multipleColumnWidths: LengthMetrics[] = [ 661 LengthMetrics.vp(100), 662 LengthMetrics.vp(200), 663 LengthMetrics.vp(100) 664 ] 665 666 private cascadeColumnWidths: LengthMetrics[] = [ 667 LengthMetrics.percent(20), 668 LengthMetrics.percent(30), 669 LengthMetrics.percent(50) 670 ] 671 build() { 672 Column() { 673 674 TextPicker({ range: this.apfruits, selected: this.select, columnWidths: this.singleColumnWidths }) 675 .onChange((value: string | string[], index: number | number[]) => { 676 console.info('Picker item changed, value: ' + value + ', index: ' + index) 677 }) 678 .onScrollStop((value: string | string[], index: number | number[]) => { 679 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 680 }).margin(bott) 681 .onEnterSelectedArea((value: string | string[], index: number | number[]) => { 682 console.info('Picker item enter selected area, value: ' + value + ', index: ' + index) 683 }) 684 685 TextPicker({ range: this.multi, columnWidths: this.multipleColumnWidths }) 686 .onChange((value: string | string[], index: number | number[]) => { 687 console.info('TextPicker 多列:onChange ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 688 }) 689 .onScrollStop((value: string | string[], index: number | number[]) => { 690 console.info('TextPicker 多列:onScrollStop ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 691 }).margin(bott) 692 .onEnterSelectedArea((value: string | string[], index: number | number[]) => { 693 console.info('TextPicker 多列:onEnterSelectedArea ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 694 }) 695 696 TextPicker({ range: this.cascade, columnWidths: this.cascadeColumnWidths }) 697 .onChange((value: string | string[], index: number | number[]) => { 698 console.info('TextPicker 多列联动:onChange ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 699 }) 700 .onScrollStop((value: string | string[], index: number | number[]) => { 701 console.info('TextPicker 多列联动:onScrollStop ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 702 }) 703 .onEnterSelectedArea((value: string | string[], index: number | number[]) => { 704 console.info('TextPicker 多列联动:onEnterSelectedArea ' + JSON.stringify(value) + ', ' + 'index: ' + JSON.stringify(index)) 705 }) 706 } 707 } 708} 709``` 710 711 712 713### 示例2（设置文本样式） 714 715该示例通过配置disappearTextStyle、textStyle、selectedTextStyle实现文本选择器中的文本样式。 716 717```ts 718// xxx.ets 719@Entry 720@Component 721struct TextPickerExample { 722 private select: number = 1 723 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 724 725 build() { 726 Column() { 727 TextPicker({ 728 range: this.fruits, 729 selected: this.select, 730 value: this.fruits[this.select] 731 }) 732 .onChange((value: string | string[], index: number | number[]) => { 733 console.info('Picker item changed, value: ' + value + ', index: ' + index) 734 }) 735 .onScrollStop((value: string | string[], index: number | number[]) => { 736 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 737 }) 738 .disappearTextStyle({ color: Color.Red, font: { size: 15, weight: FontWeight.Lighter } }) 739 .textStyle({ color: Color.Black, font: { size: 20, weight: FontWeight.Normal } }) 740 .selectedTextStyle({ color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } }) 741 .defaultPickerItemHeight(50) 742 .canLoop(false) 743 .selectedIndex(2) 744 }.width('100%').height('100%') 745 } 746} 747``` 748 749 750 751### 示例3（设置无分割线样式） 752 753该示例通过配置divider为null实现无分割线样式的文本选择器。 754 755```ts 756// xxx.ets 757@Entry 758@Component 759struct TextPickerExample { 760 private select: number = 1 761 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 762 763 build() { 764 Column() { 765 TextPicker({ range: this.fruits, selected: this.select }) 766 .onChange((value: string | string[], index: number | number[]) => { 767 console.info('Picker item changed, value: ' + value + ', index: ' + index) 768 }) 769 .onScrollStop((value: string | string[], index: number | number[]) => { 770 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 771 }) 772 .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}) 773 .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}) 774 .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}) 775 .divider(null) 776 }.width('100%').height('100%') 777 } 778} 779``` 780 781 782### 示例4（设置分割线样式） 783 784该示例通过配置divider的DividerOptions类型实现分割线样式的文本选择器。 785 786```ts 787// xxx.ets 788@Entry 789@Component 790struct TextPickerExample { 791 private select: number = 1 792 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 793 794 build() { 795 Column() { 796 TextPicker({ range: this.fruits, selected: this.select }) 797 .onChange((value: string | string[], index: number | number[]) => { 798 console.info('Picker item changed, value: ' + value + ', index: ' + index) 799 }) 800 .onScrollStop((value: string | string[], index: number | number[]) => { 801 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 802 }) 803 .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}) 804 .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}) 805 .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}) 806 .divider({ 807 strokeWidth: 10, 808 color: Color.Red, 809 startMargin: 10, 810 endMargin: 20 811 } as DividerOptions) 812 }.width('100%').height('100%') 813 } 814} 815``` 816 817 818### 示例5（设置渐隐效果） 819 820该示例通过gradientHeight自定义TextPicker的渐隐效果高度。 821 822```ts 823// xxx.ets 824@Entry 825@Component 826struct TextPickerExample { 827 private select: number = 1 828 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 829 830 build() { 831 Column() { 832 TextPicker({ range: this.fruits, selected: this.select }) 833 .onChange((value: string | string[], index: number | number[]) => { 834 console.info('Picker item changed, value: ' + value + ', index: ' + index) 835 }) 836 .onScrollStop((value: string | string[], index: number | number[]) => { 837 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 838 }) 839 .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}) 840 .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}) 841 .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}) 842 .gradientHeight(100) 843 }.width('100%').height('100%') 844 } 845} 846``` 847 848 849 850### 示例6（设置选择项高度） 851 852该示例通过配置defaultPickerItemHeight设置选择项的高度。 853 854```ts 855// xxx.ets 856@Entry 857@Component 858struct TextPickerExample { 859 private select: number = 1 860 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 861 862 build() { 863 Column() { 864 TextPicker({ range: this.fruits, selected: this.select }) 865 .defaultPickerItemHeight(60) 866 .onChange((value: string | string[], index: number | number[]) => { 867 console.info('Picker item changed, value: ' + value + ', index: ' + index) 868 }) 869 .onScrollStop((value: string | string[], index: number | number[]) => { 870 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 871 }) 872 }.width('100%').height('100%') 873 } 874} 875``` 876 877 878 879 880### 示例7（设置循环滚动） 881 882该示例使用canLoop设置TextPicker是否循环滚动。 883 884```ts 885// xxx.ets 886@Entry 887@Component 888struct TextPickerExample { 889 @State isLoop: boolean = false 890 private select: number = 1 891 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 892 893 build() { 894 Column() { 895 TextPicker({ range: this.fruits, selected: this.select }) 896 .onChange((value: string | string[], index: number | number[]) => { 897 console.info('Picker item changed, value: ' + value + ', index: ' + index) 898 }) 899 .onScrollStop((value: string | string[], index: number | number[]) => { 900 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 901 }) 902 .canLoop(this.isLoop) 903 904 Row() { 905 Text('循环滚动').fontSize(20) 906 907 Toggle({ type: ToggleType.Switch, isOn: false }) 908 .onChange((isOn: boolean) => { 909 this.isLoop = isOn 910 }) 911 }.position({ x: '60%', y: '40%' }) 912 913 }.width('100%') 914 } 915} 916``` 917 918 919 920### 示例8（设置选中项索引值） 921 922该示例通过配置selectedIndex设置默认选中项的索引值。 923 924```ts 925// xxx.ets 926@Entry 927@Component 928struct TextPickerExample { 929 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4'] 930 931 build() { 932 Column() { 933 TextPicker({ range: this.fruits, selected: 1 }) 934 .selectedIndex(2) 935 .onChange((value: string | string[], index: number | number[]) => { 936 console.info('Picker item changed, value: ' + value + ', index: ' + index) 937 }) 938 .onScrollStop((value: string | string[], index: number | number[]) => { 939 console.info('Picker scroll stopped, value: ' + value + ', index: ' + index) 940 }) 941 }.width('100%').height('100%') 942 } 943} 944``` 945 946 947 948### 示例9（设置禁用文本样式变化动效与对应文本样式） 949 950该示例通过配置disableTextStyleAnimation、defaultTextStyle实现文本选择器禁用文本样式变化动效与此时的文本样式。 951 952```ts 953// xxx.ets 954@Entry 955@Component 956struct TextPickerExample { 957 private select: number = 1 958 private fruits: string[] = ['AAAAA', 'BBBBBBBBBBBBB', 'CCCC', 'DDDDDDDD', 'EEE'] 959 960 build() { 961 Column() { 962 TextPicker({ 963 range: this.fruits, 964 selected: this.select, 965 value: this.fruits[this.select] 966 }) 967 .disableTextStyleAnimation(true) 968 .margin({ bottom: 30 }) 969 TextPicker({ 970 range: this.fruits, 971 selected: this.select, 972 value: this.fruits[this.select] 973 }) 974 .disableTextStyleAnimation(true) 975 .defaultTextStyle({ minFontSize: 18, maxFontSize: 28, overflow: TextOverflow.Ellipsis }) 976 }.width('100%').height('100%') 977 } 978} 979``` 980 981 982
