Dropdown 下拉菜单

向下弹出的菜单列表，支持多种触发方式、单选/多选、子菜单、分组等功能。

基础用法

通过默认插槽传入触发按钮，#dropdown 插槽传入菜单内容。

<my-dropdown>
  <my-button>下拉菜单</my-button>
  <template #dropdown>
    <div @click.stop>选项一</div>
    <div @click.stop>选项二</div>
  </template>
</my-dropdown>

带单选

v-model 绑定选中值，选中项带高亮和勾选标记。

当前值: 未选

<my-dropdown v-model="selected" :options="options">
  <my-button>{{ selected || '请选择' }} ▾</my-button>
</my-dropdown>

单选且自定义指示器

通过 #item 插槽自定义选项渲染，搭配自定义选中标记。

<my-dropdown v-model="selected" :options="options">
  <template #item="{ item }">
    <span>{{ selected === item.value ? '●' : '○' }}</span>
    <span>{{ item.label }}</span>
  </template>
  <my-button>选择</my-button>
</my-dropdown>

带多选

:multiple="true" 开启多选模式，选中项显示勾选框。

<my-dropdown v-model="selected" :options="options" multiple>
  <my-button>选择</my-button>
</my-dropdown>

带分组级选择

通过 group 字段对选项分组，支持全选/部分选。

<my-dropdown v-model="selected" :options="groupOptions" multiple>
  <my-button>选择</my-button>
</my-dropdown>

带图标

选项通过 icon 字段传入 SVG 图标。

<my-dropdown v-model="selected" :options="iconOptions">
  <my-button>操作菜单</my-button>
</my-dropdown>

长按触发

trigger="longpress" 长按 0.6s 后弹出菜单。

长按试试

<my-dropdown v-model="selected" :options="options" trigger="longpress">
  <my-button>长按</my-button>
</my-dropdown>

带描述

选项通过 description 字段添加辅助说明文字。

<my-dropdown v-model="selected" :options="[
  { label: '静音', value: 'mute', description: '关闭所有通知声音' },
  { label: '震动', value: 'vibrate', description: '来电时设备震动' },
]">
  <my-button>选择</my-button>
</my-dropdown>

带分组

通过 group 字段对选项分组，组与组之间有标题。

<my-dropdown v-model="selected" :options="groupedOptions">
  <my-button>选择城市</my-button>
</my-dropdown>

带禁用项

选项通过 disabled: true 禁用。

<my-dropdown v-model="selected" :options="[
  { label: '选项一', value: '1' },
  { label: '选项二（禁用）', value: '2', disabled: true },
]">
  <my-button>选择</my-button>
</my-dropdown>

带子菜单

通过 children 字段定义子菜单，悬停展开。

未选择

<my-dropdown v-model="selected" :options="[
  { label: '导航一', value: 'nav1' },
  { label: '导航二', children: [
    { label: '选项 2-1', value: '2-1' },
    { label: '选项 2-2', value: '2-2' },
  ]},
]">
  <my-button>导航</my-button>
</my-dropdown>

带自定义菜单指示器

#item 插槽完全控制选项渲染，可自定义勾选指示器样式。

<my-dropdown v-model="selected" :options="options">
  <template #item="{ item }">
    <span>{{ item.label }}</span>
    <span v-if="selected === item.value">✓</span>
  </template>
  <my-button>选择</my-button>
</my-dropdown>

受控

v-model 完全控制当前选中值，可用于语言切换等场景。

<my-dropdown v-model="lang" :options="options">
  <my-button>{{ lang }} ▾</my-button>
</my-dropdown>

受控展开状态

v-model:visible 控制菜单展开/收起。

未选

<my-dropdown v-model:visible="visible" v-model="selected" :options="options">
  <my-button>下拉</my-button>
</my-dropdown>
<my-button @click="visible = !visible">切换</my-button>

自定义触发器

#trigger 插槽自定义触发元素，适用于头像下拉等场景。

用户▾

<my-dropdown trigger="click">
  <template #trigger="{ visible }">
    <div style="display:flex;align-items:center;gap:8px;cursor:pointer">
      <img src="/images/icon.png" style="width:36px;height:36px;border-radius:50%;object-fit:cover" />
      <span>用户名</span>
    </div>
  </template>
  <template #dropdown>
    <!-- 头像 + 名称 + 邮箱 -->
    <!-- 个人资料 / 设置 / 创建团队 / 退出登录 -->
  </template>
</my-dropdown>

组件结构

<div> 根元素包含触发插槽（#trigger）和过渡动画包裹的下拉菜单（my-dropdown__menu）。菜单内部根据 options 渲染分组标题、分割线和选项列表，或通过 #dropdown 插槽自定义内容。

CSS 类名

类名	说明
.my-dropdown	根元素
.is-large	大尺寸
.is-small	小尺寸
.my-dropdown__menu	下拉菜单
.is-bottom-start	下方左对齐
.is-bottom-end	下方右对齐
.is-top-start	上方左对齐
.is-top-end	上方右对齐
.my-dropdown__item	菜单项
.is-disabled	禁用状态
.is-active	激活状态
.is-danger	危险样式
.my-dropdown__icon	选项图标
.my-dropdown__check	选中勾选标记
.my-dropdown__content	选项内容容器
.my-dropdown__label	选项标签
.my-dropdown__desc	选项描述
.my-dropdown__divider	分割线
.my-dropdown__group-title	分组标题
.-fade-*	菜单过渡动画

API

Props

属性	说明	类型	默认值
options	菜单选项列表	DropdownOption[]	—
modelValue	绑定值 (v-model)	any | any[]	—
visible	展开状态 (v-model:visible)	boolean	false
trigger	触发方式	'click' | 'hover' | 'contextmenu' | 'longpress' | 'manual'	'click'
placement	弹出位置	'bottom-start' | 'bottom-end' | 'top-start' | 'top-end'	'bottom-start'
disabled	禁用	boolean	false
multiple	多选模式	boolean	false
hideOnClick	点击选项后关闭菜单	boolean	true
size	尺寸	'large' | 'default' | 'small'	'default'

DropdownOption

属性	说明	类型	默认值
label	选项文本	string	—
value	选项值	any	—
disabled	禁用选项	boolean	false
divided	上方显示分割线	boolean	false
icon	图标 (SVG字符串)	string	—
description	描述文字	string	—
danger	危险样式	boolean	false
children	子菜单选项	DropdownOption[]	—
group	分组名	string	—

Events

事件	说明	回调
update:modelValue	v-model 更新	(value: any)
update:visible	展开状态更新	(visible: boolean)
select	选项点击	(item: DropdownOption)
visibleChange	展开状态变更	(visible: boolean)

Slots

名称	说明	作用域
trigger	自定义触发元素	{ visible, toggle, open, close }
dropdown	自定义菜单内容（不使用 options 时）	—
item	自定义选项渲染	{ item }