Ordo UI
组件Overlays

ContextMenu

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

context-menu@mox-hub/uiOverlayscanonicalsrc/components/context-menu.tsx
变体演示context-menu
右键点击此区域

Props API

Prop类型默认值说明
children*ReactNode——
items*MenuItem[]——
getItems*() => MenuItem[]——
onItemClick*(item: MenuItem) => void——

源码

packages/ui/src/components/context-menu.tsx
"use client"

import * as React from "react"
import { useState } from "react"
import { ContextMenu as ContextMenuPrimitive } from "@base-ui/react/context-menu"
// i18n 去耦(2026-11-08 迁移批):库不依赖 react-i18next,searchable 子菜单文案
// 由 MenuItem 数据侧可选注入(searchPlaceholder / noMatchesText),缺省中文文案与
// 主仓 i18n 资源逐字一致。

import { useMessages } from "../i18n"
import { cn } from "../lib/utils"
import { ChevronRightIcon, SearchIcon } from "lucide-react"
import { Kbd } from "./kbd"
import {
  MENU_POPUP_CLASS,
  MENU_SEPARATOR_CLASS,
  MENU_GROUP_LABEL_CLASS,
} from "./menu"
import {
  menuCheckboxItemVariants,
  menuItemVariants,
  menuShortcutVariants,
  menuSubTriggerVariants,
} from "./menu-styles"

/*
 * 右键菜单:base-ui ContextMenu 原语(右键定位原生支持)
 * + coss ui Menu 设计(弹出层/条目样式与 ui/menu.tsx 同源)。
 */

function ContextMenuRoot({ ...props }: ContextMenuPrimitive.Root.Props) {
  return <ContextMenuPrimitive.Root data-slot="context-menu" {...props} />
}

function ContextMenuPortal({ ...props }: ContextMenuPrimitive.Portal.Props) {
  return (
    <ContextMenuPrimitive.Portal data-slot="context-menu-portal" {...props} />
  )
}

function ContextMenuTrigger({
  className,
  ...props
}: ContextMenuPrimitive.Trigger.Props) {
  return (
    <ContextMenuPrimitive.Trigger
      data-slot="context-menu-trigger"
      className={cn("select-none", className)}
      {...props}
    />
  )
}

function ContextMenuContent({
  className,
  children,
  ...props
}: ContextMenuPrimitive.Popup.Props) {
  return (
    <ContextMenuPrimitive.Portal>
      <ContextMenuPrimitive.Positioner
        className="z-modal outline-none"
        sideOffset={4}
      >
        <ContextMenuPrimitive.Popup
          data-slot="context-menu-content"
          className={cn(MENU_POPUP_CLASS, className)}
          {...props}
        >
          <div className="max-h-(--available-height) w-full overflow-y-auto overscroll-contain p-1">
            {children}
          </div>
        </ContextMenuPrimitive.Popup>
      </ContextMenuPrimitive.Positioner>
    </ContextMenuPrimitive.Portal>
  )
}

function ContextMenuGroup({ ...props }: ContextMenuPrimitive.Group.Props) {
  return (
    <ContextMenuPrimitive.Group data-slot="context-menu-group" {...props} />
  )
}

function ContextMenuLabel({
  className,
  ...props
}: ContextMenuPrimitive.GroupLabel.Props) {
  return (
    <ContextMenuPrimitive.GroupLabel
      data-slot="context-menu-label"
      className={cn(MENU_GROUP_LABEL_CLASS, className)}
      {...props}
    />
  )
}

function ContextMenuItem({
  className,
  variant = "default",
  ...props
}: ContextMenuPrimitive.Item.Props & {
  variant?: "default" | "destructive"
}) {
  return (
    <ContextMenuPrimitive.Item
      data-slot="context-menu-item"
      data-variant={variant}
      className={cn(menuItemVariants(), className)}
      {...props}
    />
  )
}

function ContextMenuSub({ ...props }: ContextMenuPrimitive.SubmenuRoot.Props) {
  return (
    <ContextMenuPrimitive.SubmenuRoot data-slot="context-menu-sub" {...props} />
  )
}

