鸿蒙ArkUI 文本滑动选择TextPicker的使用和简单解析

原创于 2025-06-02 21:55:48 发布 · 870 阅读

8 ·

CC 4.0 BY-SA版权

文章标签：

#鸿蒙 #ArkTs #ArkUI #移动端开发

引入

在移动端开发中，表单始终都是必要的环节，文本滑动选择器是不得不品的一环

鸿蒙ArkUI中同样为我们准备了对应的组件，让我们来简单的了解一下吧

如上图是一个简单的性别选择的滑动选择器，它的实现非常简单

@Entry
@Component
struct Index {
  genderList: string[] = ['男', '女', '未知']

  build() {
    Column() {
      TextPicker({range:this.genderList})
        .width('100%')
        .height(200)
        .canLoop(false)
        .backgroundColor('#ccc')
    }
    .width('100%')
    .height('100%')
  }
}

TextPicker 就是今天我们的主角

子组件

TextPicker

滑动选择文本内容的组件。

子组件

无

TextPicker无法作为容器使用，不能放入任何的子组件

接口

TextPicker仅有一个对象参数，它的类型是TextPickerOptions，让我们一起看下，它的参数都可以为TextPicker带来些什么神奇的效果吧

range：

string[] | string[] [] | Resource | TextPickerRangeContent[] | TextCascadePickerRangeContent[]

range是TextPicker的数据源，也是唯一一个必填的参数

他提供了很多种的类型可以填入，让我们分别来看下都是些什么

string[]

最简单的string数组，我们在开篇的时候看见的性别选择列表就是string

string[][]

string二维数组

多说无益，让我们先来看下效果

下面代码，我们将personList改为了二维数组

@Entry
@Component
struct Index {

  personList: string[][] = [['男', '女', '未知'],['未成年人','成年人']]

  build() {
    Column() {
      TextPicker({range:this.personList})
        .width('100%')
        .height(200)
        .canLoop(false)
        .backgroundColor('#ccc')
    }
    .width('100%')
    .height('100%')
  }
}

效果也是立竿见影，选择列变为了2行，分别对应数据中的性别，和年龄的一维数组

通过二位数组，甚至可以添加更多的行以供用户选择

Resource

Resource类型只支持strarray.json。

其实也就是string[]，只不过通过Resource提取出来了

TextPickerRangeContent[]

TextPickerRangeContent是一个对象，拥有两个属性

icon：string | Resource 和 text string | Resource

看到icon，相信大家都知道，没错它是可以给我们的选择中添加图片

 genderList:TextPickerRangeContent[]=[{
    text:'男',
    icon: $r('app.media.male')
  },{
    text:'女',
    icon: $r('app.media.female')
  }]

TextCascadePickerRangeContent[]

在多行联动的时候，除了二维string数组，我们还可以使用TextCascadePickerRangeContent[]

先来看下这个超长的对象是什么

const textContent = {
  text：'辽宁省',
  children:TextCascadePickerRangeContent[]：[{
       text：'沈阳市',
       children: [{ text: '沈河区',children:[] }, 
                  { text: '和平区',children:[] }, 
                  { text: '浑南区',children:[] }]
    },{
       text：'大连市',
       children:[]
    }
  ]
}

没错它是一个嵌套自身的对象，有点像递归对象版

看下它的实战效果吧

@Entry
@Component
struct Index {

  // genderList: string[][] = [['男', '女', '未知'],['未成年人','成年人']]
  iconList:TextPickerRangeContent[]=[{
    text:'男',
    icon: $r('app.media.male')
  },{
    text:'女',
    icon: $r('app.media.female')
  }]

  eastNorthList:TextCascadePickerRangeContent[]=[
    {
      text: '辽宁省',
      children: [{ text: '沈阳市', children: [{ text: '沈河区' }, { text: '和平区' }, { text: '浑南区' }] },
        { text: '大连市', children: [{ text: '中山区' }, { text: '金州区' }, { text: '长海县' }] }]
    },
    {
      text: '吉林省',
      children: [{ text: '长春市', children: [{ text: '南关区' }, { text: '宽城区' }, { text: '朝阳区' }] },
        { text: '四平市', children: [{ text: '铁西区' }, { text: '铁东区' }, { text: '梨树县' }] }]
    },
    {
      text: '黑龙江省',
      children: [{ text: '哈尔滨市', children: [{ text: '道里区' }, { text: '道外区' }, { text: '南岗区' }] },
        { text: '牡丹江市', children: [{ text: '东安区' }, { text: '西安区' }, { text: '爱民区' }] }]
    }
  ]

  build() {
    Column() {
      TextPicker({range:this.eastNorthList})
        .width('100%')
        .height(200)
        .canLoop(false)

    }
    .width('100%')
    .height('100%')
  }
}

这样，应该三项联动的省市区选择器就做好啦

selected： number | number[]

设置默认选中项在数组中的索引值，索引从0开始，默认0

同样支持$$双绑，用于获取当选选中的下标，拿到用户操作后的数据

value： string | string[]

设置默认选中项的值，优先级低于selected，同样支持双绑

属性

defaultPickerItemHeight

设置Picker各选择项的高度，默认值：选中项56vp，非选中项36vp。

下图为设置了100时候样式（真的丑）

disappearTextStyle

设置所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。

PickerTextStyle对象用于更改样式（选中样式不会因为disappearTextStyle改变）

TextPicker({range:this.eastNorthList})
        .width('100%')
        .selectedTextStyle({
          color: '#ff0000',
          font: {
            size: '18fp',
            weight: FontWeight.Bold
          }
        })

textStyle

设置所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。

selectedTextStyle

设置选中项的文本颜色、字号、字体粗细。

将刚才的代码改为selectedTextStyle吧

canLoop

设置是否可循环滚动。默认true

实际上循环的情况下很少而且很丑，所以一定要手动变为false哦

divider

设置分割线样式，不设置该属性则按“默认值”展示分割线。设置为null不显示分割线

gradientHeight

设置渐隐效果的高度。若未设置该属性，则显示默认渐隐效果。

其他的属性就不带大家一起看效果啦，感兴趣的朋友可以自己去试试哦

事件

onAccept

onAccept(callback: (value: string, index: number) => void)

点击弹窗中的“确定”按钮时触发该回调。该事件仅在文本滑动选择器弹窗中生效。

onCancel

点击弹窗中的“取消”按钮时触发该回调。该事件仅在文本滑动选择器弹窗中生效。

关于文本滑动选择器弹窗，会在之后给大家进行介绍

onChange

onChange(callback: (value: string | string[], index: number | number[]) => void)

滑动选中TextPicker文本内容后，触发该回调。当显示文本或图片加文本列表时，value值为选中项中的文本值，当显示图片列表时，value值为空。

onScrollStop

onScrollStop(callback: TextPickerScrollStopCallback)

文本选择器的选项列滑动停止时触发该事件。手指拖动选项列触发的滑动，手指离开屏幕且滑动停止时会触发该事件

TextPickerScrollStopCallback里面是index和value

onChange和onScrollStop的使用区别

onChange和onScrollStop尽管很相似，但是使用却并不相同，onScrollStop更适合获取用户具体的选择，而onChange则是监听改变的过程

TextPicker({range:this.genderList})
        .width('100%')
        .canLoop(false)
        .onChange((value, index)=>{
          console.log('onChange',value);
        })
        .onScrollStop((value, index)=>{
          console.log('onScrollStop',value);
        })