组件详情入口

导航

@vean/ui

SDropdownMenu

DropdownMenu

DropdownMenu 属于导航分类。建议先看演示与用法，再对照 API 表格完成接入和样式调整。

先用快捷跳转面板找到概述、用法、演示和 API，再往下细读完整文档内容。

快速跳转

概述用法演示 API 更新日志

同分类组件

如果你在同一类交互里做组合，这些组件通常会一起出现。

Anchor Breadcrumb Command ContextMenu Menu Menubar

下拉菜单

概述

由按钮触发向用户展示的菜单，例如一组操作或功能入口。SDropdownMenu 是基于 Aria menu 基础组件（MenuOptions/MenuItem/…）构建的数据驱动菜单，经共享 popover portal 渲染。家族还提供复选（SDropdownMenuCheckbox，多选）、单选（SDropdownMenuRadio，单选）与自定义（SDropdownMenuWrapper）变体。

下拉菜单适合紧凑的操作菜单。导航菜单请用 nav-menu；丰富的悬停预览请用 hover-card。

用法

特性

🧩 基于 Aria menu — 构建于共享 menu 基础组件，带完整键盘导航（方向键/Home/End/PageUp/PageDown）、类型过滤与 roving focus
🖱️ 触发模式 — trigger="click" 或 "hover"；delayDuration/skipDelayDuration 调节悬停延迟
📊 数据驱动 — 传入 items（含 value/label/icon/disabled/hidden/separator…）或使用条目插槽
☑️ 复选变体 — SDropdownMenuCheckbox 用 v-model 实现多选
🔘 单选变体 — SDropdownMenuRadio 用 v-model 实现单选
🧩 自定义变体 — SDropdownMenuWrapper 用于完全自定义菜单内容
🎯 定位 — popper placement + showArrow
🎭 模态 — modal 控制外部指针拦截与焦点陷阱
🪜 子菜单 — 嵌套子菜单，按侧打开/关闭键（RTL 感知）
🙈 隐藏项 — 条目标记 hidden 后（连同整棵子树）不会出现在菜单中
♿ 无障碍 — role="menu"/menuitem、复选/单选 aria-checked、axe-core 零违规

组件家族

SDropdownMenu（样式层）— 数据驱动菜单；转发至 DropdownMenuCompact
SDropdownMenuCheckbox（样式层）— 带 v-model 的多选菜单
SDropdownMenuRadio（样式层）— 带 v-model 的单选菜单
SDropdownMenuWrapper（样式层）— 自定义内容菜单
DropdownMenuCompact / DropdownMenuWrapperCompact / DropdownMenuCheckboxCompact / DropdownMenuRadioCompact（Aria）— 聚合组件
MenuOptions/MenuItem/…（Aria）— 共享 menu 基础组件（roving focus、键盘导航、子菜单）

演示

基础

100%

复选

100%

单选

100%

混合

100%

API

Aria 层

DropdownMenu<T>

29 属性9 事件6 插槽

属性

属性名	类型	默认值	描述
class	ClassValue	—	菜单弹出窗口的类
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<DropdownMenuUi>	—	该组件的按槽类重写。
disabled	boolean	—	该组件是否已禁用。
placement	Placement	—	位置。
showArrow	boolean	—	是否显示箭头。
triggerProps	DropdownMenuTriggerProps	—	转发给触发元素的属性。
portalProps	DropdownMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	DropdownMenuContentProps	—	转发给内容元素的属性。
popupProps	DropdownMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	DropdownMenuArrowProps	—	转发给箭头元素的属性。
trigger	DropdownMenuTriggerType	'click'	下拉菜单的触发类型。 - `click`：点击触发器时，下拉菜单将展开。 - `hover`：将鼠标悬停在触发器上时，下拉菜单将展开。
delayDuration	number	150	从指针进入触发器到下拉菜单打开所花费的时间。
skipDelayDuration	number	300	用户在触发延迟之前，有多少时间可以输入另一个触发条件。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
open	boolean	undefined	对话框的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	false	对话框在初始渲染时的打开状态。当无需控制其打开状态时使用。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuOptionData<T>[]	—	由该组件渲染的项。
selectedValue	T	—	菜单中的选定值。
itemProps	DropdownMenuItemProps	—	转发给 item 元素的属性。
linkProps	LinkExtraProps	—	传递给 link 元素的属性。
subProps	DropdownMenuSubProps	—	转发给子元素的属性。
groupProps	DropdownMenuGroupProps	—	转发给 group 元素的属性。
groupLabelProps	DropdownMenuGroupLabelProps	—	转发至组标签元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	DropdownMenuSeparatorProps	—	转发给分隔符元素的属性。
subTriggerProps	DropdownMenuSubTriggerProps	—	转发给子触发器元素的属性。
subContentProps	DropdownMenuSubContentProps	—	转发至子内容元素的属性。