function ContextMenuSubTrigger({
  className,
  children,
  ...props
}: ContextMenuPrimitive.SubmenuTrigger.Props) {
  return (
    <ContextMenuPrimitive.SubmenuTrigger
      data-slot="context-menu-sub-trigger"
      className={cn(menuSubTriggerVariants(), className)}
      {...props}
    >
      {children}
      <ChevronRightIcon className="ms-auto -me-0.5 opacity-80 rtl:-scale-x-100" />
    </ContextMenuPrimitive.SubmenuTrigger>
  )
}

function ContextMenuSubContent({
  className,
  children,
  ...props
}: ContextMenuPrimitive.Popup.Props) {
  return (
    <ContextMenuPrimitive.Portal>
      <ContextMenuPrimitive.Positioner
        className="z-modal outline-none"
        side="inline-end"
        sideOffset={0}
        align="start"
        alignOffset={-5}
      >
        <ContextMenuPrimitive.Popup
          data-slot="context-menu-sub-content"
          className={cn(MENU_POPUP_CLASS, className)}
          {...props}
        >
          {/* 限高取 Base UI 的可用高度(视口扣掉锚点与安全边距)+ 滚动:
              长候选列表不再无限撑高,窄视口也不会越界 */}
          <div className="max-h-[var(--available-height)] w-full overflow-y-auto overscroll-contain p-1">
            {children}
          </div>
        </ContextMenuPrimitive.Popup>
      </ContextMenuPrimitive.Positioner>
    </ContextMenuPrimitive.Portal>
  )
}

function ContextMenuCheckboxItem({
  className,
  children,
  checked,
  ...props
}: ContextMenuPrimitive.CheckboxItem.Props) {
  return (
    <ContextMenuPrimitive.CheckboxItem
      data-slot="context-menu-checkbox-item"
      className={cn(menuCheckboxItemVariants(), className)}
      checked={checked}
      {...props}
    >
      <ContextMenuPrimitive.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>
      </ContextMenuPrimitive.CheckboxItemIndicator>
      <span className="col-start-2">{children}</span>
    </ContextMenuPrimitive.CheckboxItem>
  )
}

function ContextMenuRadioGroup({
  ...props
}: ContextMenuPrimitive.RadioGroup.Props) {
  return (
    <ContextMenuPrimitive.RadioGroup
      data-slot="context-menu-radio-group"
      {...props}
    />
  )
}

function ContextMenuRadioItem({
  className,
  children,
  ...props
}: ContextMenuPrimitive.RadioItem.Props) {
  return (
    <ContextMenuPrimitive.RadioItem
      data-slot="context-menu-radio-item"
      className={cn(menuCheckboxItemVariants(), className)}
      {...props}
    >
      <ContextMenuPrimitive.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>
      </ContextMenuPrimitive.RadioItemIndicator>
      <span className="col-start-2">{children}</span>
    </ContextMenuPrimitive.RadioItem>
  )
}

function ContextMenuSeparator({
  className,
  ...props
}: ContextMenuPrimitive.Separator.Props) {
  return (
    <ContextMenuPrimitive.Separator
      data-slot="context-menu-separator"
      className={cn(MENU_SEPARATOR_CLASS, className)}
      {...props}
    />
  )
}

function ContextMenuShortcut({
  className,
  ...props
}: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="context-menu-shortcut"
      className={cn(menuShortcutVariants(), className)}
      {...props}
    />
  )
}

export {
  ContextMenu,
  ContextMenuRoot,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuCheckboxItem,
  ContextMenuRadioItem,
  ContextMenuLabel,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuGroup,
  ContextMenuPortal,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuRadioGroup,
}

/* ============================================
   元数据驱动兼容层(历史 API,构建于官方 parts 之上)
   消费方:data-list / tab-bar / *-simple-list / row-context-menu
   升级官方组件时保留本节。
   ============================================ */

export interface MenuItem {
  id: string
  label: React.ReactNode
  icon?: React.ReactNode
  shortcut?: string
  /** 行尾右对齐内容(如选中态对勾) */
  trailing?: React.ReactNode
  disabled?: boolean
  destructive?: boolean
  onClick?: () => void
  children?: MenuItem[]
  separatorAfter?: boolean
  /** 子菜单内置搜索框(标签/负责人等长候选列表;配合 children 使用) */
  searchable?: boolean
  /** 搜索匹配文本(缺省回退 string 型 label);仅作为 searchable 子菜单的候选项时需要 */
  searchText?: string
  /** searchable 子菜单搜索框占位文案(缺省「搜索」);i18n 去耦后由数据侧注入(2026-11-08) */
  searchPlaceholder?: string
  /** searchable 子菜单无匹配文案(缺省「无匹配」) */
  noMatchesText?: string
}

