Select 下拉列表 | uView Next - 企业级、高质量、更贴近业务场景的 uniapp ui框架

# Select 下拉列表

该组件是一个基于本地数据的下拉列表，提供丰富的配置选项和事件回调，适用于各种选择场景。

# 基本使用

基础选择器，支持单选模式，通过 v-model 绑定选中值。

<template>
    <view>
        <un-select 
            v-model="value" 
            :list="options" 
            placeholder="请选择城市"
            @change="onChange"
        ></un-select>
    </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { UnSelectOption } from '@/uni_modules/uview-unix/components/un-select'

const value = ref('')
const options = ref<UnSelectOption[]>([
    { text: '北京', value: 'beijing' },
    { text: '上海', value: 'shanghai' },
    { text: '广州', value: 'guangzhou' },
    { text: '深圳', value: 'shenzhen' }
])

const onChange = (value: string | number) => {
    console.log('选择变化:', value)
}
</script>
✅ Copy success!

# 带标签的选择器

通过 label 参数可以添加左侧标题。

<template>
    <un-select 
        v-model="gender" 
        :list="genderOptions" 
        label="性别"
        placeholder="请选择性别"
    ></un-select>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { UnSelectOption } from '@/uni_modules/uview-unix/components/un-select'

const gender = ref('')
const genderOptions = ref<UnSelectOption[]>([
    { text: '男', value: 'male' },
    { text: '女', value: 'female' }
])
</script>
✅ Copy success!

# 不同边框样式

通过 mode 参数可以设置不同的边框样式。

<template>
    <view class="demo">
        <un-select 
            v-model="value1" 
            :list="options" 
            border="bottom"
            placeholder="下划线模式"
        ></un-select>
        
        <un-select 
            v-model="value2" 
            :list="options" 
            border="none"
            placeholder="无边框模式"
        ></un-select>
    </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { UnSelectOption } from '@/uni_modules/uview-unix/components/un-select'

const value1 = ref('')
const value2 = ref('')
const options = ref<UnSelectOption[]>([
    { text: '北京', value: 'beijing' },
    { text: '上海', value: 'shanghai' },
    { text: '广州', value: 'guangzhou' },
    { text: '深圳', value: 'shenzhen' }
])
</script>
✅ Copy success!

# 文字对齐

通过 align 参数可以设置选择文字的对齐方式。

<template>
    <!-- 左对齐 -->
    <un-select v-model="value1" :list="options" align="left"></un-select>
    
    <!-- 居中对齐 -->
    <un-select v-model="value2" :list="options" align="center"></un-select>
    
    <!-- 右对齐 -->
    <un-select v-model="value3" :list="options" align="right"></un-select>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { UnSelectOption } from '@/uni_modules/uview-unix/components/un-select'

const value = ref('')
const options = ref<UnSelectOption[]>([
    { text: '北京', value: 'beijing' },
    { text: '上海', value: 'shanghai' },
    { text: '广州', value: 'guangzhou' },
    { text: '深圳', value: 'shenzhen' }
])
</script>
✅ Copy success!

# 弹出位置

通过 placement 参数可以设置下拉列表的弹出位置。

<template>
    <view class="demo">
        <un-select 
            v-model="value1" 
            :list="options" 
            placement="top"
            placeholder="向上弹出"
        ></un-select>
        
        <un-select 
            v-model="value2" 
            :list="options" 
            placement="bottom"
            placeholder="向下弹出"
        ></un-select>
    </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { UnSelectOption } from '@/uni_modules/uview-unix/components/un-select'

const value1 = ref('')
const value2 = ref('')
const options = ref<UnSelectOption[]>([
    { text: '北京', value: 'beijing' },
    { text: '上海', value: 'shanghai' },
    { text: '广州', value: 'guangzhou' },
    { text: '深圳', value: 'shenzhen' }
])
</script>
✅ Copy success!

# 禁用选项

在数据中通过 disabled 属性可以禁用特定选项。

<template>
    <un-select 
        v-model="value" 
        :list="options" 
        placeholder="包含禁用选项"
    ></un-select>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { UnSelectOption } from '@/uni_modules/uview-unix/components/un-select'

const value = ref('')
const options = ref<UnSelectOption[]>([
    { text: '选项1', value: 'option1' },
    { text: '选项2', value: 'option2', disabled: true },
    { text: '选项3', value: 'option3' },
    { text: '选项4', value: 'option4', disabled: true }
])
</script>
✅ Copy success!

# API

# Props

参数	说明	类型	默认值	可选值
modelValue	默认值	string \| number	''	-
list	本地数据，格式 [{text:'',value:'',disabled?:boolean}]	Array	[]	-
clearable	是否显示清除控件	boolean	true	true、false
emptyText	没有数据时显示的文字	string	'暂无数据'	-
label	左侧标题	string	''	-
placeholder	输入框的提示文字	string	'请选择'	-
placeholderStyle	placeholder的样式	string \| object	''	-
backgroundColor	背景颜色	string	'#ffffff'	-
round	圆角值	string \| number	''	-
borderColor	边框颜色	string	'#dcdfe6'	-
disabled	是否禁用	boolean	false	true、false
disabledColor	禁用状态时的背景色	string	'#f5f7fa'	-
wrap	是否允许选中文本换行显示	boolean	false	true、false
placement	弹出位置	string	'bottom'	'top'、'bottom'
align	选择文字的位置	string	'left'	'left'、'center'、'right'
showArrow	是否显示右侧箭头	boolean	false	true、false
border	边框类型	string	'surround'	'surround'、'bottom'、'none'
customStyle	自定义样式	string \| object	''	-
inputStyle	输入框样式	string \| object	''	-

# Events

事件名	说明	回调参数
update:modelValue	更新选中值时触发	value: 选中的值
change	选中发生变化触发	value: 选中的值
open	下拉列表开启时触发	-
close	下拉列表关闭时触发	-
clear	点击清除按钮之后触发	oldValue: 清空前的值

# Slots

名称	说明
default	自定义选择器的所有内容

# 类型定义

# UnSelectOption

下拉选择器的选项数据类型，用于定义 list 属性的数据结构。

type UnSelectOption = {
    text: string                    // 选项显示文本
    value: string | number           // 选项值
    disabled?: boolean               // 是否禁用（可选）
}
✅ Copy success!

示例：

const options: UnSelectOption[] = [
    { text: '北京', value: 'beijing' },
    { text: '上海', value: 'shanghai' },
    { text: '广州', value: 'guangzhou' },
    { text: '深圳', value: 'shenzhen', disabled: true }
]
✅ Copy success!

← AreaPicker 地区选择器 Rate 评分 →