事件

事件名	参数	描述
update:open	boolean	当对话框的打开状态发生变化时调用的事件处理程序。
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
entryFocus	Event	在条目获得焦点时触发。
select	MenuOptionData<T>, event: Event	在发生 select 事件时触发。

插槽

插槽名	参数	描述
item	{ item: MenuOptionData<T>; isTrigger?: boolean; }	项插槽的自定义内容。
item-leading	{ item: MenuOptionData<T>; }	用于项目引导槽位的自定义内容。
item-trailing	{ item: MenuOptionData<T>; }	用于项目尾部槽位的自定义内容。
item-trigger-icon	{ item: MenuOptionData<T>; }	项目触发图标槽位的自定义内容。
item-link-icon	{ item: MenuOptionData<T>; }	项目链接图标槽位的自定义内容。
trigger	—	触发槽的自定义内容。

DropdownMenuAnchor

DropdownMenuArrow

DropdownMenuCheckbox<T>

29 属性10 事件5 插槽

属性

属性名	类型	默认值	描述
class	((string \| false \| Record<string, any> \| ClassValue[]) & (string \| false \| Record<string, any> \| import("vue").ClassValue[])) \| null	—	菜单弹出窗口的类
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<DropdownMenuUi>	—	该组件的按槽类重写。
indicatorPosition	AlignSide	—	指示符位置。
disabled	boolean	—	该组件是否已禁用。
placement	Placement	—	位置。
showArrow	boolean	—	是否显示箭头。
triggerProps	DropdownMenuTriggerProps	—	转发给触发元素的属性。
portalProps	DropdownMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	DropdownMenuContentProps	—	转发给内容元素的属性。
popupProps	DropdownMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	DropdownMenuArrowProps	—	转发给箭头元素的属性。
trigger	DropdownMenuTriggerType	'click'	下拉菜单的触发类型。 - `click`：点击触发器时，下拉菜单将展开。 - `hover`：将鼠标悬停在触发器上时，下拉菜单将展开。
delayDuration	number	150	从指针进入触发器到下拉菜单打开所花费的时间。
skipDelayDuration	number	300	用户在触发延迟之前，有多少时间可以输入另一个触发条件。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
open	boolean	undefined	对话框的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	false	对话框在初始渲染时的打开状态。当无需控制其打开状态时使用。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuCheckboxOptionData<T>[]	—	由该组件渲染的项。
groupLabelProps	DropdownMenuGroupLabelProps	—	转发至组标签元素的属性。
checkboxItemProps	DropdownMenuCheckboxItemProps	—	转发给复选框项元素的属性。
indicatorProps	DropdownMenuItemIndicatorProps	—	转发给 indicator 元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	DropdownMenuSeparatorProps	—	转发给分隔符元素的属性。
modelValue	T[]	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	T[]	—	复选框在初始渲染时的值。当不需要控制其值时使用。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
update:open	boolean	当对话框的打开状态发生变化时调用的事件处理程序。
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
entryFocus	Event	在条目获得焦点时触发。
update:modelValue	T[]	当复选框组的值发生变化时调用的事件处理程序。
select	MenuCheckboxOptionData<T>, event: Event	在发生 select 事件时触发。

插槽

插槽名	参数	描述
item	MenuCheckboxOptionData<T>	项插槽的自定义内容。
item-leading	MenuCheckboxOptionData<T>	用于项目引导槽位的自定义内容。
item-trailing	MenuCheckboxOptionData<T>	用于项目尾部槽位的自定义内容。
item-indicator-icon	MenuCheckboxOptionData<T>	项目指示器图标槽位的自定义内容。
trigger	—	触发槽的自定义内容。