interface ContextMenuProps {
  children?: React.ReactNode
  items?: MenuItem[]
  /** 惰性菜单构建口(宪法 §21.3):菜单数组在菜单打开的事件期才构建,禁止列表逐行在 render 期构建。
   *  与 items 二选一;两者都传时 getItems 优先。 */
  getItems?: () => MenuItem[]
  onItemClick?: (item: MenuItem) => void
  className?: string
}

let menuIdCounter = 0
function genMenuId() {
  menuIdCounter += 1
  return `menu-${menuIdCounter}`
}

/** 关闭态惰性菜单的稳定空数组(避免每渲染新数组触发下游 memo 失效) */
const EMPTY_MENU_ITEMS: MenuItem[] = []

export function createMenuItems(
  config: Array<{
    label: React.ReactNode
    icon?: React.ReactNode
    shortcut?: string
    disabled?: boolean
    destructive?: boolean
    onClick?: () => void
    separatorAfter?: boolean
    children?: Array<{
      label: React.ReactNode
      icon?: React.ReactNode
      shortcut?: string
      disabled?: boolean
      destructive?: boolean
      onClick?: () => void
    }>
  }>
): MenuItem[] {
  return config.map((item) => ({
    id: genMenuId(),
    ...item,
    children: item.children?.map((child) => ({
      id: genMenuId(),
      ...child,
    })),
  }))
}

function MenuItemRow({
  item,
  onItemClick,
}: {
  item: MenuItem
  onItemClick?: (item: MenuItem) => void
}) {
  return (
    <ContextMenuItem
      disabled={item.disabled}
      variant={item.destructive ? "destructive" : "default"}
      onClick={() => {
        item.onClick?.()
        onItemClick?.(item)
      }}
      className={cn(
        "gap-2",
        item.destructive &&
          "text-destructive data-highlighted:text-destructive"
      )}
    >
      {item.icon ? (
        <span className="flex size-4 shrink-0 items-center justify-center">
          {item.icon}
        </span>
      ) : null}
      <span className="flex-1 truncate">{item.label}</span>
      {item.trailing ?? null}
      {item.shortcut ? (
        <ContextMenuShortcut>
          <Kbd>{item.shortcut}</Kbd>
        </ContextMenuShortcut>
      ) : null}
    </ContextMenuItem>
  )
}

/** searchable 子菜单的过滤文本:优先 searchText,回退 string 型 label */
function menuSearchText(item: MenuItem): string {
  if (item.searchText) return item.searchText
  return typeof item.label === "string" ? item.label : ""
}

/** 子菜单内置搜索:顶部过滤输入框 + 实时过滤候选(Esc 先清词再关菜单) */
function SearchableMenuChildren({
  items,
  onItemClick,
  searchPlaceholder,
  noMatchesText,
}: {
  items: MenuItem[]
  onItemClick?: (item: MenuItem) => void
  searchPlaceholder?: string
  noMatchesText?: string
}) {
  const M = useMessages()
  const resolvedSearchPlaceholder =
    searchPlaceholder ?? M.contextMenu.search
  const resolvedNoMatchesText = noMatchesText ?? M.contextMenu.noMatches
  const [query, setQuery] = useState("")
  const trimmed = query.trim().toLowerCase()
  const filtered = trimmed
    ? items.filter((item) => menuSearchText(item).toLowerCase().includes(trimmed))
    : items
  return (
    <>
      {/* 键盘事件不外溢:输入框内的字母/方向键不能触发菜单 typeahead 与快捷键 */}
      <div
        className="px-1 pb-1"
        onKeyDown={(e) => {
          if (e.key === "Escape") {
            if (query) {
              // 第一下 Escape 只清词
              e.preventDefault()
              e.stopPropagation()
              setQuery("")
            }
            // 词已清空:放行给 base-ui 的 dismiss,菜单正常关闭
            return
          }
          // 其余按键不外溢:输入框内的字母/方向键不能触发菜单 typeahead
          e.stopPropagation()
        }}
      >
        <div className="flex h-control-2xs items-center gap-1.5 rounded-sm border border-border/60 bg-muted/40 px-2 transition-[color,box-shadow] duration-fast focus-within:border-ring focus-within:ring-2 focus-within:ring-ring/50">
          <SearchIcon className="size-3.5 shrink-0 text-muted-foreground" />
          <input
            autoFocus
            aria-label={resolvedSearchPlaceholder}
            value={query}
            onChange={(e) => setQuery(e.target.value)}
            placeholder={resolvedSearchPlaceholder}
            className="h-full w-full bg-transparent text-xs outline-none placeholder:text-muted-foreground"
          />
        </div>
      </div>
      <ContextMenuSeparator />
      {filtered.length ? (
        renderMenuItems(filtered, onItemClick)
      ) : (
        <div className="px-2 py-3 text-center text-xs text-muted-foreground">
          {resolvedNoMatchesText}
        </div>
      )}
    </>
  )
}

