React Menu-Aim

中文：基于 jQuery-menu-aim 算法的 React 版本智能下拉菜单组件。 通过检测鼠标移动方向，判断用户是"想悬停某一项"还是"正前往子菜单"， 解决了传统下拉菜单中鼠标斜向移动导致子菜单闪烁的 UX 痛点。

English: A React implementation of the classic jQuery-menu-aim plugin. By detecting mouse movement direction, it determines whether the user is "hovering over an item" or "heading to the submenu", solving the UX flicker problem that occurs when users move their mouse diagonally toward submenus.

中文文档 | English Documentation

中文文档

✨ 特性

• 🎯 方向检测：实时追踪鼠标位置，判断是否"瞄准"子菜单
• 🚫 无误触发：鼠标斜向移动穿过其他菜单项时，子菜单不会闪烁
• ⚡ 即时响应：不依赖 timeout 延迟，所有交互即时响应
• 🔄 多级嵌套：支持任意层级的子菜单嵌套
• 📐 多方向支持：支持 right / left / down / up 四种展开方向
• 🎨 可定制：灵活的 API 和 CSS 样式定制
• 📦 零依赖：仅依赖 React（>=17），不绑定任何 UI 组件库（如 antd），可在任何项目中独立使用

📦 安装

# 通过 npm 安装（推荐）
npm install @jiongsen/react-menu-aim

# 或克隆仓库本地开发
git clone https://github.com/kkk360/react-menu-aim.git
cd react-aim
npm install
npm run dev        # 启动开发服务器
npm run build:lib  # 构建库版本

🚀 快速开始

import MenuAim from '@jiongsen/react-menu-aim';
import '@jiongsen/react-menu-aim/style.css';

const menuItems = [
  {
    key: 'file',
    label: 'File',
    children: [
      { key: 'new', label: 'New' },
      { key: 'open', label: 'Open...' },
      {
        key: 'export',
        label: 'Export',
        children: [
          { key: 'pdf', label: 'PDF' },
          { key: 'png', label: 'PNG' },
        ],
      },
    ],
  },
  {
    key: 'edit',
    label: 'Edit',
    children: [
      { key: 'undo', label: 'Undo' },
      { key: 'redo', label: 'Redo' },
    ],
  },
];

function App() {
  return <MenuAim items={menuItems} direction="right" />;
}

📖 API 说明

<MenuAim> Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | items | Array<MenuItem> | — | 菜单项数据数组 | | direction | 'right' \| 'left' \| 'down' \| 'up' | 'right' | 子菜单展开方向 | | className | string | '' | 自定义 CSS 类名 |

MenuItem 数据结构

{
  key: string;           // 唯一标识
  label: string;         // 显示文本
  children?: MenuItem[]; // 可选的子菜单项
}

🔧 工作原理

传统菜单的问题

用户想把鼠标从 File → 斜向移动到 Export 子菜单
       ↘
    [File] ←── 起点
    [Edit] ←── 鼠标经过此项，导致 Edit 子菜单被误触发！
    [View]

传统菜单使用 timeout 延迟来避免这个问题，但这会让操作显得迟钝。

Menu-Aim 的解决方案

Menu-Aim 不使用延迟，而是通过方向检测来判断用户意图：

1. 当鼠标进入某个菜单项时，记录鼠标的入场点（Entry Point）
2. 当子菜单出现时，基于子菜单的左边缘和入场点构建一个瞄准三角形（Aim Triangle）
3. 当鼠标离开当前菜单项时，判断鼠标是否在这个三角形内部
4. 如果在三角形内 → 用户正在瞄准子菜单 → 保持打开
5. 如果在三角形外 → 用户没有瞄准子菜单 → 正常关闭/切换

         子菜单
    ┌─────────────┐
    │  New        │
    │  Open...    │ ← 瞄准三角形的一条边
    │  Save       │
    └─────────────┘
          ▲
          │  瞄准三角形
          │  (Entry Point → Submenu Edge)
          │
       [File] ← 入场点
       [Edit]
       [View]

三角形的"漏斗"形状确保了鼠标从菜单项斜向移动到子菜单的路径始终在三角形内部。

📁 项目结构

src/
├── components/
│   └── MenuAim/
│       ├── MenuAim.jsx      # 主组件，包含核心逻辑
│       ├── MenuItem.jsx     # 菜单项组件
│       ├── MenuAim.css      # 样式
│       └── index.js         # 导出入口
├── App.jsx                  # Demo 演示页
├── App.css                  # Demo 样式
└── index.css                # 全局样式

🎨 自定义样式

所有组件类名以 menu-aim 为前缀，方便样式覆盖：

/* 自定义菜单列表 */
.menu-aim__list {
  background: #1a1a2e;
  border-color: #16213e;
}

