Menubar

Menubar 用于构建类似桌面应用的横向菜单栏。组件基于 Radix Menubar，并复用项目 Menu 的菜单项、分隔线、子菜单、checkbox 和 radio 组选项能力。

import {
  Menubar,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarRoot,
  MenubarTrigger
} from '@skyroc/web-ui';

何时使用

需要在顶部区域展示应用级菜单，例如 File、Edit、View。
菜单项包含快捷键、分隔线、子菜单、checkbox 或 radio 选项。
需要键盘可访问的横向菜单栏。
普通下拉操作菜单优先使用 DropdownMenu；右键上下文菜单使用 ContextMenu。

基础用法

通过 items 传入菜单数据。每个顶层 item 会渲染一个菜单触发器和一个内容面板。

Preview

Code

顶层菜单类型

Menubar 支持三类顶层菜单：

type	说明
`item`	默认菜单，children 使用普通菜单项数据
`checkbox`	checkbox 菜单组，支持多选
`radio`	radio 菜单组，支持单选

菜单项类型

普通菜单的 children 复用 Menu 的数据结构，支持 item、label、separator 和 sub。

const fileMenu = [
  { label: 'New Tab', shortcut: '⌘T' },
  { type: 'separator' },
  {
    type: 'sub',
    label: 'Share',
    children: [
      { label: 'Email link' },
      { label: 'Messages' }
    ]
  }
];

受控选项

checkbox 顶层菜单通过 checks 和 onChecksChange 管理选中值；radio 顶层菜单通过 value 和 onValueChange 管理当前值。

尺寸与样式

通过 size 控制根菜单栏间距和菜单项尺寸。通过 classNames 控制菜单内容、菜单项、快捷键和触发器等 slot，其中 trigger 是 Menubar 额外扩展的 slot。

API

Menubar

通用属性参考：基于 Radix Menubar Root，并使用 items 渲染数据驱动菜单栏。

属性	说明	类型	默认值
items*	顶层菜单数据	MenubarOption[]	-
size	尺寸，影响菜单栏间距和菜单项尺寸	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	'md'
classNames	菜单相关 slot 的自定义 class，额外支持 trigger	MenubarClassNames	-
className	根菜单栏 class	ClassValue	-
value	受控模式下当前打开的顶层菜单 value	string	-
defaultValue	非受控模式下默认打开的顶层菜单 value	string	-
onValueChange	打开的顶层菜单变化时触发	(value: string) => void	-
loop	键盘导航是否循环	boolean	-
dir	文本方向	'ltr' \| 'rtl'	-

顶层菜单项

items 中的每个对象都会渲染为一个顶层菜单。

属性	说明	类型	默认值
label*	顶层菜单触发器内容	ReactNode	-
type	顶层菜单类型	'item' \| 'checkbox' \| 'radio'	'item'
children*	当前菜单的子项数据	MenuOptionData[] \| MenuCheckboxGroupItemProps[] \| MenuRadioItemOptionProps[]	-
checks	checkbox 菜单当前选中的值列表	string[]	-
onChecksChange	checkbox 菜单选中值变化时触发	(checks: string[]) => void	-
value	radio 菜单当前选中的值，或顶层菜单 value	string	-
onValueChange	radio 菜单选中值变化时触发	(value: string) => void	-
leading	顶层触发器前置内容	ReactNode	-
trailing	顶层触发器后置内容	ReactNode	-
shortcut	顶层触发器快捷键提示	string \| string[]	-

结构组件

Menubar 同时导出 Radix 风格结构组件，适合需要完全手动组合菜单结构时使用。

