react-global-context-menu

🚀 一个轻量、可定制、可全局复用的 React 右键菜单组件。

✨ 特性

• 🖱️ 全局右键菜单触发能力
• 🎨 支持菜单项自定义（icon、shortcut、divider、additional）
• 📐 自动防止菜单超出视口
• 🔒 支持点击外部关闭 / ESC 关闭 / 点击菜单项后关闭（均可配置）
• 🧱 菜单容器支持 className、minWidth、maxWidth、zIndex 等发布级配置
• ⚡ TypeScript 编写，提供完整类型定义
• 🎯 零外部样式依赖，内置精美样式

📦 安装

npm install react-global-context-menu
# or
yarn add react-global-context-menu
# or
pnpm add react-global-context-menu

🚀 快速开始

import {
  ContextMenuProvider,
  ContextMenuTrigger,
  MenuItem,
} from "react-global-context-menu";

const menus: MenuItem[] = [
  {
    key: "copy",
    type: "menu",
    name: "复制",
    shortcutKey: "Ctrl + C",
    show: true,
    onClick: () => console.log("copy"),
  },
  {
    key: "divider-1",
    type: "divider",
  },
  {
    key: "delete",
    type: "menu",
    name: "删除",
    show: true,
    className: "text-red-500",
    onClick: () => console.log("delete"),
  },
];

export default function App() {
  return (
    <ContextMenuProvider>
      <ContextMenuTrigger menus={menus} menuClassName="rounded-xl shadow-xl">
        <div style={{ padding: 24, border: "1px dashed #ccc" }}>在这里右键</div>
      </ContextMenuTrigger>
    </ContextMenuProvider>
  );
}

🧩 API

ContextMenuProvider

包裹你的应用根节点，提供全局菜单上下文。

<ContextMenuProvider>{children}</ContextMenuProvider>

ContextMenuTrigger

用于给任意区域添加右键触发能力。

Props

| 属性 | 类型 | 必填 | 说明 | | --------------- | ------------ | ---- | ------------------------ | | menus | MenuItem[] | ✅ | 菜单数据 | | children | ReactNode | ✅ | 触发区域 | | menuClassName | string | ❌ | 传给菜单容器的 className |

useGlobalContextMenu()

手动打开/关闭菜单：

const { openContextMenu, closeContextMenu } = useGlobalContextMenu();

openContextMenu(x, y, menus, {
  className: "rounded-xl",
  closeOnClickItem: true,
  closeOnClickOutside: true,
  closeOnEscape: true,
  minWidth: 180,
  maxWidth: 320,
  zIndex: 12000,
});

openContextMenu 签名

openContextMenu(
  x: number,
  y: number,
  menus: MenuItem[],
  options?: OpenContextMenuOptions,
): void;

OpenContextMenuOptions

| 属性 | 类型 | 默认值 | 说明 | | --------------------- | ------------------ | ----------- | ------------------------ | | className | string | "" | 菜单容器 className | | closeOnClickItem | boolean | true | 点击菜单项后是否自动关闭 | | closeOnClickOutside | boolean | true | 点击菜单外部是否关闭 | | closeOnEscape | boolean | true | 按 Esc 是否关闭 | | minWidth | number \| string | undefined | 菜单最小宽度 | | maxWidth | number \| string | "220px" | 菜单最大宽度 | | zIndex | number | 9999 | 菜单层级 |

MenuItem

MenuItem 为联合类型：MenuItemMenu | MenuItemDivider

MenuItemMenu

| 属性 | 类型 | 必填 | 说明 | | ------------- | --------------------- | ---- | ----------------------------------------- | | key | string | ✅ | 唯一键 | | type | "menu" | ❌ | 菜单项类型（建议显式传） | | show | boolean | ✅ | 控制菜单项显示逻辑（由业务自行过滤/控制） | | name | string \| ReactNode | ❌ | 文本/内容 | | className | string | ❌ | 菜单项样式 | | onClick | () => void | ❌ | 点击事件 | | disabled | boolean | ❌ | 是否禁用 | | icon | string | ❌ | 图标（如 emoji 或文本） | | shortcutKey | string | ❌ | 快捷键提示 | | additional | ReactNode \| string | ❌ | 额外右侧内容 |

MenuItemDivider

| 属性 | 类型 | 必填 | 说明 | | ----------- | ----------- | ---- | ---------- | | key | string | ✅ | 唯一键 | | type | "divider" | ✅ | 分割线 | | className | string | ❌ | 分割线样式 |

✅ 发布/生产建议

1. 为每个菜单项提供稳定唯一 key。
2. 对危险操作（删除等）建议增加视觉区分（如红色文案）。
3. 若应用中有弹窗/抽屉系统，建议统一管理 zIndex 策略。
4. 根据产品规范配置 minWidth / maxWidth，避免文案过长导致布局抖动。
5. 若你需要更复杂的主题系统，建议通过 menuClassName + item className 组合实现。

📄 License

MIT