右键菜单

概述

在指针位置显示的菜单，通过右键触发。SContextMenu 是基于共享 Aria menu 基础组件构建的数据驱动菜单，经 contextmenu 事件在指针位置打开（触屏上也可长按，经 pressOpenDelay）。家族还提供复选（SContextMenuCheckbox）、单选（SContextMenuRadio）与自定义（SContextMenuWrapper）变体。

右键菜单适合指针相关的操作（文件、画布、树节点）。按钮触发的菜单请用 dropdown-menu；丰富的悬停预览请用 hover-card。

用法

特性

🖱️ 右键触发 — 经 contextmenu 事件在指针位置打开；event.preventDefault() 阻止原生菜单
📱 长按触发 — pressOpenDelay（默认 700ms）在触屏/触控笔上长按打开
🧩 基于 Aria menu — 构建于共享 menu 基础组件，带完整键盘导航、类型过滤与 roving focus
📊 数据驱动 — 传入 items（含 value/label/icon/disabled/hidden/separator…）或使用条目插槽
🙈 隐藏项 — 条目标记 hidden 后（连同整棵子树）不会出现在菜单中
☑️ 复选 / 🔘 单选变体 — SContextMenuCheckbox/SContextMenuRadio 用于可选择的菜单
🧩 自定义变体 — SContextMenuWrapper 用于完全自定义菜单内容
🎭 模态 — modal 控制外部指针拦截与焦点陷阱
♿ 无障碍 — role="menu"/menuitem、复选/单选 aria-checked、axe-core 零违规

组件家族

SContextMenu（样式层）— 数据驱动菜单；转发至 ContextMenuCompact
SContextMenuCheckbox / SContextMenuRadio（样式层）— 带 v-model 的可选择菜单
SContextMenuWrapper（样式层）— 自定义内容菜单
ContextMenuCompact / ContextMenuWrapperCompact / ContextMenuCheckboxCompact / ContextMenuRadioCompact（Aria）— 聚合组件
ContextMenuRoot / ContextMenuTrigger / ContextMenuContent（Aria）— 指针锚定的触发器与菜单表面
MenuOptions/MenuItem/…（Aria）— 共享 menu 基础组件

演示

基础

100%

Right click here

复选

100%

Right click here

单选

100%

Right click here

混合

100%

Right click here

API

Aria 层

ContextMenu<T>

24 属性9 事件6 插槽

属性

属性名	类型	默认值	描述
class	ClassValue	—	菜单弹出窗口的类
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<ContextMenuUi>	—	该组件的按槽类重写。
disabled	boolean	—	该组件是否已禁用。
showArrow	boolean	—	是否显示箭头。
triggerProps	ContextMenuTriggerProps	—	转发给触发元素的属性。
portalProps	ContextMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	ContextMenuContentProps	—	转发给内容元素的属性。
popupProps	ContextMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	ContextMenuArrowProps	—	转发给箭头元素的属性。
pressOpenDelay	number	700	从按下触发器到菜单打开所需的时间。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuOptionData<T>[]	—	由该组件渲染的项。
selectedValue	T	—	菜单中的选定值。
itemProps	ContextMenuItemProps	—	转发给 item 元素的属性。
linkProps	LinkExtraProps	—	传递给 link 元素的属性。
subProps	ContextMenuSubProps	—	转发给子元素的属性。
groupProps	ContextMenuGroupProps	—	转发给 group 元素的属性。
groupLabelProps	ContextMenuGroupLabelProps	—	转发至组标签元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	ContextMenuSeparatorProps	—	转发给分隔符元素的属性。
subTriggerProps	ContextMenuSubTriggerProps	—	转发给子触发器元素的属性。
subContentProps	ContextMenuSubContentProps	—	转发至子内容元素的属性。

事件

事件名	参数	描述
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	—	触发槽的自定义内容。

ContextMenuAnchor

ContextMenuArrow

ContextMenuCheckbox<T>

24 属性10 事件5 插槽

属性

属性名	类型	默认值	描述
class	((string \| false \| Record<string, any> \| ClassValue[]) & (string \| false \| Record<string, any> \| import("vue").ClassValue[])) \| null	—	菜单弹出窗口的类
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<ContextMenuUi>	—	该组件的按槽类重写。
indicatorPosition	AlignSide	—	指示符位置。
disabled	boolean	—	该组件是否已禁用。
showArrow	boolean	—	是否显示箭头。
triggerProps	ContextMenuTriggerProps	—	转发给触发元素的属性。
portalProps	ContextMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	ContextMenuContentProps	—	转发给内容元素的属性。
popupProps	ContextMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	ContextMenuArrowProps	—	转发给箭头元素的属性。
pressOpenDelay	number	700	从按下触发器到菜单打开所需的时间。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuCheckboxOptionData<T>[]	—	由该组件渲染的项。
groupLabelProps	ContextMenuGroupLabelProps	—	转发至组标签元素的属性。
checkboxItemProps	ContextMenuCheckboxItemProps	—	转发给复选框项元素的属性。
indicatorProps	ContextMenuItemIndicatorProps	—	转发给 indicator 元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	ContextMenuSeparatorProps	—	转发给分隔符元素的属性。
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	—	触发槽的自定义内容。