DropdownMenuCheckboxCompact<T>

25 属性10 事件5 插槽

属性

属性名	类型	默认值	描述
disabled	boolean	—	该组件是否已禁用。
placement	Placement	—	位置。
showArrow	boolean	—	是否显示箭头。
triggerProps	DropdownMenuTriggerProps	—	转发给触发元素的属性。
portalProps	DropdownMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	DropdownMenuContentProps	—	转发给内容元素的属性。
popupProps	DropdownMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	DropdownMenuArrowProps	—	转发给箭头元素的属性。
trigger	DropdownMenuTriggerType	'click'	下拉菜单的触发类型。 - `click`：点击触发器时，下拉菜单将展开。 - `hover`：将鼠标悬停在触发器上时，下拉菜单将展开。
delayDuration	number	150	从指针进入触发器到下拉菜单打开所花费的时间。
skipDelayDuration	number	300	用户在触发延迟之前，有多少时间可以输入另一个触发条件。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
open	boolean	undefined	对话框的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	false	对话框在初始渲染时的打开状态。当无需控制其打开状态时使用。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuCheckboxOptionData<T>[]	—	由该组件渲染的项。
groupLabelProps	DropdownMenuGroupLabelProps	—	转发至组标签元素的属性。
checkboxItemProps	DropdownMenuCheckboxItemProps	—	转发给复选框项元素的属性。
indicatorProps	DropdownMenuItemIndicatorProps	—	转发给 indicator 元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	DropdownMenuSeparatorProps	—	转发给分隔符元素的属性。
modelValue	T[]	—	复选框的受控值。可通过 v-model 进行绑定。
defaultValue	T[]	—	复选框在初始渲染时的值。当不需要控制其值时使用。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
update:open	boolean	当对话框的打开状态发生变化时调用的事件处理程序。
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
entryFocus	Event	在条目获得焦点时触发。
update:modelValue	T[]	当复选框组的值发生变化时调用的事件处理程序。
select	MenuCheckboxOptionData<T>, event: Event	在发生 select 事件时触发。

插槽

插槽名	参数	描述
item	MenuCheckboxOptionData<T>	项插槽的自定义内容。
item-leading	MenuCheckboxOptionData<T>	用于项目引导槽位的自定义内容。
item-trailing	MenuCheckboxOptionData<T>	用于项目尾部槽位的自定义内容。
item-indicator-icon	MenuCheckboxOptionData<T>	项目指示器图标槽位的自定义内容。
trigger	—	触发槽的自定义内容。

DropdownMenuCheckboxGroup

DropdownMenuCheckboxItem

DropdownMenuCompact<T>

26 属性9 事件6 插槽

属性

属性名	类型	默认值	描述
disabled	boolean	—	该组件是否已禁用。
placement	Placement	—	位置。
showArrow	boolean	—	是否显示箭头。
triggerProps	DropdownMenuTriggerProps	—	转发给触发元素的属性。
portalProps	DropdownMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	DropdownMenuContentProps	—	转发给内容元素的属性。
popupProps	DropdownMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	DropdownMenuArrowProps	—	转发给箭头元素的属性。
trigger	DropdownMenuTriggerType	'click'	下拉菜单的触发类型。 - `click`：点击触发器时，下拉菜单将展开。 - `hover`：将鼠标悬停在触发器上时，下拉菜单将展开。
delayDuration	number	150	从指针进入触发器到下拉菜单打开所花费的时间。
skipDelayDuration	number	300	用户在触发延迟之前，有多少时间可以输入另一个触发条件。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
open	boolean	undefined	对话框的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	false	对话框在初始渲染时的打开状态。当无需控制其打开状态时使用。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuOptionData<T>[]	—	由该组件渲染的项。
selectedValue	T	—	菜单中的选定值。
itemProps	DropdownMenuItemProps	—	转发给 item 元素的属性。
linkProps	LinkExtraProps	—	传递给 link 元素的属性。
subProps	DropdownMenuSubProps	—	转发给子元素的属性。
groupProps	DropdownMenuGroupProps	—	转发给 group 元素的属性。
groupLabelProps	DropdownMenuGroupLabelProps	—	转发至组标签元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	DropdownMenuSeparatorProps	—	转发给分隔符元素的属性。
subTriggerProps	DropdownMenuSubTriggerProps	—	转发给子触发器元素的属性。
subContentProps	DropdownMenuSubContentProps	—	转发至子内容元素的属性。

