Ordo UI
组件Overlays

DropdownMenu

@mox-hub/ui 组件 · Overlays · deprecated

dropdown-menu@mox-hub/uiOverlaysdeprecatedsrc/components/dropdown-menu.tsx
变体演示dropdown-menu
demo 待补(demos map 未注册)

Props API

Prop类型默认值说明
defaultOpenboolean—Whether the menu is initially open.
loopFocusboolean—Whether to loop keyboard focus back to the first item
highlightItemOnHoverboolean—Whether moving the pointer over items should highlight them.
modalboolean—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.
openboolean—Whether the menu is currently open.
orientationMenuRootOrientation—The visual orientation of the menu.
disabledboolean—Whether the component should ignore user interaction.
closeParentOnEscboolean—When in a submenu, determines whether pressing the Escape key
actionsRefReact.RefObject<MenuRootActions>—A ref to imperative actions.
triggerIdstring—ID of the trigger that the menu is associated with.
defaultTriggerIdstring—ID of the trigger that the menu is associated with.
handleMenuHandle<unknown>—A handle to associate the menu with a trigger.
childrenReact.ReactNode | PayloadChildRenderFunction<unknown>—The content of the menu.

源码

packages/ui/src/components/dropdown-menu.tsx
"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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

已弃用,2026-12-31 到期;新代码用 menu,存量按迁移清单替换。