ContextMenuCheckboxCompact<T>

20 属性10 事件5 插槽

属性

属性名	类型	默认值	描述
disabled	boolean	—	该组件是否已禁用。
showArrow	boolean	—	是否显示箭头。
triggerProps	ContextMenuTriggerProps	—	转发给触发元素的属性。
portalProps	ContextMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	ContextMenuContentProps	—	转发给内容元素的属性。
popupProps	ContextMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	ContextMenuArrowProps	—	转发给箭头元素的属性。
pressOpenDelay	number	700	从按下触发器到菜单打开所需的时间。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuCheckboxOptionData<T>[]	—	由该组件渲染的项。
groupLabelProps	ContextMenuGroupLabelProps	—	转发至组标签元素的属性。
checkboxItemProps	ContextMenuCheckboxItemProps	—	转发给复选框项元素的属性。
indicatorProps	ContextMenuItemIndicatorProps	—	转发给 indicator 元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	ContextMenuSeparatorProps	—	转发给分隔符元素的属性。
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	—	触发槽的自定义内容。

ContextMenuCheckboxGroup<T>

ContextMenuCheckboxItem

ContextMenuCompact<T>

21 属性9 事件6 插槽

属性

属性名	类型	默认值	描述
disabled	boolean	—	该组件是否已禁用。
showArrow	boolean	—	是否显示箭头。
triggerProps	ContextMenuTriggerProps	—	转发给触发元素的属性。
portalProps	ContextMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	ContextMenuContentProps	—	转发给内容元素的属性。
popupProps	ContextMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	ContextMenuArrowProps	—	转发给箭头元素的属性。
pressOpenDelay	number	700	从按下触发器到菜单打开所需的时间。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuOptionData<T>[]	—	由该组件渲染的项。
selectedValue	T	—	菜单中的选定值。
itemProps	ContextMenuItemProps	—	转发给 item 元素的属性。
linkProps	LinkExtraProps	—	传递给 link 元素的属性。
subProps	ContextMenuSubProps	—	转发给子元素的属性。
groupProps	ContextMenuGroupProps	—	转发给 group 元素的属性。
groupLabelProps	ContextMenuGroupLabelProps	—	转发至组标签元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	ContextMenuSeparatorProps	—	转发给分隔符元素的属性。
subTriggerProps	ContextMenuSubTriggerProps	—	转发给子触发器元素的属性。
subContentProps	ContextMenuSubContentProps	—	转发至子内容元素的属性。

事件

事件名	参数	描述
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	—	触发槽的自定义内容。

ContextMenuContent

20 属性7 事件

属性

属性名	类型	默认值	描述
loop	boolean	false	键盘导航是否应循环往复
placement	Placement	undefined	浮动元素的位置。若使用该属性，它将覆盖 `side` 和 `align` 属性。
popupProps	ContextMenuPopupProps	—	转发给弹出窗口元素的属性。
sideFlip	boolean	true	遇到边界时，请翻转至另一侧。
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 }。
hideShiftedArrow	boolean	true	当值为 `true` 时，若无法将箭头居中对齐到引用元素上，则隐藏该箭头。
sticky	'partial' \| 'always'	'partial'	在对齐轴上的“粘附”行为。`partial` 会在触发器至少部分位于边界内时将内容保留在边界内，而 “always” 则无论触发器是否位于边界内，都会将内容保留在边界内。
hideWhenDetached	boolean	false	当触发器被完全遮挡时，是否隐藏内容。
positionStrategy	'fixed' \| 'absolute'	'fixed'	要使用的 CSS `position` 属性的类型。
disableUpdateOnLayoutShift	boolean	false	当布局发生变化时，是否禁用内容的更新位置。
prioritizePosition	boolean	false	强制内容位于视口内。可能会与参考元素重叠，这可能并非预期效果。
reference	ReferenceElement	—	将作为浮动元素定位参考点的自定义元素或虚拟元素。如果提供了该元素，它将替换默认的锚点元素。
trapFocus	boolean	modal	弹出窗口打开时，焦点是否被困在其中（Tab 键在层内循环，且模态层的页面滚动被锁定）。
disableHoverableContent	boolean	false	当设置为 `true` 时，鼠标悬停会关闭弹出窗口而非保持其打开状态（宽限区域已禁用，因此离开触发区域会立即关闭该层）。
onGracePointerExit	(() => void)	—	当指针最终离开宽限区域时触发的回调。允许上层组件（例如 Tooltip）在无需注册自己的第二个宽限区域的情况下，执行区域范围内的关闭逻辑。
forceMount	boolean	—	用于在需要更多控制时强制挂载。在使用 Vue 动画库控制动画时非常有用。