事件

事件名	参数	描述
update:open	boolean	当对话框的打开状态发生变化时调用的事件处理程序。
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
entryFocus	Event	在条目获得焦点时触发。
select	MenuOptionData<T>, event: Event	在发生 select 事件时触发。

插槽

插槽名	参数	描述
item	{ item: MenuOptionData<T>; isTrigger?: boolean; }	项插槽的自定义内容。
item-leading	{ item: MenuOptionData<T>; }	用于项目引导槽位的自定义内容。
item-trailing	{ item: MenuOptionData<T>; }	用于项目尾部槽位的自定义内容。
item-trigger-icon	{ item: MenuOptionData<T>; }	项目触发图标槽位的自定义内容。
item-link-icon	{ item: MenuOptionData<T>; }	项目链接图标槽位的自定义内容。
trigger	—	触发槽的自定义内容。

DropdownMenuContent

25 属性7 事件

属性

属性名	类型	默认值	描述
popupProps	DropdownMenuPopupProps	—	转发给弹出窗口元素的属性。
placement	Placement	undefined	浮动元素的位置。若使用该属性，它将覆盖 `side` 和 `align` 属性。
side	Side	'bottom'	打开时优先渲染的触发器一侧。当发生碰撞且 enableAvoidCollisions 启用时，该方向将被反转。
sideOffset	number	0	距触发器的像素距离。
sideFlip	boolean	true	遇到边界时，请翻转至另一侧。
align	Align	'center'	首选与触发条件保持一致。若发生冲突，则可能调整。
alignOffset	number	0	相对于 `start` 或 `end` 对齐选项的像素偏移量。
alignFlip	boolean	true	当与边界发生冲突时，翻转对齐方式。此情况仅在 `prioritizePosition` 为 true 时才会发生。
avoidCollisions	boolean	true	当值为 `true` 时，将覆盖“侧边”和“对齐”首选项，以避免与边界边缘发生冲突。
collisionBoundary	Element \| (Element \| null)[] \| null	[ ]	用作碰撞边界的元素。默认情况下，该边界为视口，但您可以提供额外的元素以纳入此检查范围。
collisionPadding	Padding	0	从边界边缘开始，碰撞检测应发生的距离（以像素为单位）。接受一个数字（所有边均相同），或一个部分填充对象，例如：{ top: 20, left: 20 }。
arrowPadding	number	0	箭头与内容边缘之间的间距。如果您的内容使用了 border-radius，这将防止内容溢出到角落。
hideShiftedArrow	boolean	true	当值为 `true` 时，若无法将箭头居中对齐到引用元素上，则隐藏该箭头。
sticky	'partial' \| 'always'	'partial'	在对齐轴上的“粘附”行为。`partial` 会在触发器至少部分位于边界内时将内容保留在边界内，而 “always” 则无论触发器是否位于边界内，都会将内容保留在边界内。
hideWhenDetached	boolean	false	当触发器被完全遮挡时，是否隐藏内容。
positionStrategy	'fixed' \| 'absolute'	'fixed'	要使用的 CSS `position` 属性的类型。
updatePositionStrategy	'always' \| 'optimized'	'optimized'	在每个动画帧中更新浮动元素位置的策略。
disableUpdateOnLayoutShift	boolean	false	当布局发生变化时，是否禁用内容的更新位置。
prioritizePosition	boolean	false	强制内容位于视口内。可能会与参考元素重叠，这可能并非预期效果。
reference	ReferenceElement	—	将作为浮动元素定位参考点的自定义元素或虚拟元素。如果提供了该元素，它将替换默认的锚点元素。
trapFocus	boolean	modal	弹出窗口打开时，焦点是否被困在其中（Tab 键在层内循环，且模态层的页面滚动被锁定）。
disableHoverableContent	boolean	false	当设置为 `true` 时，鼠标悬停会关闭弹出窗口而非保持其打开状态（宽限区域已禁用，因此离开触发区域会立即关闭该层）。
onGracePointerExit	(() => void)	—	当指针最终离开宽限区域时触发的回调。允许上层组件（例如 Tooltip）在无需注册自己的第二个宽限区域的情况下，执行区域范围内的关闭逻辑。
forceMount	boolean	—	用于在需要更多控制时强制挂载。在使用 Vue 动画库控制动画时非常有用。
loop	boolean	false	键盘导航是否应循环往复

