uView Next
4.0.105

外观

Picker 选择器

约 1665 字大约 6 分钟

2025-10-31

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

基本使用

  • 通过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'

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>

设置默认值

  • 通过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'

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>

使用触发器

  • 无需通过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'

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>

多列模式与多列联动

  • 通过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'

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>

加载状态

  • 通过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'

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>

默认值

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

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

  1. 单列模式

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

  1. 多列模式

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


API

Props

参数说明类型默认值
v-model \ modelValue当前选中项对应的值UnPickerValue-
show是否展示picker弹窗booleanfalse
showToolbar是否显示顶部的操作栏booleantrue
title顶部标题string-
columns对象数组，设置每一列的数据UnPickerColumn[]-
loading是否显示加载中状态booleanfalse
itemHeight各列中，单个选项的高度string | number44
cancelText取消按钮的文字string取消
confirmText确认按钮的文字string确认
cancelColor取消按钮的颜色string#909193
confirmColor确认按钮的颜色string#3c9cff
visibleItemCount每列中可见选项的数量string | number5
closeOnClickOverlay是否允许点击遮罩关闭选择器booleantrue
defaultIndex各列的默认索引number[]-
immediateChange是否在手指松开时立即触发change事件booleanfalse
round设置圆角值string | number0

Methods

名称说明类型
getIndexs获取各列选中值对应的索引
Function
getValues获取各列选中的值
Function
getColumns获取整体各列的columns的值
Function
getColumnValues获取对应列的所有选项
Function
setColumnValues设置对应列选项的所有值
Function

Events

事件名说明类型
close关闭选择器时触发
Function
open打开选择器时触发
Function
confirm点击确定按钮，返回当前选择的值
Function
change当选择值变化时触发
Function
cancel点击取消按钮
Function
update:modelValue当选择值变化时更新v-model绑定的值
Function

Slot

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

类型定义

UnPickerColumn

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

type UnPickerColumn = UnPickerColumnItem[]

UnPickerColumnItem

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

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

UnPickerValue

选择器返回值类型定义：

type UnPickerValue = string | number | Array<string | number>

UnPickerChangeEvent

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

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

UnPickerConfirmEvent

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

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

Scss 变量

变量名默认值说明
$un-picker-item-z-index10选择器选项的z-index层级
$un-picker-item-text-font-size16px选择器选项文字大小
$un-picker-item-text-color$text-color选择器选项文字颜色
$un-picker-item-disabled-opacity0.35选择器禁用选项的透明度
$un-picker-loading-bg-colorrgba(255, 255, 255, 0.87)选择器加载状态背景颜色
$un-picker-loading-z-index1000选择器加载状态的z-index层级

提示

组件内部默认使用 scss 变量，如需修改，请查看 scss 变量使用 文档

Copyright © 2026 uView Next