/* 自定义菜单项 */
.menu-aim__item {
  color: #e0e0e0;
}

.menu-aim__item:hover,
.menu-aim__item--active {
  background-color: #0f3460;
  color: #e94560;
}

🌐 浏览器支持

• Chrome / Edge（推荐）
• Firefox
• Safari
• 所有支持 CSS position: absolute 和 getBoundingClientRect 的浏览器

📝 License

MIT

English Documentation

✨ Features

• 🎯 Direction Detection: Tracks mouse position in real time to determine whether the user is "aiming" at the submenu
• 🚫 No False Triggers: Submenus won't flicker when the mouse moves diagonally across other menu items
• ⚡ Instant Response: No timeout-based delays — every interaction responds immediately
• 🔄 Multi-Level Nesting: Supports submenu nesting to any depth
• 📐 Multi-Direction: Supports four expand directions: right / left / down / up
• 🎨 Customizable: Flexible API and CSS customization
• 📦 Zero Dependencies: Only depends on React (>=17) — not bound to any UI library (e.g. antd), works standalone in any project

📦 Installation

# Install via npm (recommended)
npm install @jiongsen/react-menu-aim

# Or clone the repo for local development
git clone https://github.com/kkk360/react-menu-aim.git
cd react-aim
npm install
npm run dev        # Start dev server
npm run build:lib  # Build library version

🚀 Quick Start

import MenuAim from '@jiongsen/react-menu-aim';
import '@jiongsen/react-menu-aim/style.css';

const menuItems = [
  {
    key: 'file',
    label: 'File',
    children: [
      { key: 'new', label: 'New' },
      { key: 'open', label: 'Open...' },
      {
        key: 'export',
        label: 'Export',
        children: [
          { key: 'pdf', label: 'PDF' },
          { key: 'png', label: 'PNG' },
        ],
      },
    ],
  },
  {
    key: 'edit',
    label: 'Edit',
    children: [
      { key: 'undo', label: 'Undo' },
      { key: 'redo', label: 'Redo' },
    ],
  },
];

function App() {
  return <MenuAim items={menuItems} direction="right" />;
}

📖 API Reference

<MenuAim> Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | items | Array<MenuItem> | — | Array of menu item data | | direction | 'right' \| 'left' \| 'down' \| 'up' | 'right' | Submenu expand direction | | className | string | '' | Custom CSS class name |

MenuItem Data Structure

{
  key: string;           // Unique identifier
  label: string;         // Display text
  children?: MenuItem[]; // Optional submenu items
}

🔧 How It Works

The Problem with Traditional Menus

User wants to move the mouse diagonally from File → to the Export submenu
       ↘
    [File] ←── starting point
    [Edit] ←── mouse passes over this item, falsely triggering Edit's submenu!
    [View]

Traditional menus use a timeout delay to avoid this problem, but that makes interactions feel sluggish.

Menu-Aim's Solution

Instead of delays, Menu-Aim relies on direction detection to infer user intent:

1. When the mouse enters a menu item, record the entry point
2. When the submenu appears, build an aim triangle from the submenu's left edge and the entry point
3. When the mouse leaves the current menu item, check whether the cursor is inside that triangle
4. Inside the triangle → the user is aiming at the submenu → keep it open
5. Outside the triangle → the user is not aiming at the submenu → close / switch normally

         Submenu
    ┌─────────────┐
    │  New        │
    │  Open...    │ ← one edge of the aim triangle
    │  Save       │
    └─────────────┘
          ▲
          │  Aim Triangle
          │  (Entry Point → Submenu Edge)
          │
       [File] ← entry point
       [Edit]
       [View]

The "funnel" shape of the triangle guarantees that any diagonal path from a menu item to the submenu stays inside the triangle.

📁 Project Structure

src/
├── components/
│   └── MenuAim/
│       ├── MenuAim.jsx      # Main component with core logic
│       ├── MenuItem.jsx     # Menu item component
│       ├── MenuAim.css      # Styles
│       └── index.js         # Export entry
├── App.jsx                  # Demo page
├── App.css                  # Demo styles
└── index.css                # Global styles

🎨 Customization

All component class names are prefixed with menu-aim for easy style overrides:

/* Customize the menu list */
.menu-aim__list {
  background: #1a1a2e;
  border-color: #16213e;
}

/* Customize menu items */
.menu-aim__item {
  color: #e0e0e0;
}

.menu-aim__item:hover,
.menu-aim__item--active {
  background-color: #0f3460;
  color: #e94560;
}

🌐 Browser Support

• Chrome / Edge (recommended)
• Firefox
• Safari
• Any browser supporting CSS position: absolute and getBoundingClientRect

📝 License

MIT