uView Pro X

简体中文

English

简体中文

English

主题

Picker 选择器 ​

17:06

说明 ​

底部弹出的选择器，用布尔 v-model 控制弹出与收起，columns 数据全部由外部传入。支持 selector（单列）、multiSelector（多列独立）、cascade（树形 children 级联）三种模式，confirm / change 回传含 selectedIndex、selectedValues、selectedOptions 的事件对象。

兼容性 ​

平台支持情况
App✅ 支持
H5✅ 支持
微信小程序✅ 支持

示例 ​

单列选择 ​

mode=selector，columns 传一列数据。

查看源码
vue
<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>

多列选择 ​

mode=multiSelector，columns 传多列独立数据。

查看源码
vue
<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>

级联联动 ​

mode=cascade，通过 children 树形数据实现省市区联动。

查看源码
vue
<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>

自定义样式 ​

自定义标题、取消/确认按钮颜色。

查看源码
vue
<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 ​

属性说明类型默认值版本
customStyleUTSJSONObject--
customClassstring''-
modelValuev-model 控制弹出与收起booleanfalse-
columns列数据，全部由外部传入： selector 传 [[a, b, c]]； multiSelector 传 [[a, b], [c, d]]； cascade 传 [[根节点]]，通过 children 展开联动PickerOption[][]--
mode模式，selector-单列，multiSelector-多列，cascade-级联联动PickerMode'selector'-
defaultIndex默认选中的下标number[]--
title顶部标题string''-
cancelText取消按钮文字string''-
confirmText确认按钮文字string''-
cancelColor取消按钮颜色string''-
confirmColor确认按钮颜色string''-
maskCloseAble是否允许点击遮罩关闭booleantrue-
safeAreaInsetBottom是否开启底部安全区适配（默认 true，由 ux-popup 在 mode=bottom 时加 padding-bottom）booleantrue-
zIndex弹出 z-indexnumber | string0-

Events ​

事件名说明回调参数版本
confirmevent: UTSJSONObject-
cancel--
changeevent: UTSJSONObject-

Slots ​

插槽名说明版本
title自定义顶部标题区内容（默认渲染 title 文本）-

注意事项 ​

  1. 必须用布尔 v-model 控制弹出与收起，columns 数据全部由外部传入。
  2. mode 取值：selector（[[a, b, c]] 单列）、multiSelector（[[a, b], [c, d]] 多列独立）、cascade（[[根节点]]，通过 children 树形联动）。
  3. confirm / change 回调参数为对象，含 selectedIndex、selectedValues（文本数组）、selectedOptions（选项对象数组）。
  4. default-index 为各列默认选中下标，长度需与列数匹配，否则按 0 起算。
  5. title 插槽可完全自定义标题区（默认渲染 title 文本）。
  6. 底部安全区由内部 ux-popup 处理（safe-area-inset-bottom）；z-index 为 0 时回退到 $u.zIndex.popup。
Copyright © 2026 uView Pro X | 鲁ICP备2021040594号-5