属性	说明	类型	默认值
MenubarRoot	根菜单栏容器	MenubarRootProps	-
MenubarMenu	Radix Menu 原语包装	MenubarMenuPrimitiveProps	-
MenubarTrigger	顶层菜单触发器	MenubarTriggerProps	-
MenubarContent	菜单内容容器，默认通过 Portal 渲染	MenubarContentProps	-
MenubarItem	普通菜单项	MenubarItemProps	-
MenubarLabel	菜单分组标签	MenubarLabelProps	-
MenubarSeparator	菜单分隔线	MenubarSeparatorProps	-
MenubarSub	子菜单根组件	MenubarSubProps	-
MenubarSubTrigger	子菜单触发项	MenubarSubTriggerProps	-
MenubarSubContent	子菜单内容	MenubarSubContentProps	-
MenubarCheckboxItem	checkbox 菜单项	MenubarCheckboxItemProps	-
MenubarRadioItem	radio 菜单项	MenubarRadioItemProps	-
MenubarRadioGroup	Radix RadioGroup 原语包装	MenubarRadioGroupPrimitiveProps	-
MenubarRadioGroupData	数据驱动 radio 组	MenubarRadioGroupProps	-
MenubarCheckboxGroup	数据驱动 checkbox 组	MenubarCheckboxGroupProps	-
MenubarShortcut	快捷键展示	MenubarShortcutProps	-

类型

MenubarProps

主组件属性。继承 Radix Menubar Root props，并通过 items 渲染数据驱动菜单。

字段	类型	说明
className	ClassValue	根菜单栏 class。
classNames	MenubarClassNames	菜单 slot class，额外支持 trigger。
defaultValue	string	默认打开的顶层菜单 value。
dir	'ltr' \| 'rtl'	文本方向。
items*	MenubarOption[]	顶层菜单数据。
loop	boolean	键盘导航是否循环。
onValueChange	(value: string) => void	打开菜单变化回调。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
value	string	受控打开的顶层菜单 value。

MenubarOption

顶层菜单数据。根据 type 分为普通菜单、checkbox 菜单和 radio 菜单。

字段	类型	说明
label	ReactNode	顶层菜单触发器内容。
type	'item' \| 'checkbox' \| 'radio'	顶层菜单类型。默认普通菜单可省略。
children	MenuOptionData[] \| MenuCheckboxGroupItemProps[] \| MenuRadioItemOptionProps[]	子项数据。
checks	string[]	checkbox 菜单选中值列表。
onChecksChange	(checks: string[]) => void	checkbox 菜单选中值变化回调。
value	string	radio 菜单选中值或顶层菜单 value。
onValueChange	(value: string) => void	radio 菜单值变化回调。
leading	ReactNode	触发器前置内容。
trailing	ReactNode	触发器后置内容。
shortcut	string \| string[]	快捷键提示。

普通菜单子项数据。

字段	类型	说明
type	'item' \| 'label' \| 'separator' \| 'sub'	菜单项类型。普通 item 可省略。
label	ReactNode	菜单项内容。
children	MenuOptionData[]	子菜单 children，仅 sub 类型使用。
disabled	boolean	是否禁用。
leading	ReactNode	前置内容。
trailing	ReactNode	后置内容。
shortcut	string \| string[]	快捷键提示。

MenubarClassNames

Menubar classNames 类型。继承 MenuClassNames，并额外增加 trigger。

字段	类型	说明
trigger	ClassValue	顶层触发器 class。
content	ClassValue	菜单内容 class，来自 MenuClassNames。
item	ClassValue	菜单项 class，来自 MenuClassNames。
shortcut	ClassValue	快捷键 class，来自 MenuClassNames。
label	ClassValue	标签 class，来自 MenuClassNames。
separator	ClassValue	分隔线 class，来自 MenuClassNames。

MenubarRootProps

根菜单栏属性。继承 Radix Menubar Root props，并支持 className 和 size。

字段	类型	说明
children	ReactNode	菜单栏内容。
className	ClassValue	根菜单栏 class。
defaultValue	string	默认打开菜单 value。
dir	'ltr' \| 'rtl'	文本方向。
loop	boolean	键盘导航是否循环。
onValueChange	(value: string) => void	打开菜单变化回调。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
value	string	受控打开菜单 value。

MenubarTriggerProps

顶层触发器属性。继承 Radix Trigger props，并支持前后插槽和 shortcut。

字段	类型	说明
children	ReactNode	触发器内容。
className	ClassValue	触发器 class。
classNames	MenubarTriggerClassNames	触发器相关 slot class。
leading	ReactNode	前置内容。
shortcut	string \| string[]	快捷键提示。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
trailing	ReactNode	后置内容。

MenubarContentProps

