组件Overlays
DropdownMenu
@mox-hub/ui 组件 · Overlays · deprecated
dropdown-menu@mox-hub/uiOverlaysdeprecatedsrc/components/dropdown-menu.tsx变体演示dropdown-menu
demo 待补(demos map 未注册)
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<unknown> | — | A handle to associate the menu with a trigger. |
| children | React.ReactNode | PayloadChildRenderFunction<unknown> | — | The content of the menu. |
源码
"use client"
import * as React from "react"
import { Menu as MenuPrimitive } from "@base-ui/react/menu"
import { cn } from "../lib/utils"
import { ChevronRightIcon, CheckIcon } from "lucide-react"
import {
SURFACE_POPOVER_CLASS,
menuCheckboxItemVariants,
menuItemVariants,
menuLabelVariants,
menuShortcutVariants,
menuSubTriggerVariants,
} from "./menu-styles"
/*
* ⚠️ 双轨待收口件 —— 目标替代品是 ui/menu.tsx(coss 配方,2026-08 起的唯一菜单实现)。
*
* 2026-09-27 批 3 已按 E 类方案 §三 E6 / §七 决策 B 做**实物 API 比对**。结论:
* **差异大,不是可直接替换的重复件**,故**未做机械合流**(决策 B 明写「API 差异大则
* 先标记 + 限期迁移」,禁止硬合不兼容 API)。
*
* 差异清单(本件 → menu 并非 1:1 改名可迁):
* 1. 内容层缺省位置不同:本件 Content 的 align 缺省 start;menu 的 MenuPopup 缺省 center
* ⇒ 直接换名会让生产下拉整体位移。
* 2. 条目排版不同:本件条目 px-2 py-1.5 text-sm;menu 的 MENU_ITEM_BASE_CLASS 为
* min-h-8 px-2 py-1 text-base(并在 sm 断点收敛)⇒ 行高与字号成体系地不同。
* 3. 缺省能力缺口:menu 的 MenuCheckboxItem / MenuRadioItem **不接收 inset**,
* 而本件两者都支持 ⇒ 迁移会收窄 API 面。
* 4. MenuShortcut 渲染 kbd 元素,本件 DropdownMenuShortcut 渲染 span
* ⇒ 语义与字体继承不同。
* 5. 子菜单定位不同:MenuSubPopup 固定 side=inline-end 且 alignOffset 缺省 -5;
* 本件 SubContent 为 side=right 且缺省 -3。
* 6. **契约槽位不同且有生产依赖**:本件暴露 data-slot=dropdown-menu-content 与
* dropdown-menu-sub-content,而 shared/lib/floating-layers.ts 的浮层登记表正按这两个
* 槽位识别本件弹出层 ⇒ 迁移必须同步改该表,否则浮层互斥(Esc / 滚动锁)失灵。
*
* 迁移指引(限期,逐消费方):
* - 真实消费方 4 处(assistant-model-picker 已随 2026-10-02 助理面板裁撤模型选择而删除)、
* modules/issue/components/execution-items-panel.tsx、
* modules/issue/components/issue-type-switcher.tsx、
* modules/notification/components/inbox-item-row.tsx、
* modules/notification/pages/notification-center-page.tsx。
* 另:ui/menubar.tsx 为原子层内部引用(standby 件),design-system 页为画廊引用。
* - 步骤:① 先把 align / side 在调用处**显式写出**(消除缺省差异,视觉零变化);
* ② 改导入源为 ui/menu.tsx 的 Menu 族具名导出;③ 若用到 inset / Shortcut /
* SubContent,须先给 menu 补齐对应能力(属 menu 的能力扩增,需另立批次评审);
* ④ 同步更新 floating-layers.ts 槽位表与 issue-type-switcher.test.tsx 的槽位选择器。
* - 收口未完成前本件**保持可用**,不得删除(人类铁律:删除须先经 review 态公示 + 人工批准)。
*
* 登记状态见 src/modules/design-system/registry.ts 的 dropdown-menu 条目。
*/
function DropdownMenu({ ...props }: MenuPrimitive.Root.Props) {
return <MenuPrimitive.Root data-slot="dropdown-menu" {...props} />
}
function DropdownMenuPortal({ ...props }: MenuPrimitive.Portal.Props) {
return <MenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />
}
function DropdownMenuTrigger({ ...props }: MenuPrimitive.Trigger.Props) {
return <MenuPrimitive.Trigger data-slot="dropdown-menu-trigger" {...props} />
}
function DropdownMenuContent({
align = "start",
alignOffset = 0,
side = "bottom",
sideOffset = 4,
className,
...props
}: MenuPrimitive.Popup.Props &
Pick<
MenuPrimitive.Positioner.Props,
"align" | "alignOffset" | "side" | "sideOffset"
>) {
return (
<MenuPrimitive.Portal>
<MenuPrimitive.Positioner
className="isolate z-modal outline-none"
align={align}
alignOffset={alignOffset}
side={side}
sideOffset={sideOffset}
>
<MenuPrimitive.Popup
data-slot="dropdown-menu-content"
className={cn("z-modal max-h-(--available-height) w-(--anchor-width) min-w-32 origin-(--transform-origin) overflow-x-hidden overflow-y-auto overscroll-contain p-1 duration-fast outline-none 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:overflow-hidden data-closed:fade-out-0 data-closed:zoom-out-95", SURFACE_POPOVER_CLASS, className )}
{...props}
/>
</MenuPrimitive.Positioner>
</MenuPrimitive.Portal>
)
}
function DropdownMenuGroup({ ...props }: MenuPrimitive.Group.Props) {
return <MenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />
}
function DropdownMenuLabel({
className,
inset,
...props
}: MenuPrimitive.GroupLabel.Props & {
inset?: boolean
}) {
return (
<MenuPrimitive.GroupLabel
data-slot="dropdown-menu-label"
data-inset={inset}
className={cn(menuLabelVariants({ inset }), className)}
{...props}
/>
)
}
function DropdownMenuItem({
className,
inset,
variant = "default",
...props
}: MenuPrimitive.Item.Props & {
inset?: boolean
variant?: "default" | "destructive"
}) {
return (
<MenuPrimitive.Item
data-slot="dropdown-menu-item"
data-inset={inset}
data-variant={variant}
className={cn(menuItemVariants({ inset }), className)}
{...props}
/>
)
}
function DropdownMenuSub({ ...props }: MenuPrimitive.SubmenuRoot.Props) {
return <MenuPrimitive.SubmenuRoot data-slot="dropdown-menu-sub" {...props} />
}
function DropdownMenuSubTrigger({
className,
inset,
children,
...props
}: MenuPrimitive.SubmenuTrigger.Props & {
inset?: boolean
}) {
return (
<MenuPrimitive.SubmenuTrigger
data-slot="dropdown-menu-sub-trigger"
data-inset={inset}
className={cn(menuSubTriggerVariants({ inset }), className)}
{...props}
>
{children}
<ChevronRightIcon className="ms-auto rtl:-scale-x-100" />
</MenuPrimitive.SubmenuTrigger>
)
}
function DropdownMenuSubContent({
align = "start",
alignOffset = -3,
side = "right",
sideOffset = 0,
className,
...props
}: React.ComponentProps<typeof DropdownMenuContent>) {
return (
<DropdownMenuContent
data-slot="dropdown-menu-sub-content"
className={cn("w-auto min-w-24 p-1 duration-fast data-[side=bottom]:slide-in-from-top-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", SURFACE_POPOVER_CLASS, className )}
align={align}
alignOffset={alignOffset}
side={side}
sideOffset={sideOffset}
{...props}
/>
)
}
function DropdownMenuCheckboxItem({
className,
children,
checked,
inset,
...props
}: MenuPrimitive.CheckboxItem.Props & {
inset?: boolean
}) {
return (
<MenuPrimitive.CheckboxItem
data-slot="dropdown-menu-checkbox-item"
data-inset={inset}
className={cn(menuCheckboxItemVariants({ inset }), className)}
checked={checked}
{...props}
>
<span
className="col-start-1 -ms-0.5 flex items-center justify-center"
data-slot="dropdown-menu-checkbox-item-indicator"
>
<MenuPrimitive.CheckboxItemIndicator>
<CheckIcon
/>
</MenuPrimitive.CheckboxItemIndicator>
</span>
<span className="col-start-2">{children}</span>
</MenuPrimitive.CheckboxItem>
)
}
function DropdownMenuRadioGroup({ ...props }: MenuPrimitive.RadioGroup.Props) {
return (
<MenuPrimitive.RadioGroup
data-slot="dropdown-menu-radio-group"
{...props}
/>
)
}
function DropdownMenuRadioItem({
className,
children,
inset,
...props
}: MenuPrimitive.RadioItem.Props & {
inset?: boolean
}) {
return (
<MenuPrimitive.RadioItem
data-slot="dropdown-menu-radio-item"
data-inset={inset}
className={cn(menuCheckboxItemVariants({ inset }), className)}
{...props}
>
<span
className="col-start-1 -ms-0.5 flex items-center justify-center"
data-slot="dropdown-menu-radio-item-indicator"
>
<MenuPrimitive.RadioItemIndicator>
<CheckIcon
/>
</MenuPrimitive.RadioItemIndicator>
</span>
<span className="col-start-2">{children}</span>
</MenuPrimitive.RadioItem>
)
}
function DropdownMenuSeparator({
className,
...props
}: MenuPrimitive.Separator.Props) {
return (
<MenuPrimitive.Separator
data-slot="dropdown-menu-separator"
className={cn("-mx-1 my-1 h-px bg-border", className)}
{...props}
/>
)
}
function DropdownMenuShortcut({
className,
...props
}: React.ComponentProps<"span">) {
return (
<span
data-slot="dropdown-menu-shortcut"
className={cn(menuShortcutVariants(), className)}
{...props}
/>
)
}
export {
DropdownMenu,
DropdownMenuPortal,
DropdownMenuTrigger,
DropdownMenuContent,
DropdownMenuGroup,
DropdownMenuLabel,
DropdownMenuItem,
DropdownMenuCheckboxItem,
DropdownMenuRadioGroup,
DropdownMenuRadioItem,
DropdownMenuSeparator,
DropdownMenuShortcut,
DropdownMenuSub,
DropdownMenuSubTrigger,
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。
用法说明
已弃用,2026-12-31 到期;新代码用 menu,存量按迁移清单替换。