事件

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

ContextMenuGroup

ContextMenuGroupLabel

ContextMenuItem

ContextMenuItemIndicator

ContextMenuPortal

ContextMenuRadio<T>

24 属性10 事件5 插槽

属性

属性名	类型	默认值	描述
class	((string \| false \| Record<string, any> \| ClassValue[]) & (string \| false \| Record<string, any> \| import("vue").ClassValue[])) \| null	—	菜单弹出窗口的类
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<ContextMenuUi>	—	该组件的按槽类重写。
indicatorPosition	AlignSide	—	指示符位置。
disabled	boolean	—	该组件是否已禁用。
showArrow	boolean	—	是否显示箭头。
triggerProps	ContextMenuTriggerProps	—	转发给触发元素的属性。
portalProps	ContextMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	ContextMenuContentProps	—	转发给内容元素的属性。
popupProps	ContextMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	ContextMenuArrowProps	—	转发给箭头元素的属性。
pressOpenDelay	number	700	从按下触发器到菜单打开所需的时间。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuRadioOptionData<T>[]	—	由该组件渲染的项。
groupLabelProps	ContextMenuGroupLabelProps	—	转发至组标签元素的属性。
radioItemProps	ContextMenuRadioItemProps	—	转发给 radio item 元素的属性。
indicatorProps	ContextMenuItemIndicatorProps	—	转发给 indicator 元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	ContextMenuSeparatorProps	—	转发给分隔符元素的属性。
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	—	触发槽的自定义内容。

ContextMenuRadioCompact<T>

20 属性10 事件5 插槽

属性

属性名	类型	默认值	描述
disabled	boolean	—	该组件是否已禁用。
showArrow	boolean	—	是否显示箭头。
triggerProps	ContextMenuTriggerProps	—	转发给触发元素的属性。
portalProps	ContextMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	ContextMenuContentProps	—	转发给内容元素的属性。
popupProps	ContextMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	ContextMenuArrowProps	—	转发给箭头元素的属性。
pressOpenDelay	number	700	从按下触发器到菜单打开所需的时间。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。
items	MenuRadioOptionData<T>[]	—	由该组件渲染的项。
groupLabelProps	ContextMenuGroupLabelProps	—	转发至组标签元素的属性。
radioItemProps	ContextMenuRadioItemProps	—	转发给 radio item 元素的属性。
indicatorProps	ContextMenuItemIndicatorProps	—	转发给 indicator 元素的属性。
shortcutProps	MenuShortcutProps	—	转发给快捷方式元素的属性。
separatorProps	ContextMenuSeparatorProps	—	转发给分隔符元素的属性。
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	—	触发槽的自定义内容。

ContextMenuRadioGroup<T>

ContextMenuRadioItem

ContextMenuRoot

3 属性1 事件

属性

属性名	类型	默认值	描述
pressOpenDelay	number	700	从按下触发器到菜单打开所需的时间。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
modal	boolean	true	对话框的模态属性。当设置为 `true` 时，将禁用与外部元素的交互，屏幕阅读器仅能读取对话框内容。

事件

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

ContextMenuSeparator

ContextMenuSub

ContextMenuSubContent

ContextMenuSubTrigger

ContextMenuTrigger

5 属性

属性

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

ContextMenuWrapper

14 属性8 事件

属性

属性名	类型	默认值	描述
class	ClassValue	—	菜单弹出窗口的类
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<ContextMenuUi>	—	该组件的按槽类重写。
indicatorPosition	AlignSide	—	指示符位置。
disabled	boolean	—	该组件是否已禁用。
showArrow	boolean	—	是否显示箭头。
triggerProps	ContextMenuTriggerProps	—	转发给触发元素的属性。
portalProps	ContextMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	ContextMenuContentProps	—	转发给内容元素的属性。
popupProps	ContextMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	ContextMenuArrowProps	—	转发给箭头元素的属性。
pressOpenDelay	number	700	从按下触发器到菜单打开所需的时间。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
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	在条目获得焦点时触发。

ContextMenuWrapperCompact

10 属性8 事件

属性