事件

事件名	参数	描述
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
entryFocus	Event	在条目获得焦点时触发。

DropdownMenuGroup

DropdownMenuGroupLabel

DropdownMenuItem

DropdownMenuItemIndicator

DropdownMenuPortal

DropdownMenuRadio<T>

29 属性10 事件5 插槽

属性

属性名	类型	默认值	描述
class	((string \| false \| Record<string, any> \| ClassValue[]) & (string \| false \| Record<string, any> \| import("vue").ClassValue[])) \| null	—	菜单弹出窗口的类
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<DropdownMenuUi>	—	该组件的按槽类重写。
indicatorPosition	AlignSide	—	指示符位置。
disabled	boolean	—	该组件是否已禁用。
placement	Placement	—	位置。
showArrow	boolean	—	是否显示箭头。
triggerProps	DropdownMenuTriggerProps	—	转发给触发元素的属性。
portalProps	DropdownMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	DropdownMenuContentProps	—	转发给内容元素的属性。
popupProps	DropdownMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	DropdownMenuArrowProps	—	转发给箭头元素的属性。
trigger	DropdownMenuTriggerType	'click'	下拉菜单的触发类型。 - `click`：点击触发器时，下拉菜单将展开。 - `hover`：将鼠标悬停在触发器上时，下拉菜单将展开。
delayDuration	number	150	从指针进入触发器到下拉菜单打开所花费的时间。
skipDelayDuration	number	300	用户在触发延迟之前，有多少时间可以输入另一个触发条件。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
open	boolean	undefined	对话框的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	false	对话框在初始渲染时的打开状态。当无需控制其打开状态时使用。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuRadioOptionData<T>[]	—	由该组件渲染的项。
groupLabelProps	DropdownMenuGroupLabelProps	—	转发至组标签元素的属性。
radioItemProps	DropdownMenuRadioItemProps	—	转发给 radio item 元素的属性。
indicatorProps	DropdownMenuItemIndicatorProps	—	转发给 indicator 元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	DropdownMenuSeparatorProps	—	转发给分隔符元素的属性。
modelValue	T \| null	—	要选中的单选按钮项的控制值。可作为 `v-model` 进行绑定。
defaultValue	T	—	初始渲染时应选中的单选按钮选项的值。当您无需控制单选按钮选项的状态时使用此选项。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
update:open	boolean	当对话框的打开状态发生变化时调用的事件处理程序。
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
entryFocus	Event	在条目获得焦点时触发。
update:modelValue	Exclude<T, undefined> \| null	当单选按钮组值发生变化时调用的事件处理程序
select	MenuRadioOptionData<T>, event: Event	在发生 select 事件时触发。

插槽

插槽名	参数	描述
item	MenuRadioOptionData<T>	项插槽的自定义内容。
item-leading	MenuRadioOptionData<T>	用于项目引导槽位的自定义内容。
item-trailing	MenuRadioOptionData<T>	用于项目尾部槽位的自定义内容。
item-indicator-icon	MenuRadioOptionData<T>	项目指示器图标槽位的自定义内容。
trigger	—	触发槽的自定义内容。

DropdownMenuRadioCompact<T>

25 属性10 事件5 插槽

属性

