选择器组件

picker 是一个从底部弹出的滚动选择器，用于让用户在预设的选项中做出选择。它支持多种模式，通过 mode 属性来区分，包括普通选择器、多列选择器、时间选择器、日期选择器和省市区选择器。默认模式为普通选择器。

1. 什么是 picker 组件？

picker 组件用于从底部弹出一个滚动选择器供用户选择内容。支持的模式包括：

• 普通选择器：单列选择。
• 多列选择器：可以选择多列的内容。
• 时间选择器：选择时间。
• 日期选择器：选择日期。
• 省市区选择器：选择地区。

使用场景

• 选择时间、日期：如预订、日程安排等场景下选择具体的时间或日期。
• 选择地区：选择省市区用于地址输入等场景。
• 选择普通列表项：如选择性别、职业等单列数据。

2. picker 组件的常用属性

2.1 普通选择器

• mode="selector" 普通单列选择器，用户从单列数据中选择一项。

属性名	类型	默认值	说明
range	Array	[]	提供给用户选择的选项列表，数组格式
range-key	String		当 range 为 Array<Object> 时，指定对象中显示内容的 key
value	Number	0	当前选择的索引值（从 0 开始计数）
disabled	Boolean	false	是否禁用选择器
@change	Event		选项改变时触发，返回当前选择的索引值
@cancel	Event		用户取消选择时触发

<template>
  <view>
    <picker :range="['选项一', '选项二', '选项三']" @change="onPickerChange">
      <view class="picker">当前选择: {{ selectedValue }}</view>
    </picker>
  </view>
</template>

<script setup>
const selectedValue = ref('选项一');

const onPickerChange = (e) => {
  const index = e.detail.value;
  selectedValue.value = ['选项一', '选项二', '选项三'][index];
};
</script>

2.2 多列选择器

• mode="multiSelector" 支持多列数据选择，用户可以从每一列选择一项。

属性名	类型	默认值	说明
range	Array	[]	提供给用户选择的多列数据，二维数组
range-key	String		当 range 为 Array<Object> 时，指定对象中显示内容的 key
value	Array	[]	当前选择的索引值，数组格式，每列对应一个索引
@change	Event		选项改变时触发，返回当前选择的索引值
@columnchange	Event		列改变时触发，返回改变的列索引及新的选项索引
@cancel	Event		用户取消选择时触发

<template>
  <view>
    <picker mode="multiSelector" :range="multiArray" :value="multiIndex" @change="onMultiChange" @columnchange="onColumnChange">
      <view class="picker">当前选择: {{ multiArray[0][multiIndex[0]] }} - {{ multiArray[1][multiIndex[1]] }}</view>
    </picker>
  </view>
</template>

<script setup>
const multiArray = ref([['类别1', '类别2'], ['选项A', '选项B']]);
const multiIndex = ref([0, 0]);

const onMultiChange = (e) => {
  const indexes = e.detail.value;
  multiIndex.value = indexes;
};

const onColumnChange = (e) => {
  const column = e.detail.column;
  const value = e.detail.value;
  console.log(`第${column}列选择了第${value}项`);
};
</script>

2.3 时间选择器

• mode="time" 用于选择时间（格式：hh:mm）。

属性名	类型	默认值	说明
value	String		当前选中的时间，格式为 hh:mm
start	String		有效时间范围的开始，格式为 hh:mm
end	String		有效时间范围的结束，格式为 hh:mm
@change	Event		时间改变时触发，返回选中的时间
@cancel	Event		用户取消选择时触发

<template>
  <view>
    <picker mode="time" :value="time" start="09:00" end="18:00" @change="onTimeChange">
      <view class="picker">当前时间: {{ time }}</view>
    </picker>
  </view>
</template>

<script setup>
const time = ref('12:00');

const onTimeChange = (e) => {
  time.value = e.detail.value;
};
</script>

2.4 日期选择器

• mode="date" 用于选择日期（格式：YYYY-MM-DD）。

属性名	类型	默认值	说明
value	String		当前选中的日期，格式为 YYYY-MM-DD
start	String		有效日期范围的开始，格式为 YYYY-MM-DD
end	String		有效日期范围的结束，格式为 YYYY-MM-DD
@change	Event		日期改变时触发，返回选中的日期
@cancel	Event		用户取消选择时触发

<template>
  <view>
    <picker mode="date" :value="date" start="2020-01-01" end="2030-01-01" @change="onDateChange">
      <view class="picker">当前日期: {{ date }}</view>
    </picker>
  </view>
</template>

<script setup>
const date = ref('2023-01-01');

const onDateChange = (e) => {
  date.value = e.detail.value;
};
</script>

2.5 省市区选择器

• mode="region" 用于选择省市区。

属性名	类型	默认值	说明
value	Array	[]	当前选中的省市区
@change	Event		省市区改变时触发，返回选中的省市区
@cancel	Event		用户取消选择时触发

<template>
  <view>
    <picker mode="region" :value="region" @change="onRegionChange">
      <view class="picker">当前选择: {{ region.join(' - ') }}</view>
    </picker>
  </view>
</template>

<script setup>
const region = ref(['广东省', '广州市', '天河区']);

const onRegionChange = (e) => {
  region.value = e.detail.value;
};
</script>

3. 平台差异与注意事项

• 平台差异：不同平台的 picker 组件 UI 表现不同，如 App 和 H5 端默认调用原生选择器，而在小程序中是自定义的界面。
• 注意事项：
  • picker 内容滚动时立即点击“确定”按钮，数据可能无法及时更新，建议等待滚动结束再确定。
  • 小程序的 multiSelector 支持多列选择，支付宝小程序不支持，需使用 picker-view 组件代替。

4. 扩展与优化

4.1 动态数据加载

当需要动态加载选择项（如省市区选择时逐级加载市和区数据），可以通过监听 @columnchange 事件并动态更新 range 的内容。

4.2 使用增强版 Picker

uni-ui 提供了增强版的 <uni-data-picker> 组件，支持更多列、数据懒加载和更复杂的表单场景，适合复杂选择需求。

5. 选择器组件总结

picker 组件通过提供多种选择模式（如单列、多列、时间、日期、地区等），极大地方便了用户选择输入。开发者可以根据不同的业务需求灵活选择和配置 picker 的各个模式和属性来满足具体的应用场景。

5.1 组件常见模式对比

模式	说明	使用场景
selector	普通单列选择器	选择性别、职业等单项选择
multiSelector	多列选择器	选择多列相关数据，如日期
time	时间选择器	选择特定时间点
date	日期选择器	选择日期
region	省市区选择器	地址选择

5.2 完整使用案例

<template>
  <view>
    <picker mode="date" :value="date" start="2020-01-01" end="2030-01-01" @change="onDateChange">
      <view class="picker">当前日期: {{ date }}</view>
    </picker>

    <picker mode="time" :value="time" start="09:00" end="18:00" @change="onTimeChange">
      <view class="picker">当前时间: {{ time }}</view>
    </picker>

    <picker mode="region" :value="region" @change="onRegionChange">
      <view class="picker">当前选择: {{ region.join(' - ') }}</view>
    </picker>
  </view>
</template>

<script setup>
const date = ref('2023-01-01');
const time = ref('12:00');
const region = ref(['广东省', '广州市', '天河区']);

const onDateChange = (e) => {
  date.value = e.detail.value;
};

const onTimeChange = (e) => {
  time.value = e.detail.value;
};

const onRegionChange = (e) => {
  region.value = e.detail.value;
};
</script>