uView Next
4.0.105

外观

Dropdown 下拉菜单

约 2099 字大约 7 分钟

2025-10-31

该组件一般用于向下展开菜单，同时可切换多个选项卡的场景。

基本使用

使用前说明：

  • 该组件必须结合un-dropdown和un-dropdown-item一起使用，展开的内容由un-dropdown-item通过传递参数或者slot提供
  • 组件的菜单栏标题由un-dropdown-item通过title参数提供
  • un-dropdown-item带有默认的单选展示功能，通过options(见下方说明)配置，传入slot则会覆盖默认功能，通过v-model双向绑定options选中项的value值
<template>
	<view class="">
		<un-dropdown>
			<un-dropdown-item v-model="value1" title="距离" :options="options1"></un-dropdown-item>
			<un-dropdown-item v-model="value2" title="温度" :options="options2"></un-dropdown-item>
		</un-dropdown>
	</view>
</template>

<script setup lang="ts">
  import { ref } from 'vue'
  import type { UnDropdownOption } from '@/uni_modules/uview-unix'
  
  const value1 = ref(1)
  const value2 = ref(2)
  
  const options1 = ref<UnDropdownOption[]>([
    {
      label: '默认排序',
      value: 1,
    },
    {
      label: '距离优先',
      value: 2,
    },
    {
      label: '价格优先',
      value: 3,
    }
  ])
  
  const options2 = ref<UnDropdownOption[]>([
    {
      label: '去冰',
      value: 1,
    },
    {
      label: '加冰',
      value: 2,
    },
  ])
</script>

自定义菜单（标题插槽）

当需要自定义每个菜单项在标题栏中的展示（而非下拉内容）时，可使用un-dropdown-item的label插槽。同时可配合disabledClick禁用默认的点击展开/收起行为，以实现自定义的交互逻辑。

<template>
	<view class="">
		<un-dropdown activeColor="#f00" ref="dropdown">
			<un-dropdown-item v-model="value1" title="距离" :options="options1"></un-dropdown-item>
			<un-dropdown-item v-model="value2" :options="options2">
				<template #label="{ active }">
					<text>插槽 {{ active }}</text>
				</template>
			</un-dropdown-item>
			<un-dropdown-item disabledClick>
				<template #label>
					<text @click="handleClick">筛选</text>
				</template>
			</un-dropdown-item>
		</un-dropdown>
	</view>
</template>

<script setup lang="ts">
  import { ref } from 'vue'
  import type { UnDropdownOption } from '@/uni_modules/uview-unix'
  
  const dropdown = ref()
  const show = ref(false)
  const value1 = ref(1)
  const value2 = ref(2)
  
  const options1 = ref<UnDropdownOption[]>([
    { label: '默认排序', value: 1 },
    { label: '距离优先', value: 2 },
    { label: '价格优先', value: 3 }
  ])
  
  const options2 = ref<UnDropdownOption[]>([
    { label: '去冰', value: 1 },
    { label: '加冰', value: 2 }
  ])
  
  const handleClick = () => {
    show.value = true
    console.log('handleClick')
  }
  
  const handleClose = () => {
    show.value = false
  }
</script>

说明：

  • label插槽用于自定义菜单标题区域的内容。
  • label插槽参数包含active字段，表示该菜单是否处于激活状态 。
  • 配合disabledClick可禁用默认展开逻辑，完全由业务控制点击交互 。

配置选项卡默认功能

如上所示，un-dropdown-item具有默认的单选功能，这里主要讲解其options和v-model参数：

options参数为一个数组，元素为对象，其中label为需要展示的提示文字，value为点击时双向绑定给v-model的值，v-model初始化时如果设置 某个options中的value，则该条目将会被默认选中：

let options = [
	{
		label: '蜀道难',
		value: 1
	},
	{
		label: '难以上青天',
		value: 2
	}
]

配置选项卡自定义功能

在选项卡默认的单选功能无法满足的时候，我们可以给un-dropdown-item传递slot来自定义需要展示的内容。

问：如果自定义内容，如何实现点击其中的按钮关闭下拉菜单？

答：在un-dropdown中，有一个close()方法，可以通过ref获取实例，并调用方法进行关闭即可。

<template>
	<view class="">
		<un-dropdown ref="uDropdown">
			<un-dropdown-item title="属性">
				<view class="slot-content">
					<un-radio-group v-model="radiovalue1">
						<un-radio
							:customStyle="{marginRight: '8px'}"
							v-for="(item, index) in radiolist1"
							:key="index"
							:label="item.name"
							:name="item.name"
						>
						</un-radio>
					</un-radio-group>
					<un-button type="primary" shape="circle" text="确定" @click="closeDropdown"></un-button>
				</view>
			</un-dropdown-item>
		</un-dropdown>
	</view>
</template>

<script setup lang="ts">
  import { ref } from 'vue'
  
  const uDropdown = ref()
  
  type RadioItem = {
    name: string,
    disabled: boolean
  }
  
  const radiovalue1 = ref('苹果')
  const radiolist1 = ref<RadioItem[]>([
    {
      name: '苹果',
      disabled: false
    },
    {
      name: '香蕉',
      disabled: false
    },
    {
      name: '橙子',
      disabled: false
    }, 
    {
      name: '榴莲',
      disabled: false
    }
  ])
  
  const closeDropdown = () => {
    if(uDropdown.value != null) {
      uDropdown.value.close();
    }
  }