属性名	类型	默认值	描述
disabled	boolean	—	该组件是否已禁用。
placement	Placement	—	位置。
showArrow	boolean	—	是否显示箭头。
triggerProps	DropdownMenuTriggerProps	—	转发给触发元素的属性。
portalProps	DropdownMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	DropdownMenuContentProps	—	转发给内容元素的属性。
popupProps	DropdownMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	DropdownMenuArrowProps	—	转发给箭头元素的属性。
trigger	DropdownMenuTriggerType	'click'	下拉菜单的触发类型。 - `click`：点击触发器时，下拉菜单将展开。 - `hover`：将鼠标悬停在触发器上时，下拉菜单将展开。
delayDuration	number	150	从指针进入触发器到下拉菜单打开所花费的时间。
skipDelayDuration	number	300	用户在触发延迟之前，有多少时间可以输入另一个触发条件。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
open	boolean	undefined	对话框的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	false	对话框在初始渲染时的打开状态。当无需控制其打开状态时使用。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuRadioOptionData<T>[]	—	由该组件渲染的项。
groupLabelProps	DropdownMenuGroupLabelProps	—	转发至组标签元素的属性。
radioItemProps	DropdownMenuRadioItemProps	—	转发给 radio item 元素的属性。
indicatorProps	DropdownMenuItemIndicatorProps	—	转发给 indicator 元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	DropdownMenuSeparatorProps	—	转发给分隔符元素的属性。
modelValue	T \| null	—	要选中的单选按钮项的控制值。可作为 `v-model` 进行绑定。
defaultValue	T	—	初始渲染时应选中的单选按钮选项的值。当您无需控制单选按钮选项的状态时使用此选项。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
update:open	boolean	当对话框的打开状态发生变化时调用的事件处理程序。
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
entryFocus	Event	在条目获得焦点时触发。
update:modelValue	Exclude<T, undefined> \| null	当单选按钮组值发生变化时调用的事件处理程序
select	MenuRadioOptionData<T>, event: Event	在发生 select 事件时触发。

插槽

插槽名	参数	描述
item	MenuRadioOptionData<T>	项插槽的自定义内容。
item-leading	MenuRadioOptionData<T>	用于项目引导槽位的自定义内容。
item-trailing	MenuRadioOptionData<T>	用于项目尾部槽位的自定义内容。
item-indicator-icon	MenuRadioOptionData<T>	项目指示器图标槽位的自定义内容。
trigger	—	触发槽的自定义内容。

DropdownMenuRadioGroup

DropdownMenuRadioItem

DropdownMenuRoot

7 属性1 事件

属性

属性名	类型	默认值	描述
trigger	DropdownMenuTriggerType	'click'	下拉菜单的触发类型。 - `click`：点击触发器时，下拉菜单将展开。 - `hover`：将鼠标悬停在触发器上时，下拉菜单将展开。
delayDuration	number	150	从指针进入触发器到下拉菜单打开所花费的时间。
skipDelayDuration	number	300	用户在触发延迟之前，有多少时间可以输入另一个触发条件。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
open	boolean	undefined	对话框的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	false	对话框在初始渲染时的打开状态。当无需控制其打开状态时使用。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。

事件

事件名	参数	描述
update:open	boolean	当对话框的打开状态发生变化时调用的事件处理程序。

DropdownMenuSeparator

DropdownMenuSub

DropdownMenuSubContent

DropdownMenuSubTrigger

DropdownMenuTrigger

4 属性

属性

属性名	类型	默认值	描述
type	ButtonType	'button'	按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。
disabled	boolean	—	该组件是否已禁用。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

DropdownMenuWrapper

19 属性8 事件

属性

属性名	类型	默认值	描述
class	ClassValue	—	菜单弹出窗口的类
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<DropdownMenuUi>	—	该组件的按槽类重写。
indicatorPosition	AlignSide	—	指示符位置。
disabled	boolean	—	该组件是否已禁用。
placement	Placement	—	位置。
showArrow	boolean	—	是否显示箭头。
triggerProps	DropdownMenuTriggerProps	—	转发给触发元素的属性。
portalProps	DropdownMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	DropdownMenuContentProps	—	转发给内容元素的属性。
popupProps	DropdownMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	DropdownMenuArrowProps	—	转发给箭头元素的属性。
trigger	DropdownMenuTriggerType	'click'	下拉菜单的触发类型。 - `click`：点击触发器时，下拉菜单将展开。 - `hover`：将鼠标悬停在触发器上时，下拉菜单将展开。
delayDuration	number	150	从指针进入触发器到下拉菜单打开所花费的时间。
skipDelayDuration	number	300	用户在触发延迟之前，有多少时间可以输入另一个触发条件。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
open	boolean	undefined	对话框的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	false	对话框在初始渲染时的打开状态。当无需控制其打开状态时使用。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。

事件

事件名	参数	描述
update:open	boolean	当对话框的打开状态发生变化时调用的事件处理程序。
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
entryFocus	Event	在条目获得焦点时触发。

DropdownMenuWrapperCompact

15 属性8 事件

属性

