组件Navigation
Menu
@mox-hub/ui 组件 · Navigation · canonical
menu@mox-hub/uiNavigationcanonicalsrc/components/menu.tsx变体演示menu
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| defaultOpen | boolean | — | Whether the menu is initially open. |
| loopFocus | boolean | — | Whether to loop keyboard focus back to the first item |
| highlightItemOnHover | boolean | — | Whether moving the pointer over items should highlight them. |
| modal | boolean | — | Determines if the menu enters a modal state when open. |
| onOpenChange | (open: boolean, eventDetails: MenuRoot.ChangeEventDetails) => void | — | Event handler called when the menu is opened or closed. |
| onOpenChangeComplete | (open: boolean) => void | — | Event handler called after any animations complete when the menu is opened or closed. |
| onItemHighlighted | (highlightedItem: HTMLElement | undefined, eventDetails: MenuRoot.HighlightEventDetails) => void | — | Callback fired when an item is highlighted or unhighlighted. |
| open | boolean | — | Whether the menu is currently open. |
| orientation | MenuRootOrientation | — | The visual orientation of the menu. |
| disabled | boolean | — | Whether the component should ignore user interaction. |
| closeParentOnEsc | boolean | — | When in a submenu, determines whether pressing the Escape key |
| actionsRef | React.RefObject<MenuRootActions> | — | A ref to imperative actions. |
| triggerId | string | — | ID of the trigger that the menu is associated with. |
| defaultTriggerId | string | — | ID of the trigger that the menu is associated with. |
| handle | MenuHandle<Payload> | — | A handle to associate the menu with a trigger. |
| children | React.ReactNode | PayloadChildRenderFunction<Payload> | — | The content of the menu. |
源码
"use client"
import { Menu as MenuPrimitive } from "@base-ui/react/menu"
import { ChevronRightIcon } from "lucide-react"
import type * as React from "react"
import { cn } from "../lib/utils"
import {
SURFACE_MENU_CLASS,
menuCheckboxItemVariants,
menuItemVariants,
menuLabelVariants,
menuShortcutVariants,
menuSubTriggerVariants,
} from "./menu-styles"
/*
* coss ui Menu(base-ui 配方移植,registry @coss/menu)
* 下拉菜单标准件;右键菜单(context-menu.tsx)复用本文件的条目样式常量。
*/
export const MenuCreateHandle: typeof MenuPrimitive.createHandle =
MenuPrimitive.createHandle
export const Menu = MenuPrimitive.Root
export const MenuPortal = MenuPrimitive.Portal
/** 条目/弹出层样式常量(供 context-menu 等 非 MenuRoot 容器复用同一设计) */
export const MENU_POPUP_CLASS = cn(
"relative flex not-[class*='w-']:min-w-32 origin-(--transform-origin) outline-none not-dark:bg-clip-padding before:pointer-events-none before:absolute before:inset-0 before:rounded-inset-menu before:shadow-[0_1px_--theme(--color-black/4%)] focus:outline-none dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
SURFACE_MENU_CLASS,
"duration-fast data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95"
)
export const MENU_ITEM_BASE_CLASS = menuItemVariants()
export const MENU_CHECKBOX_ITEM_CLASS = cn(
menuCheckboxItemVariants(),
"in-data-[side=none]:min-w-[calc(var(--anchor-width)+1.25rem)]"
)
export const MENU_GROUP_LABEL_CLASS = menuLabelVariants()
export const MENU_SEPARATOR_CLASS = "mx-2 my-1 h-px bg-border"
export function MenuTrigger({
className,
children,
...props
}: MenuPrimitive.Trigger.Props): React.ReactElement {
return (
<MenuPrimitive.Trigger
className={className}
data-slot="menu-trigger"
{...props}
>
{children}
</MenuPrimitive.Trigger>
)
}
export function MenuPopup({
children,
className,
sideOffset = 4,
align = "center",
alignOffset,
side = "bottom",
anchor,
portalProps,
...props
}: MenuPrimitive.Popup.Props & {
align?: MenuPrimitive.Positioner.Props["align"]
sideOffset?: MenuPrimitive.Positioner.Props["sideOffset"]
alignOffset?: MenuPrimitive.Positioner.Props["alignOffset"]
side?: MenuPrimitive.Positioner.Props["side"]
anchor?: MenuPrimitive.Positioner.Props["anchor"]
portalProps?: MenuPrimitive.Portal.Props
}): React.ReactElement {
return (
<MenuPortal {...portalProps}>
<MenuPrimitive.Positioner
align={align}
alignOffset={alignOffset}
anchor={anchor}
className="z-modal"
data-slot="menu-positioner"
side={side}
sideOffset={sideOffset}
>
<MenuPrimitive.Popup
className={cn(MENU_POPUP_CLASS, className)}
data-slot="menu-popup"
{...props}
>
<div className="max-h-(--available-height) w-full overflow-y-auto overscroll-contain p-1">
{children}
</div>
</MenuPrimitive.Popup>
</MenuPrimitive.Positioner>
</MenuPortal>
)
}
export function MenuGroup(
props: MenuPrimitive.Group.Props
): React.ReactElement {
return <MenuPrimitive.Group data-slot="menu-group" {...props} />
}
export function MenuItem({
className,
inset,
variant = "default",
...props
}: MenuPrimitive.Item.Props & {
inset?: boolean
variant?: "default" | "destructive"
}): React.ReactElement {
return (
<MenuPrimitive.Item
className={cn(menuItemVariants({ inset }), className)}
data-inset={inset}
data-slot="menu-item"
data-variant={variant}
{...props}
/>
)
}
export function MenuLinkItem({
className,
inset,
variant = "default",
closeOnClick = true,
...props
}: MenuPrimitive.LinkItem.Props & {
inset?: boolean
variant?: "default" | "destructive"
}): React.ReactElement {
return (
<MenuPrimitive.LinkItem
className={cn(menuItemVariants({ inset }), className)}
closeOnClick={closeOnClick}
data-inset={inset}
data-slot="menu-link-item"
data-variant={variant}
{...props}
/>
)
}
export function MenuCheckboxItem({
className,
children,
checked,
variant = "default",
...props
}: MenuPrimitive.CheckboxItem.Props & {
variant?: "default" | "switch"
}): React.ReactElement {
return (
<MenuPrimitive.CheckboxItem
checked={checked}
className={cn(
menuCheckboxItemVariants(),
variant === "switch" && "flex items-center justify-between gap-2",
className
)}
data-slot="menu-checkbox-item"
data-variant={variant}
{...props}
>
{variant === "switch" ? (
<>
<span className="min-w-0 flex-1 truncate">{children}</span>
<MenuPrimitive.CheckboxItemIndicator
className="ms-auto inset-shadow-[0_1px_--theme(--color-black/4%)] inline-flex h-[calc(var(--thumb-size)+2px)] w-[calc(var(--thumb-size)*2-2px)] shrink-0 items-center rounded-full p-px outline-none transition-[background-color,box-shadow] duration-normal [--thumb-size:--spacing(4)] focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:ring-offset-1 focus-visible:ring-offset-background data-checked:bg-primary data-unchecked:bg-input data-disabled:opacity-50 sm:[--thumb-size:--spacing(3)]"
keepMounted
>
<span className="pointer-events-none block aspect-square h-full in-[[data-slot=menu-checkbox-item][data-checked]]:origin-[var(--thumb-size)_50%] origin-left rtl:origin-right in-[[data-slot=menu-checkbox-item][data-checked]]:translate-x-[calc(var(--thumb-size)-4px)] rtl:in-[[data-slot=menu-checkbox-item][data-checked]]:-translate-x-[calc(var(--thumb-size)-4px)] in-[[data-slot=menu-checkbox-item]:active]:not-data-disabled:scale-x-110 in-[[data-slot=menu-checkbox-item]:active]:rounded-[var(--thumb-size)/calc(var(--thumb-size)*1.10)] rounded-(--thumb-size) bg-background shadow-xs/5 will-change-transform [transition:translate_.15s,border-radius_.15s,scale_.1s_.1s,transform-origin_.15s]" />
</MenuPrimitive.CheckboxItemIndicator>
</>
) : (
<>
<MenuPrimitive.CheckboxItemIndicator className="col-start-1 -ms-0.5">
<svg
aria-hidden="true"
fill="none"
height="24"
stroke="currentColor"
strokeLinecap="round"
strokeLinejoin="round"
strokeWidth="2"
viewBox="0 0 24 24"
width="24"
xmlns="http://www.w3.org/2000/svg"
>
<path d="M5.252 12.7 10.2 18.63 18.748 5.37" />
</svg>
</MenuPrimitive.CheckboxItemIndicator>
<span className="col-start-2">{children}</span>
</>
)}
</MenuPrimitive.CheckboxItem>
)
}
export function MenuRadioGroup(
props: MenuPrimitive.RadioGroup.Props
): React.ReactElement {
return <MenuPrimitive.RadioGroup data-slot="menu-radio-group" {...props} />
}
export function MenuRadioItem({
className,
children,
...props
}: MenuPrimitive.RadioItem.Props): React.ReactElement {
return (
<MenuPrimitive.RadioItem
className={cn(menuCheckboxItemVariants(), className)}
data-slot="menu-radio-item"
{...props}
>
<MenuPrimitive.RadioItemIndicator className="col-start-1 -ms-0.5">
<svg
aria-hidden="true"
fill="none"
height="24"
stroke="currentColor"
strokeLinecap="round"
strokeLinejoin="round"
strokeWidth="2"
viewBox="0 0 24 24"
width="24"
xmlns="http://www.w3.org/2000/svg"
>
<path d="M5.252 12.7 10.2 18.63 18.748 5.37" />
</svg>
</MenuPrimitive.RadioItemIndicator>
<span className="col-start-2">{children}</span>
</MenuPrimitive.RadioItem>
)
}
export function MenuGroupLabel({
className,
inset,
...props
}: MenuPrimitive.GroupLabel.Props & {
inset?: boolean
}): React.ReactElement {
return (
<MenuPrimitive.GroupLabel
className={cn(menuLabelVariants({ inset }), className)}
data-inset={inset}
data-slot="menu-label"
{...props}
/>
)
}
export function MenuSeparator({
className,
...props
}: MenuPrimitive.Separator.Props): React.ReactElement {
return (
<MenuPrimitive.Separator
className={cn(MENU_SEPARATOR_CLASS, className)}
data-slot="menu-separator"
{...props}
/>
)
}
export function MenuShortcut({
className,
...props
}: React.ComponentProps<"kbd">): React.ReactElement {
return (
<kbd
className={cn(menuShortcutVariants(), className)}
data-slot="menu-shortcut"
{...props}
/>
)
}
export function MenuSub(
props: MenuPrimitive.SubmenuRoot.Props
): React.ReactElement {
return <MenuPrimitive.SubmenuRoot data-slot="menu-sub" {...props} />
}
export function MenuSubTrigger({
className,
inset,
children,
...props
}: MenuPrimitive.SubmenuTrigger.Props & {
inset?: boolean
}): React.ReactElement {
return (
<MenuPrimitive.SubmenuTrigger
className={cn(menuSubTriggerVariants({ inset }), className)}
data-inset={inset}
data-slot="menu-sub-trigger"
{...props}
>
{children}
<ChevronRightIcon className="ms-auto -me-0.5 opacity-80 rtl:-scale-x-100" />
</MenuPrimitive.SubmenuTrigger>
)
}
export function MenuSubPopup({
className,
sideOffset = 0,
alignOffset,
align = "start",
...props
}: MenuPrimitive.Popup.Props & {
align?: MenuPrimitive.Positioner.Props["align"]
sideOffset?: MenuPrimitive.Positioner.Props["sideOffset"]
alignOffset?: MenuPrimitive.Positioner.Props["alignOffset"]
}): React.ReactElement {
const defaultAlignOffset = align !== "center" ? -5 : undefined
return (
<MenuPopup
align={align}
alignOffset={alignOffset ?? defaultAlignOffset}
className={className}
data-slot="menu-sub-content"
side="inline-end"
sideOffset={sideOffset}
{...props}
/>
)
}
export {
MenuPrimitive,
MenuCreateHandle as DropdownMenuCreateHandle,
Menu as DropdownMenu,
MenuPortal as DropdownMenuPortal,
MenuTrigger as DropdownMenuTrigger,
MenuPopup as DropdownMenuContent,
MenuGroup as DropdownMenuGroup,
MenuItem as DropdownMenuItem,
MenuCheckboxItem as DropdownMenuCheckboxItem,
MenuRadioGroup as DropdownMenuRadioGroup,
MenuRadioItem as DropdownMenuRadioItem,
MenuGroupLabel as DropdownMenuLabel,
MenuSeparator as DropdownMenuSeparator,
MenuShortcut as DropdownMenuShortcut,
MenuSub as DropdownMenuSub,
MenuSubTrigger as DropdownMenuSubTrigger,
MenuSubPopup as DropdownMenuSubContent,
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
通用菜单原语(Base UI Menu),由 Menu、MenuTrigger、MenuPopup、MenuItem 组合;新代码优先用它而不是已弃用的 dropdown-menu。