Picker 选择器

约 1896 字大约 6 分钟

2025-10-31

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

基本使用

单列选择

通过 show 绑定布尔值变量控制组件的弹出与收起，通过 columns 配置选择项：

<template>
    <un-button type="primary" @click="handleClick" text="打开"></un-button>

    <un-picker 
        :show="showPicker" 
        :columns="columns"
        @change="change" 
        @close="close"
        @cancel="cancel"
        @confirm="confirm" 
    />
</template>

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

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

const showPicker = ref<boolean>(false);

const handleClick = () => {
    showPicker.value = true
}

const change = (event: UnPickerChangeEvent) => {
    console.log('change', event);
};

const close = () => {
    showPicker.value = false
}

const cancel = () => {
    close()
}

const confirm = (event: UnPickerConfirmEvent) => {

    //由于event.value单列是UnPickerColumnItem，多列是为UnPickerColumnItem数组，所以需要自行转换数据类型
    // const value = event.value as UnPickerColumnItem
    // console.log(value.text)

    console.log('confirm', event);
    close()
}
</script>

设置默认项 - 单列

通过 defaultIndex 设置默认选中项：

<template>
    <un-button type="primary" @click="handleClick" text="打开"></un-button>

    <un-picker 
        :show="showPicker" 
        :columns="columns"
        :defaultIndex="defaultIndex" 
        @change="change" 
        @close="close"
        @cancel="cancel"
        @confirm="confirm" 
    />
</template>

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

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

const defaultIndex = ref<number>(0);
const showPicker = ref<boolean>(false);

const handleClick = () => {
    defaultIndex.value = 1
    showPicker.value = true
}

const change = (event: UnPickerChangeEvent) => {
    console.log('change', event);
};

const close = () => {
    showPicker.value = false
}

const cancel = () => {
    close()
}

const confirm = (event: UnPickerConfirmEvent) => {
    console.log('confirm', event);
    close()
}
</script>

设置默认值 - 单列

通过 v-model 设置默认值：

<template>
    <un-button type="primary" @click="handleClick" text="打开"></un-button>

    <un-picker
        v-model="defaultValue"
        :show="showPicker" 
        :columns="columns"
        @change="change" 
        @close="close"
        @cancel="cancel"
        @confirm="confirm" 
    />

</template>

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

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

const defaultValue = ref<number>(0);
const showPicker = ref<boolean>(false);

const handleClick = () => {
    defaultValue.value = 3
    showPicker.value = true
}

const change = (event: UnPickerChangeEvent) => {
    console.log('change', event);
};

const close = () => {
    showPicker.value = false
}

const cancel = () => {
    close()
}

const confirm = (e: UnPickerConfirmEvent) => {
    console.log('confirm', e);
    close()
}
</script>

多列选择

通过 columns 传入二维数组实现多列选择：

<template>
    <un-button type="primary" @click="handleClick" text="打开"></un-button>

    <un-picker 
        :show="showPicker" 
        :columns="columns" 
        @change="change" 
        @close="close"
        @cancel="cancel"
        @confirm="confirm" 
    />
</template>

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

const columns = ref<UnPickerColumn[]>([
    [
        { text: '早餐', value: 1 },
        { text: '午餐', value: 2 },
        { text: '晚餐', value: 3 }
    ],
    [
        { text: '米饭', value: 1 },
        { text: '面条', value: 2 },
        { text: '面包', value: 3 },
        { text: '沙拉', value: 4 }
    ]
]);

const showPicker = ref<boolean>(false);

const handleClick = () => {
    showPicker.value = true
}

const change = (event: UnPickerChangeEvent) => {
    console.log('change', event);
};

const close = () => {
    showPicker.value = false
}

const cancel = () => {
    close()
}

const confirm = (event: UnPickerConfirmEvent) => {

    //由于event.value单列是UnPickerColumnItem，多列是为UnPickerColumnItem数组，所以需要自行转换数据类型
    // const value = event.value as UnPickerColumnItem[]
    // value.forEach(item => {
    //     console.log(item)
    // })

    console.log('confirm', event);
    close()
}
</script>

设置默认项 - 多列

通过 defaultIndex 数组设置多列默认选中项：

<template>
    <un-button type="primary" @click="handleClick" text="打开"></un-button>

    <un-picker 
        :show="showPicker" 
        :columns="columns" 
        :defaultIndex="defaultIndex" 
        @change="change" 
        @close="close"
        @cancel="cancel"
        @confirm="confirm" 
    />
   
</template>

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

const columns = ref<UnPickerColumn[]>([
    [
        { text: '早餐', value: 1 },
        { text: '午餐', value: 2 },
        { text: '晚餐', value: 3 }
    ],
    [
        { text: '米饭', value: 1 },
        { text: '面条', value: 2 },
        { text: '面包', value: 3 },
        { text: '沙拉', value: 4 }
    ]
]);

const defaultIndex = ref<number[]>([0,0]);
const showPicker = ref<boolean>(false);

const handleClick = () => {
    defaultIndex.value = [1,1]
    showPicker.value = true
}

