Picker

17:06

Description

A bottom popup picker. A boolean v-model controls popup open/close and columns data is passed in externally. Supports selector (single column), multiSelector (independent columns) and cascade (tree linkage via children); confirm / change return an event object with selectedIndex, selectedValues and selectedOptions.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Single Column

mode=selector, pass one column via columns.

View source

<template>
    <ux-button size="small" shape="round" @click="show = true">打开选择器</ux-button>
    <text v-if="result !== ''" class="result">选择结果: {{ result }}</text>
    <ux-picker v-model="show" mode="selector" :columns="columns" :default-index="[2]" title="单选选择器" @confirm="onConfirm"></ux-picker>
</template>

<script setup lang="uts">
import type { PickerOption } from '@/uni_modules/uview-pro-x';

const show = ref<boolean>(false);
const result = ref<string>('');

const columns: PickerOption[][] = [
    [
        { text: '春眠不觉晓', value: 1 },
        { text: '处处闻啼鸟', value: 2 },
        { text: '夜来风雨声', value: 3 },
        { text: '花落知多少', value: 4 }
    ]
];

function onConfirm(event: UTSJSONObject): void {
    const values = event['selectedValues'] as string[];
    if (values == null) return;
    result.value = values.join(' / ');
}
</script>

<style scoped>
.result {
    margin-top: 10px;
    font-size: 13px;
    color: #909399;
}
</style>

Multi Column

mode=multiSelector, pass multiple independent columns.

View source

<template>
    <ux-button size="small" shape="round" @click="show = true">打开选择器</ux-button>
    <text v-if="result !== ''" class="result">选择结果: {{ result }}</text>
    <ux-picker v-model="show" mode="multiSelector" :columns="columns" :default-index="[0, 0, 1]" title="多列选择器" @confirm="onConfirm"></ux-picker>
</template>

<script setup lang="uts">
import type { PickerOption } from '@/uni_modules/uview-pro-x';

const show = ref<boolean>(false);
const result = ref<string>('');

const columns: PickerOption[][] = [
    [
        { text: '亚洲', value: 'asia' },
        { text: '欧洲', value: 'europe' }
    ],
    [
        { text: '中国', value: 'cn' },
        { text: '日本', value: 'jp' }
    ],
    [
        { text: '北京', value: 'bj' },
        { text: '上海', value: 'sh' },
        { text: '广州', value: 'gz' }
    ]
];

function onConfirm(event: UTSJSONObject): void {
    const values = event['selectedValues'] as string[];
    if (values == null) return;
    result.value = values.join(' / ');
}
</script>

<style scoped>
.result {
    margin-top: 10px;
    font-size: 13px;
    color: #909399;
}
</style>

Cascade

mode=cascade, use children tree data for region linkage.

View source

<template>
    <ux-button size="small" shape="round" @click="show = true">打开选择器</ux-button>
    <text v-if="result !== ''" class="result">选择结果: {{ result }}</text>
    <ux-picker v-model="show" mode="cascade" :columns="columns" :default-index="[0, 0, 0]" title="级联选择器" @confirm="onConfirm"></ux-picker>
</template>

<script setup lang="uts">
import type { PickerOption } from '@/uni_modules/uview-pro-x';

const show = ref<boolean>(false);
const result = ref<string>('');

const columns: PickerOption[][] = [
    [
        {
            text: '山东省',
            children: [
                {
                    text: '青岛市',
                    children: [
                        { text: '崂山区' },
                        { text: '市南区' }
                    ]
                },
                {
                    text: '济南市',
                    children: [
                        { text: '历下区' },
                        { text: '市中区' }
                    ]
                }
            ]
        }
    ]
];

function onConfirm(event: UTSJSONObject): void {
    const values = event['selectedValues'] as string[];
    if (values == null) return;
    result.value = values.join(' / ');
}
</script>

<style scoped>
.result {
    margin-top: 10px;
    font-size: 13px;
    color: #909399;
}
</style>

Custom Style

Customize title, cancel/confirm button colors.

View source

<template>
    <ux-button size="small" shape="round" @click="show = true">打开选择器</ux-button>
    <text v-if="result !== ''" class="result">选择结果: {{ result }}</text>
    <ux-picker v-model="show" mode="selector" :columns="columns" title="自定义颜色" cancel-color="#909399" confirm-color="#fa3534" @confirm="onConfirm"></ux-picker>
</template>

<script setup lang="uts">
import type { PickerOption } from '@/uni_modules/uview-pro-x';

const show = ref<boolean>(false);
const result = ref<string>('');

const columns: PickerOption[][] = [
    [
        { text: '红色', value: 'red' },
        { text: '蓝色', value: 'blue' },
        { text: '绿色', value: 'green' }
    ]
];

function onConfirm(event: UTSJSONObject): void {
    const values = event['selectedValues'] as string[];
    if (values == null) return;
    result.value = values.join(' / ');
}
</script>

<style scoped>
.result {
    margin-top: 10px;
    font-size: 13px;
    color: #909399;
}
</style>

API

Props

Property	Description	Type	Default	Version
customStyle		UTSJSONObject	-	-
customClass		string	''	-
modelValue	v-model controls popup open/close	boolean	false	-
columns	Column data, passed in externally: selector takes [[a, b, c]]; multiSelector takes [[a, b], [c, d]]; cascade takes [[root]], expanded via children	PickerOption[][]	-	-
mode	Mode: selector (single column), multiSelector (independent columns), cascade (tree linkage)	PickerMode	'selector'	-
defaultIndex	Default selected index	number[]	-	-
title	Top title	string	''	-
cancelText	Cancel button text	string	''	-
confirmText	Confirm button text	string	''	-
cancelColor	Cancel button color	string	''	-
confirmColor	Confirm button color	string	''	-
maskCloseAble	Whether the popup can be closed by tapping the mask	boolean	true	-
safeAreaInsetBottom	Whether to enable the bottom safe-area inset (default true; the internal ux-popup adds padding-bottom when mode=bottom)	boolean	true	-
zIndex	Popup z-index	number | string	0	-

Events

Event	Description	Params	Version
confirm		event: UTSJSONObject	-
cancel		-	-
change		event: UTSJSONObject	-

Slots

Slot	Description	Version
title	Custom content for the top title area (renders the title text by default)	-

Notes

1. Use a boolean v-model to control popup open/close; columns data is passed in externally.
2. mode values: selector ([[a, b, c]], single column), multiSelector ([[a, b], [c, d]], independent columns), cascade ([[root]], tree linkage via children).
3. confirm / change receive an object containing selectedIndex, selectedValues (text array) and selectedOptions (option object array).
4. default-index sets the default selected index of each column; its length should match the column count, otherwise indices start from 0.
5. The title slot fully customizes the title area (defaults to the title text).
6. The bottom safe area is handled by the internal ux-popup (safe-area-inset-bottom); a z-index of 0 falls back to $u.zIndex.popup.