组件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 | — | — |
源码
"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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
右键上下文菜单,由 ContextMenu、Trigger、Content、Item 组合;移动端需另提供长按或按钮入口。