属性名	类型	默认值	描述
disabled	boolean	—	该组件是否已禁用。
placement	Placement	—	位置。
showArrow	boolean	—	是否显示箭头。
triggerProps	DropdownMenuTriggerProps	—	转发给触发元素的属性。
portalProps	DropdownMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	DropdownMenuContentProps	—	转发给内容元素的属性。
popupProps	DropdownMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	DropdownMenuArrowProps	—	转发给箭头元素的属性。
trigger	DropdownMenuTriggerType	'click'	下拉菜单的触发类型。 - `click`：点击触发器时，下拉菜单将展开。 - `hover`：将鼠标悬停在触发器上时，下拉菜单将展开。
delayDuration	number	150	从指针进入触发器到下拉菜单打开所花费的时间。
skipDelayDuration	number	300	用户在触发延迟之前，有多少时间可以输入另一个触发条件。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
open	boolean	undefined	对话框的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	false	对话框在初始渲染时的打开状态。当无需控制其打开状态时使用。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。

事件

事件名	参数	描述
update:open	boolean	当对话框的打开状态发生变化时调用的事件处理程序。
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
entryFocus	Event	在条目获得焦点时触发。

注意事项

架构与对标差异

下拉菜单家族在 popover portal 内组合共享 menu 基础组件（MenuOptions/MenuItem）；UI 包装组件只注入共享 menuVariants 类（经 provideMenuUi）并转发 prop/插槽。这与 radix-ui/shadcn-ui 的 headless menu 分离一致。Ant Design、Element Plus、Mantine、Naive UI 提供带 items/onSelect prop 的单一样式化下拉；VeanUI 额外提供专用复选/单选/自定义变体、size 尺寸体系，以及经共享 menu 层的完整键盘/类型过滤行为。

能力	VeanUI	shadcn/ui	Ant Design Dropdown	Element Plus Dropdown	Mantine Menu	Naive UI Dropdown
Aria/样式分离	✅	✅	—	—	—	—
数据驱动条目	✅	✅	✅	✅	✅	✅
复选 / 单选	✅	✅	—	—	✅	—
触发 click/hover	✅	✅	✅	✅	✅	✅
键盘 + 类型过滤	✅	✅	—	—	—	—
子菜单	✅	✅	✅	✅	✅	✅
尺寸（6）	✅	—	—	—	—	—

— = 不支持或采用不同交互模型。

运行时注意

SDropdownMenu 默认 modal（true）；传 modal={false} 获得轻量、非阻塞菜单。
trigger 接受 "click"（默认）或 "hover"；悬停时调节 delayDuration（打开）与 skipDelayDuration（触发间隔）。
items 为数据驱动；用对应条目插槽（item、item-leading、item-trailing）自定义渲染。
复选/单选变体用 v-model 绑定选择；单选期望单一值，复选期望数组。
菜单经 portal 渲染；仅在 portalProps: { disabled: true } 时置于相对定位的祖先内。

Roadmap

不适用——dropdown-menu 对当前对标集已功能完备。

FAQ

如何构建基础操作菜单？

传入 items 与 trigger 插槽：

<SDropdownMenu
  :items="[
    { value: 'edit', label: '编辑' },
    { value: 'delete', label: '删除', disabled: true }
  ]"
>
  <template #trigger><SButton>操作</SButton></template>
</SDropdownMenu>

如何使用复选（多选）变体？

使用带 v-model 的 SDropdownMenuCheckbox：

<SDropdownMenuCheckbox v-model="selected" :items="items">
  <template #trigger><SButton>筛选</SButton></template>
</SDropdownMenuCheckbox>

如何使用单选变体？

使用带 v-model 的 SDropdownMenuRadio：

<SDropdownMenuRadio v-model="sort" :items="sortOptions">
  <template #trigger><SButton>排序</SButton></template>
</SDropdownMenuRadio>

如何构建完全自定义的菜单？

使用 SDropdownMenuWrapper 并用 MenuItem 填充默认插槽：

<SDropdownMenuWrapper>
  <template #trigger><SButton>打开</SButton></template>
  <MenuItem value="a">条目 A</MenuItem>
  <MenuItem value="b">条目 B</MenuItem>
</SDropdownMenuWrapper>

如何在悬停时打开？

设置 trigger="hover" 并调整延迟：

