radix-vue 子菜单完全指南ContextMenuSub 的受控状态、嵌套层级与交互原理【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue本篇技术指南聚焦 radix-vue原 Radix Vue现文档中以reka-ui包名发布无障碍 UI 组件库中的ContextMenuSub及其配套部件ContextMenuSubTrigger、ContextMenuSubContent。子菜单是右键上下文菜单中最常用的进阶结构本文将从 API 属性、受控/非受控状态管理、嵌套层级组合到源码层级的展开/收起交互原理悬停延迟、指针宽限区、方向键、RTL做系统拆解读完即可在真实项目中落地一个完整、可嵌套、键盘可访问的子菜单。ContextMenuSub 是什么在 radix-vue 中右键上下文菜单由ContextMenuRoot统领ContextMenuSub则用于在当前菜单内部再派生出一层二级乃至多级菜单。根据 ContextMenu 官方文档 的定义ContextMenuSubContains all the parts of a submenu即包含一个子菜单的所有部件通常需要与以下两个部件配合部件作用ContextMenuSubTrigger一个可以打开子菜单的菜单项必须渲染在ContextMenu.Sub内部ContextMenuSubContent子菜单打开时弹出的内容面板必须渲染在ContextMenu.Sub内部三者缺一不可ContextMenuSub负责维护子菜单的开合状态并向下传递上下文SubTrigger是触发入口SubContent是弹出的面板容器。核心 API 一览ContextMenuSub的完整 API 由 ContextMenuSub.md 定义其本质是基础菜单MenuSub的一层薄封装见 ContextMenuSub.vue仅额外补充defaultOpen属性。完整清单如下PropsNameDescriptionTypeRequiredDefaultdefaultOpenThe open state of the submenu when it is initially rendered. Use when you do not need to control its open state.booleanNo-openThe controlled open state of the menu. Can be used as v-model:open.booleanNo-EventsNameDescriptionTypeupdate:openEvent handler called when the open state of the submenu changes.[payload: boolean]SlotsNameDescriptionTypeopenCurrent open stateboolean受控与非受控两种模式非受控只传defaultOpen子菜单的展开/收起由内部状态自行管理。例如ContextMenuSub default-open表示首次渲染时默认展开。受控通过v-model:open绑定布尔值父组件完全接管开合状态可据此实现展开子菜单时联动关闭其他菜单等业务逻辑script setup langts import { ref } from vue const subOpen ref(false) /script template ContextMenuSub v-model:opensubOpen ContextMenuSubTriggerMore Tools/ContextMenuSubTrigger ContextMenuPortal ContextMenuSubContent ContextMenuItemSave Page As…/ContextMenuItem /ContextMenuSubContent /ContextMenuPortal /ContextMenuSub /template从源码看这两种模式由useVModel统一收敛在 MenuSub.vue 中open以props.open undefined判断是否为受控非受控时回退到默认值false在ContextMenuSub层则以props.defaultOpen作为初始默认值见 ContextMenuSub.vue。作用域插槽访问当前开合状态ContextMenuSub暴露一个默认插槽参数为当前的open布尔值。你可以利用它在不引入额外响应式变量的情况下完成联动渲染例如给子菜单触发器动态切换箭头图标方向ContextMenuSub v-slot{ open } ContextMenuSubTrigger More Tools ChevronRightIcon :classopen ? rotate-90 : / /ContextMenuSubTrigger ContextMenuPortal ContextMenuSubContent…/ContextMenuSubContent /ContextMenuPortal /ContextMenuSub完整实战示例三级嵌套子菜单仓库自带的 story 演示packages/core/src/ContextMenu/story/_ContextMenu.vue以及 官方文档示例 给出了子菜单的完整组合方式——注意子菜单面板同样需要包在ContextMenuPortal中且SubContent支持继续嵌套下一级ContextMenuSub从而实现多级级联script setup langts import { ContextMenuContent, ContextMenuItem, ContextMenuPortal, ContextMenuRoot, ContextMenuSeparator, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, } from reka-ui /script template ContextMenuRoot ContextMenuTriggerRight click here./ContextMenuTrigger ContextMenuPortal ContextMenuContent :side-offset5 ContextMenuItemNew Tab/ContextMenuItem ContextMenuItemNew Window/ContextMenuItem ContextMenuSeparator / ContextMenuSub ContextMenuSubTrigger More Tools ChevronRightIcon / /ContextMenuSubTrigger ContextMenuPortal ContextMenuSubContent :side-offset2 :align-offset-5 ContextMenuItemSave Page As…/ContextMenuItem ContextMenuItemCreate Shortcut…/ContextMenuItem ContextMenuSeparator / !-- 支持无限层级嵌套 -- ContextMenuSub ContextMenuSubTriggerAdvanced/ContextMenuSubTrigger ContextMenuPortal ContextMenuSubContent ContextMenuItemDeveloper Tools/ContextMenuItem /ContextMenuSubContent /ContextMenuPortal /ContextMenuSub ContextMenuArrow / /ContextMenuSubContent /ContextMenuPortal /ContextMenuSub ContextMenuSeparator / ContextMenuItemExit/ContextMenuItem /ContextMenuContent /ContextMenuPortal /ContextMenuRoot /template注意示例中ContextMenuSubContent通过:side-offset与:align-offset微调面板与触发器的间距和对齐偏移这是子菜单悬浮定位最常用的两个样式参数。状态与数据属性无障碍样式的基石radix-vue 的无障碍设计依赖data-*属性向 CSS 暴露内部状态子菜单的触发器与面板分别暴露不同的属性集合见 文档 DataAttributesTable。ContextMenuSubTrigger 数据属性AttributeValues[data-state]open,closed[data-highlighted]Present when highlighted[data-disabled]Present when disabledContextMenuSubContent 数据属性AttributeValues[data-state]open,closed[data-side]left,right,bottom,top[data-align]start,end,center在 story 演示中可以看到这些属性的典型用法例如给触发器的高亮与展开态叠加样式/* 触发项被键盘高亮时 */ .data-[highlighted]:bg-violet9 /* 子菜单展开时 */ .data-[stateopen]:bg-violet4 /* 面板出现在不同方向时的入场动画 */ .data-[sideright]:animate-slideLeftAndFade面板侧边计算逻辑在 MenuSubContent.vue 中写死为siderightRTL 环境为left、alignstart即子菜单面板默认向右弹出、与触发器顶部对齐因此data-side的取值会随视口边界自动在left/right间切换。源码视角子菜单的交互原理ContextMenuSub系列组件在实现上全部转发给Menu模块的基础实现因此其交互行为与DropdownMenu、Menubar的子菜单完全一致。下面拆解三个关键机制。1. 悬停 100ms 延迟打开 300ms 指针宽限区在 MenuSubTrigger.vue 中鼠标移入触发器并不会立即展开子菜单而是启动一个 100ms 的定时器后再调用menuContext.onOpenChange(true)鼠标移出时则先清理该定时器并基于当前内容面板的矩形区域构造一个指针宽限区pointer grace area——当鼠标从触发器移向面板的路径穿过该区域时即使暂时脱离了触发器也不会立刻收起子菜单宽限区在 300ms 后失效。这套机制保证了鼠标从触发器斜向移入面板的经典操作路径不会造成面板闪烁关闭。2. 方向键开合与焦点管理展开在 handleKeyDown 中按下SUB_OPEN_KEYS[dir]LTR 为ArrowRightRTL 为ArrowLeft会打开子菜单并在nextTick后将焦点移入内容面板保证纯键盘用户的操作连续性。收起面板内的keydown处理见 MenuSubContent.vue监听SUB_CLOSE_KEYS[dir]LTR 为ArrowLeft命中后将焦点交还给SubTrigger并调用scrollIntoView({ block: nearest })确保触发器在视口内可见。Escescape-key-down中调用rootContext.onClose()并preventDefault保证在子菜单中按 Esc 不会连带触发浏览器全屏退出等副作用。焦点移出focus-outside处理会放行焦点回到触发器和焦点进入父级菜单过滤元素这两种情况避免指针交互时触发重复的打开动画见 MenuSubContent.vue。3. 父菜单关闭时自动收起MenuSub.vue 中通过watchEffect监听父级MenuContext.open一旦父菜单关闭子菜单的open会被强制重置为false并在清理函数中再次兜底置空避免出现父菜单已关闭、子菜单仍悬浮的脏状态。4. Popper 定位与 CSS 变量透传MenuSub用PopperRoot包裹子菜单内容MenuSub.vue而 ContextMenuSubContent.vue 在转发属性时将 Popper 计算出的五个定位值映射为--reka-context-menu-*系列 CSS 变量供开发者实现跟随触发器与箭头位置的入场动画。ContextMenuSubContent 暴露的 CSS 变量CSS VariableDescription--reka-context-menu-content-transform-originThetransform-origincomputed from the content and arrow positions/offsets--reka-context-menu-content-available-widthThe remaining width between the trigger and the boundary edge--reka-context-menu-content-available-heightThe remaining height between the trigger and the boundary edge--reka-context-menu-trigger-widthThe width of the trigger--reka-context-menu-trigger-heightThe height of the trigger键盘交互一览根据 文档 KeyboardTable与子菜单相关的完整键盘约定如下KeysDescriptionSpace/EnterActivates the focused item.ArrowDown/ArrowUpMoves focus to the next / previous item.ArrowRight/ArrowLeftWhen focus is onContextMenu.SubTrigger, opens or closes the submenu depending on reading direction.EscCloses the context menu其中ArrowRight/ArrowLeft的方向语义会随dir阅读方向翻转源码中SUB_OPEN_KEYS/SUB_CLOSE_KEYS正是依据 MenuRoot 的 dir 配置 在 LTR 与 RTL 两套键位间切换这是国际化应用必须留意的细节。小结与延伸阅读ContextMenuSub是一个小而精的组合式部件对外只暴露open、defaultOpen两个属性与一个作用域插槽却通过转发Menu模块的成熟实现获得了悬停延迟、指针宽限、焦点管理与 RTL 适配等全套无障碍交互能力。建议在实际项目中遵循官方推荐结构——ContextMenuSub包裹SubTrigger与Portal SubContent并将菜单项继续放入SubContent中实现级联。可继续深入阅读的仓库资料完整组件 APIdocs/content/meta/ContextMenuSub.md、ContextMenuSubTrigger 元数据、ContextMenuSubContent 元数据官方组件文档与示例docs/content/docs/components/context-menu.md运行时演示含嵌套子菜单packages/core/src/ContextMenu/story/_ContextMenu.vue基础实现packages/core/src/Menu/MenuSub.vue、MenuSubTrigger.vue、MenuSubContent.vueContextMenu 层封装packages/core/src/ContextMenu/ContextMenuSub.vue【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
