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

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

# 平台差异说明

App（vue）	App（nvue）	H5	小程序
√	X	√	√

# 基本使用

使用前说明：

该组件必须结合u-dropdown和u-dropdown-item一起使用，展开的内容由u-dropdown-item通过传递参数或者slot提供
组件的菜单栏标题由u-dropdown-item通过title参数提供
u-dropdown-item带有默认的单选展示功能，通过options(见下方说明)配置，传入slot则会覆盖默认功能，通过v-model双向绑定options选中项的value值

<template>
	<view class="">
		<u-dropdown>
			<u-dropdown-item v-model="value1" title="距离" :options="options1"></u-dropdown-item>
			<u-dropdown-item v-model="value2" title="温度" :options="options2"></u-dropdown-item>
		</u-dropdown>
	</view>
</template>

<script>
	export default {
		data() {
			return {
				value1: 1,
				value2: 2,
				options1: [{
						label: '默认排序',
						value: 1,
					},
					{
						label: '距离优先',
						value: 2,
					},
					{
						label: '价格优先',
						value: 3,
					}
				],
				options2: [{
						label: '去冰',
						value: 1,
					},
					{
						label: '加冰',
						value: 2,
					},
				],
			}
		},
	}
</script>
✅ Copy success!

# 自定义菜单（标题插槽） 3.6.13

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

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

<script>
export default {
	data() {
		return {
			value1: 1,
			value2: 2,
			options1: [
				{ label: '默认排序', value: 1 },
				{ label: '距离优先', value: 2 },
				{ label: '价格优先', value: 3 }
			],
			options2: [
				{ label: '去冰', value: 1 },
				{ label: '加冰', value: 2 }
			]
		}
	},
	methods: {
		handleClick() {
			// 自定义点击行为，例如打开侧边筛选弹窗等
			console.log('handleClick')
		}
	}
}
</script>
✅ Copy success!

说明：

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

# 配置选项卡默认功能

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

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

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

# 配置选项卡自定义功能

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

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

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

<template>
	<view class="">
		<u-dropdown ref="uDropdown">
			<u-dropdown-item title="属性">
				<view class="slot-content">
					<view class="un-text-center u-content-color u-m-t-20 u-m-b-20">其他自定义内容</view>
					<un-button type="primary" @click="closeDropdown">确定</un-button>
				</view>
			</u-dropdown-item>
		</u-dropdown>
	</view>
</template>

<script>
	export default {
		methods: {
			closeDropdown() {
				this.$refs.uDropdown.close();
			}
		}
	}
</script>
✅ Copy success!

# 配置选项卡内容可滚动

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

<template>
	<view class="">
		<u-dropdown ref="uDropdown">
			<u-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>
			</u-dropdown-item>
		</u-dropdown>
	</view>
</template>

<script>
	export default {
		methods: {
			closeDropdown() {
				this.$refs.uDropdown.close();
			}
		}
	}
</script>
✅ Copy success!

# 如何保持菜单高亮（已废弃）

有时候，我们可能会希望下拉菜单收起之后，标题部分可以保持高亮，组件内部可以做到这样的要求，但是如果通过自定义slot传入了内容，那么组件就不知道收起的时候，是否该保持菜单的高亮了，因为组件不知道您在自定义的内容中是否进行了"操作"，所以我们提供了一个手动通过ref设置的highlight(index)方法，让您自主决定是否让某个菜单高亮，可以自行结合change(dropdown-item)、open(dropdown)、close(dropdown)事件进行组合操作。

<template>
	<view class="">
		<u-dropdown ref="uDropdown" @open="open" @close="close">
			<u-dropdown-item v-model="value1" title="距离" :options="options1" @change="change"></u-dropdown-item>
			<u-dropdown-item v-model="value2" title="温度" :options="options2"></u-dropdown-item>
		</u-dropdown>
	</view>
</template>

<script>
	export default {
		data() {
			return {
				value1: 1,
				value2: 2,
				options1: [{
						label: '默认排序',
						value: 1,
					},
					{
						label: '距离优先',
						value: 2,
					}
				],
				options2: [{
						label: '去冰',
						value: 1,
					},
					{
						label: '加冰',
						value: 2,
					},
				],
			}
		},
		methods: {
			open(index) {
				// 展开某个下来菜单时，先关闭原来的其他菜单的高亮
				// 同时内部会自动给当前展开项进行高亮
				this.$refs.uDropdown.highlight();
			},
			close(index) {
				// 关闭的时候，给当前项加上高亮
				// 当然，您也可以通过监听dropdown-item的@change事件进行处理
				this.$refs.uDropdown.highlight(index);
			},
			change() {
				// 更多的细节，如有需要请自行根据业务逻辑进行处理
				// this.$refs.uDropdown.highlight(xxx);
			}
		}
	}
</script>
✅ Copy success!

# 兼容性 3.6.12

由于头条小程序的兼容性原因，如果u-dropdown父元素设置了display: flex，您可能需要给组件添加u-dropdown类，如下：

<u-dropdown class="u-dropdown"></u-dropdown>
✅ Copy success!

# API

参数	说明	类型	默认值	可选值
activeColor	标题和选项卡选中的颜色	String	主题主色	-
inactiveColor	标题和选项卡未选中的颜色	String	主题文本色	-
disabledColor 3.6.13	标题和选项卡禁用时的颜色	String	主题禁用色	-
bgColor	标题选项卡背景颜色	String	#ffffff	-
round	标题选项卡圆角值	String \| Number	0	-
closeOnClickMask	点击遮罩是否关闭菜单	Boolean	true	false
closeOnClickSelf	点击当前激活项标题是否关闭菜单	Boolean	true	false
overlay 3.6.13	是否显示遮罩	Boolean	true	false
duration	选项卡展开和收起的过渡时间，单位ms	String \| Number	220	-
height	标题菜单的高度，单位任意	String \| Number	44	-
titleSize	标题的字体大小，单位任意	String \| Number	14	-
borderRadius	菜单展开内容下方的圆角值，单位任意	String \| Number	10	-
menuIcon	标题菜单右侧的图标	String	caret-down	-
menuIconSize	标题菜单右侧的图标的大小，单位任意	String \| Number	16	-

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

参数	说明	类型	默认值	可选值
v-model	双向绑定选项卡选择值	String \| Number \| Array	-	-
title	菜单项标题	String \| Number	-	-
disabledClick 3.6.13	禁用默认的点击展开/收起行为	Boolean	false	true
options	选项数据，如果传入了默认slot，此参数无效，数据结构见上方说明	Array[Object]	[]	-
disabled	是否禁用此选项卡	Boolean	false	true
height	弹窗下拉内容的高度(内容超出将会滚动)，`slot`自定义内容时无效(自行使用`scroll-view`处理)，单位任意	String \| Number	auto	-

名称	说明
default	自定义选项卡内容
label 3.6.13	自定义标题区域内容；插槽参数：`{ active }` 表示当前是否激活

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

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

参数	说明
open(index) 3.6.13	打开指定的菜单项
close(index) 3.6.13	关闭打开的下拉菜单
highlight(index) （已废弃）	index为需要设置高亮的菜单项的索引(从0开始)，不写表示清空内部的高亮

← Divider 分割线 Tabbar 底部导航栏 →