属性名	类型	默认值	描述
disabled	boolean	—	该组件是否已禁用。
showArrow	boolean	—	是否显示箭头。
triggerProps	ContextMenuTriggerProps	—	转发给触发元素的属性。
portalProps	ContextMenuPortalProps	—	转发给 portal 元素的属性。
contentProps	ContextMenuContentProps	—	转发给内容元素的属性。
popupProps	ContextMenuPopupProps	—	转发给弹出窗口元素的属性。
arrowProps	ContextMenuArrowProps	—	转发给箭头元素的属性。
pressOpenDelay	number	700	从按下触发器到菜单打开所需的时间。
dir	Direction	—	如适用，请指定下拉列表的阅读方向。若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
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 基础组件；UI 包装组件只注入共享 menuVariants 类（经 provideMenuUi）并转发 prop/插槽。这与 radix-ui/shadcn-ui 的 headless menu 分离一致。Ant Design、Element Plus、Mantine、Naive UI 提供单一样式化右键菜单（或复用其下拉的 trigger="contextmenu"）；VeanUI 额外提供复选/单选/自定义变体、size 尺寸体系，以及经共享 menu 层的完整键盘/类型过滤行为。

能力	VeanUI	shadcn/ui	Ant Design	Element Plus	Mantine	Naive UI
指针定位	✅	✅	✅	✅	✅	✅
右键触发	✅	✅	✅	✅	✅	✅
长按（触屏）	✅	✅	—	—	—	—
复选 / 单选	✅	✅	—	—	✅	—
键盘 + 类型过滤	✅	✅	—	—	—	—
尺寸（6）	✅	—	—	—	—	—

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

运行时注意

菜单经 contextmenu 在指针位置打开；pressOpenDelay 控制触屏长按（默认 700ms）。
SContextMenu 默认 modal（true）；传 modal={false} 获得轻量菜单。
items 为数据驱动；用对应条目插槽（item、item-leading、item-trailing）自定义渲染。
复选/单选变体用 v-model 绑定选择；单选期望单一值，复选期望数组。
菜单经 portal 在指针位置渲染；右键时 event.preventDefault() 抑制浏览器原生菜单。

Roadmap

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

FAQ

如何构建基础右键菜单？

传入 items 并包裹一个触发区域：

<SContextMenu
  :items="[
    { value: 'copy', label: '复制' },
    { value: 'paste', label: '粘贴' },
    { type: 'separator' },
    { value: 'delete', label: '删除', disabled: true }
  ]"
>
  <div class="target">在此右键</div>
</SContextMenu>

如何在触屏上长按打开？

调整 press-open-delay：

<SContextMenu :press-open-delay="500" :items="items">
  <div class="target">长按打开</div>
</SContextMenu>

如何使用复选/单选变体？

使用带 v-model 的 SContextMenuCheckbox/SContextMenuRadio：

<SContextMenuCheckbox v-model="selected" :items="items">
  <div class="target">右键</div>
</SContextMenuCheckbox>

如何构建自定义菜单？

使用 SContextMenuWrapper 与 MenuItem：

<SContextMenuWrapper>
  <div class="target">右键</div>
  <MenuItem value="a">条目 A</MenuItem>
  <MenuItem value="b">条目 B</MenuItem>
</SContextMenuWrapper>

快速跳转

同分类组件

右键菜单

概述

用法

特性

组件家族

演示

基础

复选

单选

混合

API

Aria 层

ContextMenu<T>

属性

事件

插槽

ContextMenuAnchor

ContextMenuArrow

ContextMenuCheckbox<T>

属性

事件

插槽

ContextMenuCheckboxCompact<T>

属性

事件

插槽

ContextMenuCheckboxGroup<T>

ContextMenuCheckboxItem

ContextMenuCompact<T>

属性

事件

插槽

ContextMenuContent

属性

事件

ContextMenuGroup

ContextMenuGroupLabel

ContextMenuItem

ContextMenuItemIndicator

ContextMenuPortal

ContextMenuRadio<T>

属性

事件

插槽

ContextMenuRadioCompact<T>

属性

事件

插槽

ContextMenuRadioGroup<T>

ContextMenuRadioItem

ContextMenuRoot

属性

事件

ContextMenuSeparator

ContextMenuSub

ContextMenuSubContent

ContextMenuSubTrigger

ContextMenuTrigger

属性

ContextMenuWrapper

属性

事件

ContextMenuWrapperCompact

属性

事件

注意事项

架构与对标差异

运行时注意

Roadmap

FAQ

如何构建基础右键菜单？

如何在触屏上长按打开？

如何使用复选/单选变体？

如何构建自定义菜单？

更新日志

v0.50.0

修复

修复