uview-plus

# Picker 选择器

此选择器用于单列，多列，多列联动的选择场景。

# 平台差异说明

App（vue） App（nvue） H5 小程序
√ √ √ √

# 基本使用

  • 通过show绑定一个布尔值变量，用于控制组件的弹出与收起。
  • 都通过传入数组columns配置选择项。
<template>
	<view>
		<up-picker :show="show" :columns="columns"></up-picker>
		<up-button @click="show = true">打开</up-button>
	</view>
</template>

<script setup>
import { ref, reactive } from 'vue';

const show = ref(false);
const columns = reactive([
  ['中国', '美国', '日本']
]);
</script>

<template>
	<view>
		<up-picker :show="show" :columns="columns"></up-picker>
		<up-button @click="show = true">打开</up-button>
	</view>
</template>

<script>
	export default {
		data() {
			return {
				show: false,
                columns: [
                    ['中国', '美国', '日本']
                ],
			}
		}
	}
</script>

# 多列模式与多列联动

此模式通过传入columns参数，此参数为二维数组，通过change事件完成联动操作。

<template>
    <up-picker :show="show" ref="uPickerRef" :columns="columns" @confirm="confirm" @change="changeHandler"></up-picker>
</template>

<script setup>
import { ref, reactive } from 'vue';

const show = ref(true);
const columns = reactive([
  ['中国', '美国'],
  ['深圳', '厦门', '上海', '拉萨']
]);
const columnData = reactive([
  ['深圳', '厦门', '上海', '拉萨'],
  ['得州', '华盛顿', '纽约', '阿拉斯加']
]);

const uPickerRef = ref(null)
const changeHandler = (e) => {
  const {
    columnIndex,
    value,
    values,
    index,
  } = e;

  if (columnIndex === 0) {
    uPickerRef.value.setColumnValues(1, columnData[index]);
  }
};

const confirm = (e) => {
  console.log('confirm', e);
  show.value = false;
};
</script>

<template>
    <up-picker :show="show" ref="uPickerRef" :columns="columns" @confirm="confirm" @change="changeHandler"></up-picker>
</template>

<script>
	export default {
		data() {
			return {
				show: true,
                columns: [
                    ['中国', '美国'],
                    ['深圳', '厦门', '上海', '拉萨']
				],
        columnData: [
            ['深圳', '厦门', '上海', '拉萨'],
            ['得州', '华盛顿', '纽约', '阿拉斯加']
        ]
			}
		},
		methods: {
      changeHandler(e) {
          const {
              columnIndex,
              value,
              values, // values为当前变化列的数组内容
              index
          } = e
          // 当第一列值发生变化时，变化第二列(后一列)对应的选项
          if (columnIndex === 0) {
              // picker为选择器this实例，变化第二列对应的选项
              this.$refs.uPickerRef.setColumnValues(1, this.columnData[index])
          }
      },
			// 回调参数为包含columnIndex、value、values
			confirm(e) {
        console.log('confirm', e)
        this.show = false
      }
		}
	}
</script>

# 加载状态

由于需要多列联动，此模式和上面的"多列模式"基本相同，在加载之前将loading设置为true，数据获取完成之后再置为false即可。

<template>
    <up-picker :show="show" ref="uPickerRef" :loading="loading" :columns="columns" @change="changeHandler"></up-picker>
</template>

<script setup>
import { ref, reactive } from 'vue';

const show = ref(true);
const loading = ref(false);
const columns = reactive([
  ['中国', '美国'],
  ['深圳', '厦门', '上海', '拉萨']
]);
const columnData = reactive([
  ['深圳', '厦门', '上海', '拉萨'],
  ['得州', '华盛顿', '纽约', '阿拉斯加']
]);

const uPickerRef = ref(null)
const changeHandler = (e) => {
  const {
    columnIndex,
    index,
    picker
  } = e;

  if (columnIndex === 0) {
    loading.value = true;
    // 模拟网络请求
    setTimeout(() => {
      uPickerRef.value.setColumnValues(1, columnData[index]);
      loading.value = false;
    }, 1500);
  }
};
</script>

<template>
    <up-picker :show="show" ref="uPicker" :loading="loading" :columns="columns" @change="changeHandler"></up-picker>
</template>