<SDropdownMenu trigger="hover" :delay-duration="100" :items="items">
  <template #trigger><SButton>悬停</SButton></template>
</SDropdownMenu>

更新日志

版本记录按发布版本分组，便于快速查看这个组件在不同版本里的实际变更。

v0.40.0

2026-09-14

对比版本

修复

在触发、blur 和关闭事件中检查弹出窗口 ID 是否为空

范围: dropdown-menu作者: soybeanfe查看提交38f5e

修复

在触发、blur 和关闭事件中检查弹出窗口 ID 是否为空

范围: dropdown-menu作者: soybeanfe查看提交38f5e

v0.0.9

2026-01-02

对比版本

新功能

为 DropdownMenuWrapper 和 DropdownMenu 组件添加放置道具

范围: dropdown-menu作者: soybeanjs查看提交04e0b

v0.0.8

2026-01-01

对比版本

修复

为下拉菜单组件添加 popupProps 以增强功能

范围: dropdown-menu作者: soybeanjs查看提交ab340

重构

通过删除未使用的元素和更新引用来简化上下文管理，从而提高清晰度和功能性

范围: dropdown-menu作者: soybeanjs查看提交73ac1

v0.0.2

2025-11-18

对比版本

新功能

实现具有上下文管理和无障碍功能的下拉菜单组件

范围: dropdown-menu作者: soybeanjs查看提交96bcd

新功能

添加 DropdownMenuExample 组件并将其集成到 App.vue 中

范围: dropdown-menu作者: soybeanjs查看提交4a190

新功能

通过新增子菜单、复选框和单选按钮组来增强下拉菜单功能

范围: dropdown-menu作者: soybeanjs查看提交2a8e7

新功能

在下拉菜单触发器中添加 aria-disabled 属性，以提升无障碍访问性

范围: dropdown-menu作者: soybeanjs查看提交0da08

修复

更新 MenuAnchor 语法以提升与模板的兼容性

范围: dropdown-menu作者: soybeanjs查看提交6d96c

优化

从下拉菜单触发器中移除多余的 Slot 包装器，以使标记更简洁

范围: dropdown-menu作者: soybeanjs查看提交0d9f3

重构

通过引入 shallowRef 和 el-ref 绑定来增强内容元素的管理功能

范围: dropdown-menu作者: soybeanjs查看提交2c9ed

重构

实现带延时控制的悬停功能，以提升用户体验

范围: dropdown-menu作者: soybeanjs查看提交e24ef

新功能

在下拉菜单组件中添加 'disabledTrigger' 属性

范围: dropdown-menu作者: soybeanjs查看提交113cc

新功能

实现具有上下文管理和无障碍功能的下拉菜单组件

范围: dropdown-menu作者: soybeanjs查看提交96bcd

新功能

添加 DropdownMenuExample 组件并将其集成到 App.vue 中

范围: dropdown-menu作者: soybeanjs查看提交4a190

新功能

通过新增子菜单、复选框和单选按钮组来增强下拉菜单功能

范围: dropdown-menu作者: soybeanjs查看提交2a8e7

新功能

在下拉菜单触发器中添加 aria-disabled 属性，以提升无障碍访问性

范围: dropdown-menu作者: soybeanjs查看提交0da08

修复

更新 MenuAnchor 语法以提升与模板的兼容性

范围: dropdown-menu作者: soybeanjs查看提交6d96c

优化

在下拉菜单组件示例中添加尺寸选择功能

范围: dropdown-menu作者: soybeanjs查看提交75f3c

优化

从下拉菜单触发器中移除多余的 Slot 包装器，以使标记更简洁

范围: dropdown-menu作者: soybeanjs查看提交0d9f3

重构

通过引入 shallowRef 和 el-ref 绑定来增强内容元素的管理功能

范围: dropdown-menu作者: soybeanjs查看提交2c9ed

重构

实现带延时控制的悬停功能，以提升用户体验

范围: dropdown-menu作者: soybeanjs查看提交e24ef

新功能

在下拉菜单组件中添加 'disabledTrigger' 属性

范围: dropdown-menu作者: soybeanjs查看提交113cc

优化

在下拉菜单组件示例中添加尺寸选择功能

范围: dropdown-menu作者: soybeanjs查看提交75f3c