const change = (event: UnPickerChangeEvent) => {
    console.log('change', event);
};

const close = () => {
    showPicker.value = false
}

const cancel = () => {
    close()
}

const confirm = (event: UnPickerConfirmEvent) => {
    console.log('confirm', event);
    close()
}
</script>

设置默认值 - 多列

通过 v-model 设置默认值：

<template>
    <un-button type="primary" @click="handleClick" text="打开"></un-button>

    <un-picker
        v-model="defaultValue"
        :show="showPicker" 
        :columns="columns"
        @change="change" 
        @close="close"
        @cancel="cancel"
        @confirm="confirm" 
    />

</template>

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

const columns = ref<UnPickerColumn[]>([
    [
        { text: '早餐', value: 1 },
        { text: '午餐', value: 2 },
        { text: '晚餐', value: 3 }
    ],
    [
        { text: '米饭', value: 1 },
        { text: '面条', value: 2 },
        { text: '面包', value: 3 },
        { text: '沙拉', value: 4 }
    ]
]);

const defaultValue = ref<number[]>([0,0]);
const showPicker = ref<boolean>(false);

const handleClick = () => {
    defaultValue.value = [1,3]
    showPicker.value = true
}

const change = (event: UnPickerChangeEvent) => {
    console.log('change', event);
};

const close = () => {
    showPicker.value = false
}

const cancel = () => {
    close()
}

const confirm = (event: UnPickerConfirmEvent) => {
    console.log('confirm', event);
    close()
}
</script>

加载中状态

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

<template>
    <un-button type="primary" @click="handleClick" text="打开"></un-button>
    <un-picker 
        :show="showPicker" 
        :columns="columns" 
        :loading="loading" 
        @change="change" 
        @close="close"
        @cancel="cancel"
        @confirm="confirm" 
    />
    
</template>

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

const columns = ref<UnPickerColumn | null>(null);
const loading = ref<boolean>(false);
const showPicker = ref<boolean>(false);

// 加载中状态
const pickerLoading = () => {
    loading.value = true
    showPicker.value = true
    setTimeout(() => {
        columns.value = [
            { text: '中国', value: 1 },
            { text: '美国', value: 2 },
            { text: '日本', value: 3 }
        ] as UnPickerColumn
        loading.value = false
    }, 1500);
}

const change = (event: UnPickerChangeEvent) => {
    console.log('change', event);
};

const close = () => {
    showPicker.value = false
}

const cancel = () => {
    close()
}

const confirm = (event: UnPickerConfirmEvent) => {
    console.log('confirm', event);
    close()
}
</script>

使用触发器

通过 showInput 属性显示输入框作为触发器，也可以使用默认插槽自定义触发器：

<template>
    <un-picker v-model="defaultValue" :columns="columns" showInput></un-picker>
   
    <un-picker v-model="defaultValue" :columns="columns">
        <un-input :value="defaultValue" placeholder="请选择" />
    </un-picker>
</template>

<script setup lang="uts">
import { ref } from 'vue';
import type { UnPickerColumn } from '@/uni_modules/uview-unix';

const columns2 = ref<UnPickerColumn[]>([
    [
        { text: '早餐', value: 1 },
        { text: '午餐', value: 2 },
        { text: '晚餐', value: 3 }
    ],
    [
        { text: '米饭', value: 1 },
        { text: '面条', value: 2 },
        { text: '面包', value: 3 },
        { text: '沙拉', value: 4 }
    ]
]);

const defaultValue = ref<number[]>([1,2]);
</script>

API

Props

参数	说明	类型	默认值
v-model \ modelValue	当前选中项对应的值，多列时候为数组	string \| number	-
show	是否展示picker弹窗	boolean	false
showToolbar	是否显示顶部的操作栏	boolean	true
title	顶部标题	string	-
columns	数据对象，多列时候为二维数组，单列时候为一维数组	UnPickerColumn \| UnPickerColumn[]	-
loading	是否显示加载中状态	boolean	false
itemHeight	各列中，单个选项的高度	string \| number	44
cancelText	取消按钮的文字	string	取消
confirmText	确认按钮的文字	string	确认
cancelColor	取消按钮的颜色	string	#909193
confirmColor	确认按钮的颜色	string	#3c9cff
visibleItemCount	每列中可见选项的数量	string \| number	5
closeOnClickOverlay	是否允许点击遮罩关闭选择器	boolean	true
defaultIndex	各列的默认索引，多列时候为数组，单列时候为数字	number \| number[]	-
immediateChange	是否在手指松开时立即触发change事件	boolean	false
round	设置圆角值	string \| number	0
showInput v4.1.0	是否显示input输入框	Boolean	false
inputProps v4.1.0	input属性，参考input组件	Object	-
showDefaultValue v4.1.0	是否显示默认值	Boolean	false

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 // 当前列索引
    value: UnPickerColumnItem | UnPickerColumnItem[] // 各列的选中项
    values: UnPickerColumn | UnPickerColumn[] // 各列的选中项数组
}

UnPickerConfirmEvent

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

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