<script>
    export default {
        data() {
            return {
                show: true,
                loading: false,
                columns: [
                    ['中国', '美国'],
                    ['深圳', '厦门', '上海', '拉萨']
                ],
                columnData: [
                    ['深圳', '厦门', '上海', '拉萨'],
                    ['得州', '华盛顿', '纽约', '阿拉斯加']
                ]
            }
        },
        methods: {
            changeHandler(e) {
                const {
                    columnIndex,
                    index,
					// 微信小程序无法将picker实例传出来，只能通过ref操作
					picker = this.$refs.uPicker
                } = e
                if (columnIndex === 0) {
                    this.loading = true
                    // 模拟网络请求
                    uni.$u.sleep(1500).then(() => {
                        picker.setColumnValues(1, this.columnData[index])
                        this.loading = false
                    })
                }
            }
        }
    }
</script>

# 自定义选项值

参数columns可以传入自定义选项值，可以通过keyName参数控制对应的显示属性。

<template>
    <up-picker :show="show" :columns="columns" keyName="label"></up-picker>
</template>

<script setup>
import { ref, reactive } from 'vue';

const show = ref(true);
const columns = reactive([
  [
    {
      label: '雪月夜',
      // 其他属性值
      id: 2021
      // ...
    },
    {
      label: '冷夜雨',
      id: 804
    }
  ]
]);
</script>

<template>
    <up-picker :show="show" :columns="columns" keyName="label"></up-picker>
</template>

<script>
	export default {
		data() {
			return {
				show: true,
                columns: [
                    [{
                        label: '雪月夜',
                        // 其他属性值
                        id: 2021
                        // ...
                    }, {
                        label: '冷夜雨',
                        id: 804
                    }]
                ],
			}
		}
	}
</script>

# 默认值

此组件的所有模式，都可以设置默认值，通过defaultIndex数组参数配置，数组元素的0表示选中每列的哪个值(从0开始)，下面分别对几种模式进行说明：

注意： defaultIndex数组的长度，必须与列数相同，否则无效。

  1. 单列模式

如设置defaultIndex为[1]表示默认选中第2个(从0开始)，[5]表示选中第6个。

  1. 多列模式

如设置defaultIndex为[1, 3]表示第一列默认选中第2个，第二列默认选中第4个。


# 右侧演示页面源代码地址

点击以下链接以查看右侧演示页面的源码


 github  gitee

# API

# Props

参数 说明 类型 默认值 可选值
show 用于控制选择器的弹出与收起 Boolean false true
showToolbar 是否显示顶部的操作栏 Boolean true false
title 顶部中间的标题 String - -
columns 设置每一列的数据，见上方说明 Array - -
loading 加载状态 Boolean false true
itemHeight 各列中，单个选项的高度 String | Number 44 -
cancelText 取消按钮的文字 String 取消 -
confirmText 确认按钮的文字 String 确认 -
cancelColor 取消按钮的颜色 String #909193 -
confirmColor 确认按钮的颜色 String #3c9cff -
visibleItemCount 每列中可见选项的数量 String | Number 5 -
keyName 自定义需要展示的text属性键名 String text -
closeOnClickOverlay 是否允许点击遮罩关闭选择器（注意：关闭事件需要自行处理，只会在开启closeOnClickOverlay后点击遮罩层执行close回调） Boolean false true
defaultIndex 各列的默认索引 Array - -
immediateChange 2.0.22 是否在手指松开时立即触发change事件。若不开启则会在滚动动画结束后触发change事件，只在微信2.21.1及以上有效 Boolean true false

# Methods

名称 说明
setIndexs (index, setLastIndex) 设置对应列的选择值
setColumnValues 多列联动时需要用到，见上方说明，注意微信小程序的特殊用法

# Events

事件名 说明 回调参数 版本
close 关闭选择器时触发 - -
confirm 点击确定按钮，返回当前选择的值 Array: 见上方"回调参数"部分说明 -
change 当选择值变化时触发 Array: 见上方"回调参数"部分说明 -
cancel 点击取消按钮 - -

# Slots

名称 说明
toolbar-right 工具栏右侧内容，自定义右侧内容，因为微信小程序限制，需要同时设置:toolbarRightSlot="true"生效。
toolbar-bottom 输入框下方自定义区域

← DatetimePicker 选择器 →