</script>

配置选项卡内容可滚动

如果我们想给自定义内容的选项中局部内容可滚动，可以通过嵌入scroll-view元素实现，需要注意的是scroll-view必须声明高度才有效，大概如下：

<template>
	<view class="">
		<un-dropdown ref="uDropdown">
			<un-dropdown-item title="属性">
				<view class="slot-content" style="background-color: #FFFFFF;">
					<scroll-view scroll-y="true" style="height: 200rpx;">
						<view class="un-text-center u-content-color u-m-t-20 u-m-b-20">无言独上西楼</view>
						<view class="un-text-center u-content-color u-m-t-20 u-m-b-20">月如钩</view>
						<view class="un-text-center u-content-color u-m-t-20 u-m-b-20">寂寞梧桐深院锁清秋</view>
						<view class="un-text-center u-content-color u-m-t-20 u-m-b-20">剪不断</view>
						<view class="un-text-center u-content-color u-m-t-20 u-m-b-20">理还乱</view>
						<view class="un-text-center u-content-color u-m-t-20 u-m-b-20">是离愁</view>
						<view class="un-text-center u-content-color u-m-t-20 u-m-b-20">别是一般滋味在心头</view>
					</scroll-view>
					<un-button type="primary" @click="closeDropdown">确定</un-button>
				</view>
			</un-dropdown-item>
		</un-dropdown>
	</view>
</template>

<script setup lang="ts">
  import { ref } from 'vue'
  
  const uDropdown = ref()
  
  const closeDropdown = () => {
    if(uDropdown.value != null) {
      uDropdown.value.close();
    }
  }
</script>

API

参数说明类型默认值
activeColor标题和选项卡选中的颜色string主题主色
inactiveColor标题和选项卡未选中的颜色string主题文本色
disabledColor标题和选项卡禁用时的颜色string主题禁用色
bgColor标题选项卡背景颜色string#ffffff
round标题选项卡圆角值string | number0
closeOnClickMask点击遮罩是否关闭菜单Booleantrue
closeOnClickSelf点击当前激活项标题是否关闭菜单Booleantrue
overlay是否显示遮罩Booleantrue
duration选项卡展开和收起的过渡时间，单位msstring | number220
height标题菜单的高度，单位任意string | number44
titleSize标题的字体大小，单位任意string | number14
borderRadius菜单展开内容下方的圆角值，单位任意string | number10
menuIcon标题菜单右侧的图标stringcaret-down
menuIconSize标题菜单右侧的图标的大小，单位任意string | number16

|事件名|说明|回调参数| |:-|:-|:-|:-| | open | 下拉菜单被打开时触发 | (index) - 当前被打开菜单的索引 | | close | 下拉菜单被关闭时触发 | (index) - 当前被关闭菜单的索引 |

参数说明类型默认值
v-model双向绑定选项卡选择值string | number | array-
title菜单项标题string | number-
disabledClick禁用默认的点击展开/收起行为Booleanfalse
options选项数据，如果传入了默认slot，此参数无效，数据结构见上方说明array[]
disabled是否禁用此选项卡Booleanfalse
height弹窗下拉内容的高度(内容超出将会滚动)，slot自定义内容时无效(自行使用scroll-view处理)，单位任意string | numberauto
名称说明
default自定义选项卡内容
label自定义标题区域内容；插槽参数：{ active } 表示当前是否激活

|事件名|说明|回调参数| |:-|:-|:-|:-| | change | 每个un-dropdown均有此回调，点击某个options选项时触发 | (value) - 点击项绑定的value属性值 | | open | 打开当前菜单项时触发 | - | | opened | 打开菜单项且动画结束后触发 | - | | close | 关闭当前菜单项时触发 | - | | closed | 关闭菜单项且动画结束后触发 | - |

这些为组件内部的方法，需要通过ref调用

参数说明
open(index)打开指定的菜单项
close(index)关闭打开的下拉菜单

数据类型

UnDropdownOption

字段名类型说明
labelstring选项显示文本
valuestring | number选项对应的值

Scss 变量

关于组件 SCSS 变量的用法，请参考 组件 SCSS 变量用法。

变量名默认值说明
$un-dropdown-bg-color-container$bg-color-container背景颜色
$un-dropdown-item-height44px项目高度
$un-dropdown-item-menu-label-font-size$text-base菜单标签字体大小
$un-dropdown-item-menu-label-color$text-color菜单标签颜色
$un-dropdown-item-menu-label-active-color$color-primary菜单标签激活颜色
$un-dropdown-item-menu-icon-margin-left2px菜单图标左边距
$un-dropdown-item-menu-icon-transitiontransform .3s菜单图标过渡效果
$un-dropdown-item-wrapper-z-index10000包装器层级
$un-dropdown-item-mask-z-index1000遮罩层级
$un-dropdown-item-mask-bg-color$bg-color-overlay遮罩背景颜色
$un-dropdown-item-popup-bg-color$bg-color-container弹窗背景颜色
$un-dropdown-item-options-padding-bottom10px选项底部内边距
$un-dropdown-item-options-item-height45px选项高度
$un-dropdown-item-options-item-padding0 15px选项内边距
$un-dropdown-item-options-item-text-color$text-color选项文本颜色
$un-dropdown-item-options-item-text-font-size$text-base选项文本字体大小
$un-dropdown-item-options-item-text-active-color$color-primary选项文本激活颜色

Copyright © 2026 uView Next