uView Next
4.0.105

外观

Select 下拉列表

约 1408 字大约 5 分钟

2025-10-31

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

基本使用

基础选择器，支持单选模式，通过 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'

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>

带标签的选择器

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

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

不同边框样式

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

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

文字对齐

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

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

弹出位置

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

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

禁用选项

在数据中通过 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'

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>

API

Props

参数说明类型默认值
modelValue默认值string | number-
list本地数据UnSelectOption[][]
clearable是否显示清除控件booleantrue
emptyText没有数据时显示的文字string暂无数据
label左侧标题string-
placeholder输入框的提示文字string请选择
placeholderStyleplaceholder的样式string | object-
backgroundColor背景颜色string#ffffff
round圆角值string | number-
borderColor边框颜色string#dcdfe6
disabled是否禁用booleanfalse
disabledColor禁用状态时的背景色string#f5f7fa
wrap是否允许选中文本换行显示booleanfalse
placement弹出位置
Enum
bottom
align选择文字的位置
Enum
left
showArrow是否显示右侧箭头booleanfalse
border边框类型
Enum
surround
inputStyle输入框样式string | object-

Events

事件名说明类型
update:modelValue更新选中值时触发
Function
change选中发生变化触发
Function
open下拉列表开启时触发
Function
close下拉列表关闭时触发
Function
clear点击清除按钮之后触发
Function

Slots

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

数据类型


// 下拉选择器的选项数据类型，用于定义 `list` 属性的数据结构。
type UnSelectOption = {
    text: string                    // 选项显示文本
    value: string | number           // 选项值
    disabled?: boolean               // 是否禁用（可选）
}

示例：

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

Scss 变量

变量名默认值说明
$un-select-label-margin-bottom8px标签底部间距
$un-select-input-padding0px 9px输入框内边距
$un-select-input-height37px输入框高度
$un-select-input-border1px solid $border-color输入框边框
$un-select-right-margin-left8px右侧元素左侧间距
$un-select-clear-width20px清除按钮宽度
$un-select-clear-bg-color#c6c7cb清除按钮背景色
$un-select-clear-scale0.82清除按钮缩放比例
$un-select-arrow-width16px箭头图标宽度
$un-select-arrow-transition-duration0.3s箭头过渡动画时长
$un-select-dropdown-max-height200px下拉列表最大高度
$un-select-empty-padding20px空数据提示内边距
$un-select-options-padding4px 0选项列表内边距
$un-select-option-padding8px 12px选项内边距
$un-select-selected-icon-margin-left8px选中图标左侧间距
$un-select-font-size$text-base文字大小
$un-select-line-height$line-base行高
$un-select-text-color$text-color文字颜色
$un-select-text-color-placeholder$text-color-placeholder占位文字颜色
$un-select-text-color-muted$text-color-muted弱化文字颜色
$un-select-text-color-active$text-color-active激活文字颜色
$un-select-text-color-disabled$text-color-disabled禁用文字颜色
$un-select-bg-color-container$bg-color-container容器背景色
$un-select-bg-color-lighter$bg-color-lighter浅色背景色
$un-select-box-shadow0 2px 12px 0 rgba(0, 0, 0, 0.1)下拉列表阴影
$un-select-z-index10选择框层级
$un-select-dropdown-z-index1080下拉列表层级

提示

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

Copyright © 2026 uView Next