Picker 选择器 | uView Next - 企业级、高质量、更贴近业务场景的 uniapp ui框架

# Picker 选择器

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

# 基本使用

通过show绑定一个布尔值变量，用于控制组件的弹出与收起。
通过传入数组columns配置选择项。

<template>
	<view>
		<un-picker :show="show" :columns="columns" @close="show = false" @confirm="onConfirm" />
		<un-button @click="show = true">打开</un-button>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import type { UnPickerColumn, UnPickerConfirmEvent } from '@/uni_modules/uview-unix/components/un-picker'

const show = ref(false)
const columns = ref<UnPickerColumn[]>([
    [
        { text: '中国', value: 1 },
        { text: '美国', value: 2 },
        { text: '日本', value: 3 }
    ]
])

const onConfirm = (e: UnPickerConfirmEvent) => {
    console.log('确认选择:', e.value)
}
</script>
✅ Copy success!

# 设置默认值

通过show绑定一个布尔值变量，用于控制组件的弹出与收起。
通过传入数组columns配置选择项。
通过v-model/modelValue设置默认值。

<template>
	<view>
		<un-picker :show="show" v-model="value" :columns="columns" @close="show = false" @confirm="onConfirm" />
		<un-button @click="show = true">打开</un-button>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import type { UnPickerColumn, UnPickerConfirmEvent } from '@/uni_modules/uview-unix/components/un-picker'

const show = ref(false)
const value = ref<number>(2) // 默认选中美国（value为2）
const columns = ref<UnPickerColumn[]>([
    [
        { text: '中国', value: 1 },
        { text: '美国', value: 2 },
        { text: '日本', value: 3 }
    ]
])

const onConfirm = (e: UnPickerConfirmEvent) => {
    console.log('确认选择:', e.value)
}
</script>
✅ Copy success!

# 使用触发器

无需通过show变量控制弹出层的打开和收起

<template>
	<view>
		<un-picker :columns="columns" closeOnClickOverlay @confirm="onConfirm">
			<template #trigger>
				<un-input :value="value" placeholder="请选择国家" disabled-color="#fff" disabled clearable />
			</template>
		</un-picker>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import type { UnPickerColumn, UnPickerConfirmEvent } from '@/uni_modules/uview-unix/components/un-picker'

const value = ref<string>('')
const columns = ref<UnPickerColumn[]>([
    [
        { text: '中国', value: 1 },
        { text: '美国', value: 2 },
        { text: '日本', value: 3 }
    ]
])

const onConfirm = (e: UnPickerConfirmEvent) => {
    if (e.value.length > 0) {
        value.value = e.value[0].text || ''
    }
}
</script>
✅ Copy success!

# 多列模式与多列联动

通过columns传入二维数组，实现多列选择器。
通过@change事件监听列变化，实现多列联动。

<template>
	<view>
		<un-picker :show="show" :columns="columns" @change="onChange" @confirm="onConfirm" @close="show = false" />
		<un-button @click="show = true">打开</un-button>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import type { UnPickerColumn, UnPickerChangeEvent, UnPickerConfirmEvent } from '@/uni_modules/uview-unix/components/un-picker'

const show = ref(false)

// 城市数据
const cityData = {
    '中国': ['深圳', '广州', '杭州', '北京', '上海', '重庆'],
    '美国': ['纽约', '洛杉矶', '芝加哥', '休斯顿', '费城']
}

const columns = ref<UnPickerColumn[]>([
    [
        { text: '中国', value: '中国' },
        { text: '美国', value: '美国' }
    ],
    [
        { text: '深圳', value: '深圳' },
        { text: '广州', value: '广州' },
        { text: '杭州', value: '杭州' },
        { text: '北京', value: '北京' },
        { text: '上海', value: '上海' },
        { text: '重庆', value: '重庆' }
    ]
])

const onChange = (e: UnPickerChangeEvent) => {
    const { columnIndex, value } = e
    
    // 当第一列值发生变化时，动态改变第二列的数据
    if (columnIndex == 0 && value != null) {
        const selectedCountry = value.text || ''
        const cities = cityData[selectedCountry] || []
        
        // 更新第二列数据
        columns.value[1] = cities.map(city => ({ text: city, value: city }))
    }
}

const onConfirm = (e: UnPickerConfirmEvent) => {
    console.log('确认选择:', e.value)
}
</script>
✅ Copy success!

# 加载状态

通过loading属性设置加载状态。

<template>
	<view>
		<un-picker :show="show" :columns="columns" loading @close="show = false" @confirm="onConfirm" />
		<un-button @click="show = true">打开</un-button>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import type { UnPickerColumn, UnPickerConfirmEvent } from '@/uni_modules/uview-unix/components/un-picker'

const show = ref(false)
const columns = ref<UnPickerColumn[]>([
    [
        { text: '中国', value: 1 },
        { text: '美国', value: 2 },
        { text: '日本', value: 3 }
    ]
])

const onConfirm = (e: UnPickerConfirmEvent) => {
    console.log('确认选择:', e.value)
}
</script>
✅ Copy success!

# 默认值

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

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

单列模式

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

多列模式

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

# API

# Props

参数	说明	类型	默认值	可选值
v-model / modeValue	当前选中项对应的值	Array	-	-
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	-
closeOnClickOverlay	是否允许点击遮罩关闭选择器（注意：关闭事件需要自行处理，只会在开启closeOnClickOverlay后点击遮罩层执行close回调）	Boolean	true	false
defaultIndex	各列的默认索引	Array	-	-
immediateChange	是否在手指松开时立即触发`change`事件。若不开启则会在滚动动画结束后触发`change`事件，只在微信`2.21.1`及以上有效	Boolean	false	true
round	圆角值，默认无圆角	String \| Number	0	-

# Methods

名称	说明
setIndexs	(index, setLastIndex) 设置对应列的选择值
setColumnValues	多列联动时需要用到

# Events

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

# Slot

名称	说明
trigger	自定义触发
default	自定义触发

# 类型定义

# UnPickerColumn

选择器列数据类型定义，用于columns属性：

type UnPickerColumn = UnPickerColumnItem[]
✅ Copy success!

# UnPickerColumnItem

选择器选项项数据类型定义：

type UnPickerColumnItem = {
    text: string           // 显示文本
    value: string | number             // 选项值
    disabled?: boolean     // 是否禁用（可选）
    children?: UnPickerColumnItem[] // 子选项（用于级联选择）（可选）
}
✅ Copy success!

# UnPickerValue

选择器返回值类型定义：

type UnPickerValue = string | number | Array<string | number>
✅ Copy success!

# UnPickerChangeEvent

选择器变化事件类型定义：

type UnPickerChangeEvent = {
    index: number // 当前列的选中索引
    indexs: number[] // 各列的选中索引
    columnIndex: number // 当前列索引
    values: UnPickerColumn[] // 各列的选中项数组
    value: UnPickerColumnItem[] // 各列的选中项
}
✅ Copy success!

# UnPickerConfirmEvent

选择器确认事件类型定义：

type UnPickerConfirmEvent = {
    indexs: number[] // 各列的选中索引
    value: UnPickerColumnItem[] // 各列的选中项
    values: UnPickerColumn[] // 各列的选中项数组
}
✅ Copy success!

← Cascader 级联选择器 AreaPicker 地区选择器 →