function renderMenuItems(items: MenuItem[], onItemClick?: (item: MenuItem) => void) {
  return items.map((item) => (
    <React.Fragment key={item.id}>
      {item.children?.length ? (
        <ContextMenuSub>
          <ContextMenuSubTrigger className="gap-2">
            {item.icon ? (
              <span className="flex size-4 shrink-0 items-center justify-center">{item.icon}</span>
            ) : null}
            <span className="flex-1 truncate">{item.label}</span>
          </ContextMenuSubTrigger>
          <ContextMenuSubContent>
            {item.searchable ? (
              <SearchableMenuChildren
                items={item.children}
                onItemClick={onItemClick}
                searchPlaceholder={item.searchPlaceholder}
                noMatchesText={item.noMatchesText}
              />
            ) : (
              renderMenuItems(item.children, onItemClick)
            )}
          </ContextMenuSubContent>
        </ContextMenuSub>
      ) : (
        <MenuItemRow item={item} onItemClick={onItemClick} />
      )}
      {item.separatorAfter ? <ContextMenuSeparator /> : null}
    </React.Fragment>
  ))
}

function ContextMenu({ children, items, getItems, onItemClick }: ContextMenuProps) {
  // className 仅作历史 API 兼容保留:旧包裹层时代用于 display:contents,
  // 现在若转发给 popup 会令其 display:contents,背景/边框/阴影全部失效
  // 注意:本层用 cloneElement 把右键菜单 props(含 ref)注入 children——children 必须是
  // DOM 元素或能透传 props/ref 的组件。children 自带触发器 ref 时会被覆盖(如把 hover
  // 卡 props 直接展开在 div 上再交给本层克隆),嵌套其它 cloneElement 型包装时应让它
  // 克隆一个「转发 props 的组件」(参考 tab-bar 的 RoutePreviewTrigger 用法)。
  // getItems 惰性口(宪法 §21.3):关闭态不构建菜单数组,打开瞬间才调用一次。
  const [open, setOpen] = useState(false)
  const resolvedItems = getItems ? (open ? getItems() : EMPTY_MENU_ITEMS) : (items ?? [])
  return (
    <ContextMenuRoot onOpenChange={setOpen}>
      <ContextMenuTrigger
        render={(triggerProps: Record<string, unknown>) =>
          React.isValidElement(children)
            ? // cloneElement 的 props 是整体覆盖语义:trigger 自带 className(select-none)
              // 会吃掉子元素自身的布局类(如 flex),必须显式合并
              React.cloneElement(children, {
                ...triggerProps,
                className: cn(
                  (children.props as { className?: string }).className,
                  triggerProps.className as string | undefined,
                ),
              } as never)
            : React.cloneElement(<div>{children}</div>, triggerProps as never)
        }
      />
      <ContextMenuContent>{renderMenuItems(resolvedItems, onItemClick)}</ContextMenuContent>
    </ContextMenuRoot>
  )
}

可访问性与 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。

用法说明

右键上下文菜单,由 ContextMenu、Trigger、Content、Item 组合;移动端需另提供长按或按钮入口。