组件 · 导航
Menubar 菜单栏
桌面式菜单栏。
使用建议
- 避免：移动端强行使用密集 Menubar
- 限制：属性与导出以 @selrux/ui 对应子路径 d.ts/源码为准，禁止臆造
引入
import {
Menubar,
MenubarCheckboxItem,
MenubarContent,
MenubarGroup,
MenubarItem,
MenubarLabel,
// …共 16 个导出
} from '@selrux/ui/menubar';演练场
调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。
代码演示
基础用法
桌面应用式菜单栏，点击触发器打开菜单，方向键在菜单间移动。
受控菜单栏
value / onValueChange 受控当前打开的菜单（null 为全部关闭）；MenubarMenu 的 value 标识菜单、onOpenChange、disabled、loop、closeOnEscape、closeOnOutsidePress；size 尺寸。
勾选、单选与子菜单
CheckboxItem 的 checked / onCheckedChange、disabled、inset、onAction、closeOnAction；RadioGroup + RadioItem（value / textValue / disabled / inset / onAction / closeOnAction）；Label 的 inset；Sub / SubTrigger / SubContent 嵌套。
API
属性覆盖：示例用到 48 / 49 个自有属性（98%）
由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。
MenubarContent.container：Portal 挂载目标，默认 body；文档页无需更换挂载点MenubarMenu.returnFocusRef：焦点目标 ref，效果不可见；行为见“无障碍”MenubarPortal.container：Portal 挂载目标，默认 body；文档页无需更换挂载点MenubarSubContent.container：Portal 挂载目标，默认 body；文档页无需更换挂载点
Menubar
主题化顶栏菜单根。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
size | 菜单字号与项内距；省略取 Provider → md。 | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | - |
value | 受控：当前打开菜单的 value。 | string | null | - |
defaultValue | 非受控默认打开菜单。 | string | null | - |
onValueChange | 打开菜单变更。 | ((value: string | null) => void) | - |
另有 278 项原生属性与事件继承自 HTMLAttributes，原样透传。
MenubarCheckboxItem
主题化勾选项；内置指示器。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
textValue * | typeahead 文本。 | string | - |
defaultChecked | 非受控默认选中。 | boolean | - |
disabled | 禁用。 | boolean | - |
inset | 起步缩进。 | boolean | - |
onAction | 可选；在 checked 变更后通知。 | ((details: MenuActionDetails) => void) | - |
closeOnAction | 默认 false，保持菜单打开。 | boolean | false |
checked | 受控选中。 | boolean | - |
onCheckedChange | 选中变更。 | ((checked: boolean, details: MenuActionDetails) => void) | - |
children | 可见内容。 | ReactNode | - |
另有 283 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。
MenubarContent
主题化内容面：默认自带 Portal + 域镜像（对齐 shadcn MenubarContent）。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
container | Portal 挂载点；省略默认 body。 | PortalContainerInput | body |
side | 物理四向；根默认 bottom，子默认逻辑外向。 | "top" | "bottom" | "left" | "right" | bottom |
align | 对齐；默认 start。 | "start" | "end" | "center" | start |
sideOffset | 侧向间距（CSS px）。 | number | - |
collisionPadding | 碰撞内边距（CSS px）。 | number | - |
onEscapeKeyDown | Esc；preventDefault 取消关闭。 | ((event: KeyboardEvent) => void) | - |
onPointerDownOutside | 外部主指针；preventDefault 取消关闭。 | ((event: Event) => void) | - |
style | 普通样式；受管定位不可绕过。 | CSSProperties | - |
ref | 转发到内容根。
Allows getting a ref to the component instance.
Once the component unmounts, React will set ref.current to null
(or call the ref with null if you passed a callback ref). | Ref<HTMLDivElement> | - |
children | 菜单面子树。 | ReactNode | - |
另有 276 项原生属性与事件继承自 HTMLAttributes，原样透传。
MenubarGroup
主题化分组。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
children | 组内容。 | ReactNode | - |
另有 278 项原生属性与事件继承自 HTMLAttributes，原样透传。
MenubarItem
主题化动作项；支持 destructive / inset。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
textValue * | 可访问名与 typeahead 来源；必填非空。 | string | - |
disabled | 禁用；aria-disabled，集合内仍可达。 | boolean | - |
variant | 危险动作外观。 | "default" | "destructive" | - |
inset | 无前导图标时的起步缩进。 | boolean | - |
onAction | 统一激活入口。 | ((details: MenuActionDetails) => void) | - |
closeOnAction | 激活后是否关闭整棵菜单。默认 true。 | boolean | true |
children | 可见内容。 | ReactNode | - |
另有 285 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。
MenubarLabel
主题化标签；支持 inset。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
inset | 无前导图标时的起步缩进。 | boolean | - |
children | 标签文本。 | ReactNode | - |
另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。
MenubarMenu
主题化菜单：为子树提供 DropdownMenu 视觉尺寸上下文。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
value | 菜单标识；省略时用稳定自动 id（对齐 shadcn 无 value 用法）。 | string | - |
onOpenChange | 透传打开变更（在协调之后）。 | ((open: boolean, details: OverlayChangeDetails) => void) | - |
disabled | 为真时禁止打开并立即抑制可见层。 | boolean | - |
loop | 当前菜单面上下导航是否循环。默认 true。 | boolean | true |
closeOnEscape | 顶层 Esc 是否进入关闭流程。默认 true。 | boolean | true |
closeOnOutsidePress | 外部主指针是否关闭整棵菜单树。默认 true。 | boolean | true |
returnFocusRef | 整棵关闭后适用的返回焦点目标。 | RefObject<HTMLElement | null> | - |
children | 复合子树。 | ReactNode | - |
MenubarPortal
Menubar Portal：复用 DropdownMenu 域镜像 Portal。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
container | 挂载目标；省略默认 body；显式 null 等待就绪。 | PortalContainerInput | body |
children | Portal 子树。 | ReactNode | - |
MenubarRadioGroup
主题化单选组。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
defaultValue | 非受控默认值。 | string | - |
value | 受控值。 | string | - |
onValueChange | 值变更。 | ((value: string, details: MenuActionDetails) => void) | - |
children | 组内项。 | ReactNode | - |
另有 277 项原生属性与事件继承自 HTMLAttributes，原样透传。
MenubarRadioItem
主题化单选项；内置指示器。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
value * | 组内唯一值。 | string | - |
textValue * | typeahead 文本。 | string | - |
disabled | 禁用。 | boolean | - |
inset | 起步缩进。 | boolean | - |
onAction | 可选激活通知。 | ((details: MenuActionDetails) => void) | - |
closeOnAction | 默认 false。 | boolean | false |
children | 可见内容。 | ReactNode | - |
另有 283 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。
MenubarSeparator
主题化分隔线。
无自有属性；其余 278 项原生属性继承自 HTMLAttributes。
MenubarShortcut
主题化快捷键。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
children | 提示文本。 | ReactNode | - |
另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。
MenubarSub
子菜单根。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
open | 受控打开。 | boolean | - |
defaultOpen | 非受控默认。 | boolean | - |
onOpenChange | 子菜单开关变更。 | ((open: boolean, details: OverlayChangeDetails) => void) | - |
children | 子树。 | ReactNode | - |
MenubarSubContent
主题化子菜单面：默认自带 Portal。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
container | Portal 挂载点；省略默认 body。 | PortalContainerInput | body |
side | 物理四向；根默认 bottom，子默认逻辑外向。 | "top" | "bottom" | "left" | "right" | bottom |
align | 对齐；默认 start。 | "start" | "end" | "center" | start |
sideOffset | 侧向间距（CSS px）。 | number | - |
collisionPadding | 碰撞内边距（CSS px）。 | number | - |
onEscapeKeyDown | Esc；preventDefault 取消关闭。 | ((event: KeyboardEvent) => void) | - |
onPointerDownOutside | 外部主指针；preventDefault 取消关闭。 | ((event: Event) => void) | - |
style | 普通样式；受管定位不可绕过。 | CSSProperties | - |
ref | 转发到内容根。
Allows getting a ref to the component instance.
Once the component unmounts, React will set ref.current to null
(or call the ref with null if you passed a callback ref). | Ref<HTMLDivElement> | - |
children | 菜单面子树。 | ReactNode | - |
另有 276 项原生属性与事件继承自 HTMLAttributes，原样透传。
MenubarSubTrigger
主题化子菜单触发器；内置 chevron。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
textValue * | typeahead 文本。 | string | - |
disabled | 禁用。 | boolean | - |
inset | 起步缩进。 | boolean | - |
children | 可见内容。 | ReactNode | - |
另有 283 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。
MenubarTrigger
主题化触发器。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
render | 与 children 互斥。 | ReactElement<unknown, string | JSXElementConstructor<any>> | - |
children | 按钮内容。 | ReactNode | - |
另有 284 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。
导出类型：DropdownMenuItemVariant、DropdownMenuSize、MenubarCheckboxItemProps、MenubarContentProps、MenubarGroupProps、MenubarItemProps、MenubarLabelProps、MenubarMenuProps、MenubarPortalProps、MenubarProps、MenubarRadioGroupProps、MenubarRadioItemProps、MenubarSeparatorProps、MenubarShortcutProps、MenubarSubContentProps、MenubarSubProps、MenubarSubTriggerProps、MenubarTriggerProps
无障碍
摘自源码 JSDoc。
MenubarContent.onEscapeKeyDown：Esc；preventDefault 取消关闭。MenubarItem.disabled：禁用；aria-disabled，集合内仍可达。MenubarMenu.closeOnEscape：顶层 Esc 是否进入关闭流程。MenubarMenu.returnFocusRef：整棵关闭后适用的返回焦点目标。MenubarSubContent.onEscapeKeyDown：Esc；preventDefault 取消关闭。