菜单内容属性。继承 Radix Content props，默认 align=start、alignOffset=-4、sideOffset=8。

字段	类型	说明
align	'start' \| 'center' \| 'end'	对齐方式。默认值为 start。
alignOffset	number	对齐偏移。默认值为 -4。
children	ReactNode	菜单内容。
className	ClassValue	内容 class。
sideOffset	number	侧向偏移。默认值为 8。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。

MenubarItemProps

普通菜单项属性。复用 MenuItemProps，并支持 inset。

字段	类型	说明
children	ReactNode	菜单项内容。
className	ClassValue	菜单项 class。
disabled	boolean	是否禁用。
inset	boolean	是否增加左侧缩进。
leading	ReactNode	前置内容。
shortcut	string \| string[]	快捷键提示。
trailing	ReactNode	后置内容。

MenubarCheckboxGroupProps

数据驱动 checkbox 菜单组属性。

字段	类型	说明
checks	string[]	选中值列表。
items*	MenuCheckboxGroupItemProps[]	checkbox 菜单项数据。
onChecksChange	(checks: string[]) => void	选中值变化回调。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。

MenubarRadioGroupProps

数据驱动 radio 菜单组属性。

字段	类型	说明
items*	MenuRadioItemOptionProps[]	radio 菜单项数据。
onValueChange	(value: string) => void	选中值变化回调。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
value	string	当前选中值。

MenubarShortcutProps

快捷键展示属性。children 为字符串时会作为 shortcut value 展示。

字段	类型	说明
children	ReactNode	快捷键内容。字符串会被转换为 value。
className	ClassValue	快捷键 class。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。

MenubarMenu 透传的 Radix Menu props

radix menubar menu props

内部使用的数据驱动顶层菜单组合属性

MenubarTriggerProps with trigger, value and children

MenubarLabelProps

MenubarLabel 复用 MenuLabelProps

menu label props

MenubarOptionProps

MenubarOption 复用 MenuOptionProps 并替换内部组件

menu option props

MenubarItemIndicatorProps

MenubarItemIndicator 复用 MenuItemIndicatorProps

menu item indicator props

MenubarSeparatorProps

MenubarSeparator 复用 MenuSeparatorProps

menu separator props

MenubarSubContentProps

MenubarSubContent 复用 MenuSubContentProps

menu sub content props

MenubarSubTriggerProps

MenubarSubTrigger 复用 MenuSubTriggerProps

menu sub trigger props

MenubarCheckboxItemProps

MenubarCheckboxItem 复用 MenuCheckboxItemProps

menu checkbox item props

MenubarRadioItemProps

MenubarRadioItem 复用 MenuRadioItemProps

menu radio item props

MenubarRadioGroupPrimitiveProps

MenubarRadioGroup 透传的 Radix RadioGroup props

radix menubar radio group props

MenubarGroupProps

MenubarGroup 透传的 Radix Group props

radix menubar group props

MenubarPortalProps

MenubarPortal 透传的 Radix Portal props

radix menubar portal props

MenubarSubProps

MenubarSub 透传的 Radix Sub props

radix menubar sub props

MenubarTriggerClassNames

MenubarTrigger 可配置的 slot class

{ trigger?: ClassValue; shortcut?: ClassValue }

MenubarSlots

Menubar 根组件 slot

'root'

ClassValue

CSS 类名类型

string | null | undefined | Record<string, boolean> | ClassValue[]

Menubar

MenubarProps

MenubarOption

MenuOptionData

MenubarClassNames

MenubarRootProps

MenubarTriggerProps

MenubarContentProps

MenubarItemProps

MenubarCheckboxGroupProps

MenubarRadioGroupProps

MenubarShortcutProps

MenubarMenuPrimitiveProps

MenubarMenuComposedProps

MenubarLabelProps

MenubarOptionProps

MenubarItemIndicatorProps

MenubarSeparatorProps

MenubarSubContentProps

MenubarSubTriggerProps

MenubarCheckboxItemProps

MenubarRadioItemProps

MenubarRadioGroupPrimitiveProps

MenubarGroupProps

MenubarPortalProps

MenubarSubProps

MenubarTriggerClassNames

MenubarSlots

ClassValue

On this page