syncfusion-react-menu

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing the Syncfusion React Menu Component

实现Syncfusion React Menu组件

The Syncfusion React Menu component is a flexible, feature-rich navigation control for creating hierarchical menu structures with support for icons, separators, animations, accessibility, hamburger mode, scrolling, event handling, and item state management. Use it to build navigation bars, dropdown menus, context menus, mobile-responsive menus, and complex hierarchical navigation systems.

Syncfusion React Menu组件是一款灵活且功能丰富的导航控件，可用于创建层级菜单结构，支持图标、分隔符、动画、无障碍访问、汉堡模式、滚动、事件处理和菜单项状态管理。可使用它构建导航栏、下拉菜单、上下文菜单、移动端响应式菜单以及复杂的层级导航系统。

When to Use This Skill

何时使用本技能

Building navigation menus: File menus, application menus, main navigation bars
Dropdown menus: User action menus, context-sensitive options
Sub-menu systems: Multi-level hierarchical navigation
Hamburger/mobile menus: Responsive menu for mobile devices
Menu customization: Adding/removing items, icons, separators, custom styling
Event handling: Detecting menu item clicks, open/close events, item state changes
Data-driven menus: Binding menus to JSON data structures (hierarchical or self-referential)
Item state management: Enabling/disabling, showing/hiding, updating menu items
Accessibility: Creating keyboard-navigable, screen reader-friendly menus
RTL support: Right-to-left language menus
Scrollable menus: Large menus with horizontal/vertical scrolling
Persistence: Saving menu state across page reloads

构建导航菜单：文件菜单、应用菜单、主导航栏
下拉菜单：用户操作菜单、上下文相关选项
子菜单系统：多级层级导航
汉堡/移动端菜单：面向移动设备的响应式菜单
菜单自定义：添加/移除菜单项、图标、分隔符、自定义样式
事件处理：检测菜单项点击、展开/收起事件、菜单项状态变化
数据驱动菜单：将菜单绑定到JSON数据结构（层级或自引用类型）
菜单项状态管理：启用/禁用、显示/隐藏、更新菜单项
无障碍访问：创建支持键盘导航、屏幕阅读器友好的菜单
RTL支持：适配从右到左语言的菜单
滚动菜单：支持横向/纵向滚动的大型菜单
状态持久化：在页面刷新后保存菜单状态

Component Overview

组件概述

Key Capabilities

核心功能

Hierarchical menus with unlimited nesting levels
Data binding to hierarchical or self-referential JSON data
Icon and separator support for visual organization
Event system for click, open, close, and render interactions
Animation effects with configurable timing and easing
Keyboard navigation and WCAG accessibility compliance
RTL support for right-to-left languages
Responsive layout with horizontal and vertical scrolling
Item state management - dynamically add, remove, enable/disable, show/hide items
Hamburger mode for mobile-responsive menus
State persistence - save and restore menu state across page reloads
HTML sanitization for security
Hover delay control for sub-menu timing
Custom CSS classes for flexible styling

层级菜单，支持无限嵌套层级
数据绑定，可绑定层级或自引用类型的JSON数据
图标与分隔符支持，实现视觉组织
事件系统，支持点击、展开、收起和渲染交互
动画效果，可配置时长和缓动效果
键盘导航，符合WCAG无障碍合规标准
RTL支持，适配从右到左语言
响应式布局，支持横向和纵向滚动
菜单项状态管理 - 动态添加、移除、启用/禁用、显示/隐藏菜单项
汉堡模式，用于移动端响应式菜单
状态持久化 - 在页面刷新后保存和恢复菜单状态
HTML清理，保障安全性
悬停延迟控制，自定义子菜单触发时机
自定义CSS类，实现灵活样式定制

When to Choose Menu Over Alternatives

何时选择Menu而非其他组件

Component	Best For
Menu	Hierarchical navigation, dropdown menus, file menus, hamburger menus
Navbar	Linear top navigation
Sidebar	Fixed side navigation panel
Tabs	Flat content sections with switching

组件	适用场景
Menu	层级导航、下拉菜单、文件菜单、汉堡菜单
Navbar	线性顶部导航
Sidebar	固定侧边导航面板
Tabs	可切换的扁平内容区域

Quick Start

快速开始

jsx

import { MenuComponent, MenuItemModel } from '@syncfusion/ej2-react-navigations';
import React from 'react';

function App() {
  const menuItems: MenuItemModel[] = [
    {
      text: 'File',
      items: [
        { text: 'New' },
        { text: 'Open' },
        { text: 'Save' }
      ]
    },
    {
      text: 'Edit',
      items: [
        { text: 'Cut' },
        { text: 'Copy' },
        { text: 'Paste' }
      ]
    }
  ];

  return (
    <MenuComponent items={menuItems}></MenuComponent>
  );
}

export default App;

jsx

import { MenuComponent, MenuItemModel } from '@syncfusion/ej2-react-navigations';
import React from 'react';

function App() {
  const menuItems: MenuItemModel[] = [
    {
      text: 'File',
      items: [
        { text: 'New' },
        { text: 'Open' },
        { text: 'Save' }
      ]
    },
    {
      text: 'Edit',
      items: [
        { text: 'Cut' },
        { text: 'Copy' },
        { text: 'Paste' }
      ]
    }
  ];

  return (
    <MenuComponent items={menuItems}></MenuComponent>
  );
}

export default App;

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and package setup with Vite/Create React App
CSS imports and theme configuration
Creating basic menu with MenuItemModel
MenuComponent integration in React
First render and initialization
Ripple effects
When to read: Starting a new Menu implementation, setting up project

📄 阅读： references/getting-started.md

使用Vite/Create React App进行安装和包配置
CSS导入与主题配置
使用MenuItemModel创建基础菜单
在React中集成MenuComponent
首次渲染与初始化
涟漪效果
阅读时机： 开始新的Menu实现、项目搭建阶段

Properties and Configuration

属性与配置

📄 Read: references/properties-and-configuration.md

All MenuComponent properties with descriptions
Default values and accepted types
Configuration examples for each property
animationSettings, cssClass, enableHtmlSanitizer, enablePersistence
enableRtl, enableScrolling, hamburgerMode, hoverDelay
locale, orientation, showItemOnClick, target, title
When to read: Configuring component behavior, setting animations, enabling features

📄 阅读： references/properties-and-configuration.md

所有MenuComponent属性及说明
默认值与接受类型
各属性的配置示例
animationSettings、cssClass、enableHtmlSanitizer、enablePersistence
enableRtl、enableScrolling、hamburgerMode、hoverDelay
locale、orientation、showItemOnClick、target、title
阅读时机： 配置组件行为、设置动画、启用功能

Methods and API

方法与API

📄 Read: references/methods-api.md

All MenuComponent methods with detailed documentation
insertBefore(), insertAfter(), removeItems() - item manipulation
enableItems(), hideItems(), showItems() - item state management
getItemIndex(), setItem() - item access and updates
open(), close() - hamburger mode control
destroy() - cleanup
Complete code examples for every method
When to read: Dynamically manipulating menu items, controlling menu state

📄 阅读： references/methods-api.md

所有MenuComponent方法的详细文档
insertBefore()、insertAfter()、removeItems() - 菜单项操作
enableItems()、hideItems()、showItems() - 菜单项状态管理
getItemIndex()、setItem() - 菜单项访问与更新
open()、close() - 汉堡模式控制
destroy() - 清理资源
每个方法的完整代码示例
阅读时机： 动态操作菜单项、控制菜单状态

Events and Callbacks

事件与回调

📄 Read: references/events-and-callbacks.md

All event types with complete documentation
Event arguments: MenuEventArgs, BeforeOpenCloseMenuEventArgs, OpenCloseMenuEventArgs
select, beforeOpen, beforeClose, onOpen, onClose events
beforeItemRender and created lifecycle events
Event handling patterns and callback examples
When to read: Responding to user interactions, handling lifecycle events

📄 阅读： references/events-and-callbacks.md

所有事件类型的完整文档
事件参数：MenuEventArgs、BeforeOpenCloseMenuEventArgs、OpenCloseMenuEventArgs
select、beforeOpen、beforeClose、onOpen、onClose事件
beforeItemRender和created生命周期事件
事件处理模式与回调示例
阅读时机： 响应用户交互、处理生命周期事件

Data Binding

数据绑定

📄 Read: references/data-binding.md

Hierarchical data binding
Self-referential data structures
JSON data mapping with FieldSettingsModel
Complex nested data hierarchies
Dynamic data updates and modifications
Real-time data from APIs
When to read: Populating menus from data sources

📄 阅读： references/data-binding.md

层级数据绑定
自引用数据结构
使用FieldSettingsModel映射JSON数据
复杂嵌套数据层级
动态数据更新与修改
来自API的实时数据
阅读时机： 从数据源填充菜单

Menu Item Customization

菜单项自定义

📄 Read: references/menu-items-customization.md

Adding menu items with insertBefore/insertAfter
Removing items with removeItems
Enabling/disabling items with enableItems
Showing/hiding items with showItems/hideItems
Custom HTML attributes
Separator support
When to read: Dynamically managing menu structure

📄 阅读： references/menu-items-customization.md

使用insertBefore/insertAfter添加菜单项
使用removeItems移除菜单项
使用enableItems启用/禁用菜单项
使用showItems/hideItems显示/隐藏菜单项
自定义HTML属性
分隔符支持
阅读时机： 动态管理菜单结构

Styling and Appearance

样式与外观

📄 Read: references/styling-and-appearance.md

Icon integration and positioning
Separator rendering and customization
Mnemonic UI creation (keyboard shortcuts)
RTL (Right-to-left) support
Custom CSS classes and theme integration
Animation settings and effects
Dark mode support
When to read: Customizing appearance, theming

📄 阅读： references/styling-and-appearance.md

图标集成与定位
分隔符渲染与自定义
助记UI创建（键盘快捷键）
RTL（从右到左）支持
自定义CSS类与主题集成
动画设置与效果
深色模式支持
阅读时机： 自定义外观、主题定制

Hamburger and Mobile Mode

汉堡与移动端模式

📄 Read: references/hamburger-mode.md

Hamburger mode setup and configuration
Mobile responsive implementation
hamburgerMode, target, title properties
open() and close() methods
Integration with Sidebar and Accordion
Mobile-first design patterns
When to read: Building mobile-responsive menus

📄 阅读： references/hamburger-mode.md

汉堡模式的设置与配置
移动端响应式实现
hamburgerMode、target、title属性
open()和close()方法
与Sidebar和Accordion集成
移动端优先设计模式
阅读时机： 构建移动端响应式菜单

Use Case Scenarios

用例场景

📄 Read: references/use-case-scenarios.md

Scrollable menu implementation
Menu in Toolbar integration
Hamburger menu with Sidebar
Mobile view with ListView
Context menu patterns
Dynamic data-driven menus
When to read: Building specific menu patterns for real-world scenarios

📄 阅读： references/use-case-scenarios.md

滚动菜单实现
菜单与Toolbar集成
带Sidebar的汉堡菜单
结合ListView的移动端视图
上下文菜单模式
动态数据驱动菜单
阅读时机： 为实际场景构建特定菜单模式

Accessibility

无障碍访问

📄 Read: references/accessibility.md

WCAG compliance standards
WAI-ARIA attributes
Keyboard navigation patterns
Screen reader support
Focus management
Color contrast guidelines
Testing accessibility
When to read: Ensuring menu is accessible to all users

📄 阅读： references/accessibility.md

WCAG合规标准
WAI-ARIA属性
键盘导航模式
屏幕阅读器支持
焦点管理
颜色对比度指南
无障碍测试
阅读时机： 确保菜单对所有用户无障碍

Quick Start Example

快速启动示例

jsx

import { MenuComponent, MenuItemModel } from '@syncfusion/ej2-react-navigations';
import * as React from 'react';

function App() {
  // Define menu structure
  const menuItems: MenuItemModel[] = [
    {
      text: 'File',
      items: [
        { text: 'New' },
        { text: 'Open' },
        { text: 'Save' },
        { separator: true },
        { text: 'Exit' }
      ]
    },
    {
      text: 'Edit',
      items: [
        { text: 'Cut' },
        { text: 'Copy' },
        { text: 'Paste' }
      ]
    },
    {
      text: 'Help'
    }
  ];

  return (
    <MenuComponent items={menuItems}></MenuComponent>
  );
}

export default App;

jsx

import { MenuComponent, MenuItemModel } from '@syncfusion/ej2-react-navigations';
import * as React from 'react';

function App() {
  // Define menu structure
  const menuItems: MenuItemModel[] = [
    {
      text: 'File',
      items: [
        { text: 'New' },
        { text: 'Open' },
        { text: 'Save' },
        { separator: true },
        { text: 'Exit' }
      ]
    },
    {
      text: 'Edit',
      items: [
        { text: 'Cut' },
        { text: 'Copy' },
        { text: 'Paste' }
      ]
    },
    {
      text: 'Help'
    }
  ];

  return (
    <MenuComponent items={menuItems}></MenuComponent>
  );
}

export default App;

Key Properties Reference

核心属性参考

Property	Type	Default	Purpose
`items`	MenuItemModel[]	[]	Menu items to render
`fields`	FieldSettingsModel	-	Data field mappings
`hamburgerMode`	boolean	false	Enable mobile hamburger view
`enableScrolling`	boolean	true	Allow scrolling for large menus
`enablePersistence`	boolean	false	Save state across sessions
`enableRtl`	boolean	false	Right-to-left text support
`orientation`	Orientation	Horizontal	Layout direction
`animationSettings`	MenuAnimationSettings	-	Animation configuration
`hoverDelay`	number	400	Sub-menu hover delay (ms)
`showItemOnClick`	boolean	false	Show items only on click
`enableHtmlSanitizer`	boolean	true	Sanitize HTML content
`cssClass`	string	-	Custom CSS classes
`locale`	string	'en-US'	Culture/language setting
`target`	string	-	Element selector for hamburger
`title`	string	-	Hamburger mode title text

属性	类型	默认值	用途
`items`	MenuItemModel[]	[]	要渲染的菜单项
`fields`	FieldSettingsModel	-	数据字段映射
`hamburgerMode`	boolean	false	启用移动端汉堡视图
`enableScrolling`	boolean	true	允许大型菜单滚动
`enablePersistence`	boolean	false	在会话间保存状态
`enableRtl`	boolean	false	支持从右到左文本
`orientation`	Orientation	Horizontal	布局方向
`animationSettings`	MenuAnimationSettings	-	动画配置
`hoverDelay`	number	400	子菜单悬停延迟（毫秒）
`showItemOnClick`	boolean	false	仅在点击时显示菜单项
`enableHtmlSanitizer`	boolean	true	清理HTML内容
`cssClass`	string	-	自定义CSS类
`locale`	string	'en-US'	区域/语言设置
`target`	string	-	汉堡模式的元素选择器
`title`	string	-	汉堡模式的标题文本

Key Methods Reference

核心方法参考

Method	Parameters	Purpose
`insertBefore()`	item, selector	Insert before a menu item
`insertAfter()`	item, selector	Insert after a menu item
`removeItems()`	selectors	Remove items by selector
`enableItems()`	selectors, enable	Enable/disable items
`showItems()`	selectors	Show hidden items
`hideItems()`	selectors	Hide visible items
`setItem()`	item, selector	Update item properties
`getItemIndex()`	selector	Get item index in menu
`open()`	-	Open hamburger menu
`close()`	-	Close hamburger menu
`destroy()`	-	Cleanup component

方法	参数	用途
`insertBefore()`	item, selector	在指定菜单项前插入
`insertAfter()`	item, selector	在指定菜单项后插入
`removeItems()`	selectors	通过选择器移除菜单项
`enableItems()`	selectors, enable	启用/禁用菜单项
`showItems()`	selectors	显示隐藏的菜单项
`hideItems()`	selectors	隐藏可见的菜单项
`setItem()`	item, selector	更新菜单项属性
`getItemIndex()`	selector	获取菜单项在菜单中的索引
`open()`	-	打开汉堡菜单
`close()`	-	关闭汉堡菜单
`destroy()`	-	清理组件资源

Key Events Reference

核心事件参考

Event	Trigger	Argument Type
`select`	Menu item clicked	MenuEventArgs
`beforeOpen`	Before sub-menu opens	BeforeOpenCloseMenuEventArgs
`beforeClose`	Before sub-menu closes	BeforeOpenCloseMenuEventArgs
`onOpen`	After sub-menu opens	OpenCloseMenuEventArgs
`onClose`	After sub-menu closes	OpenCloseMenuEventArgs
`beforeItemRender`	Before item renders	BeforeItemRenderEventArgs
`created`	Component initialized	Object

事件	触发时机	参数类型
`select`	菜单项被点击时	MenuEventArgs
`beforeOpen`	子菜单展开前	BeforeOpenCloseMenuEventArgs
`beforeClose`	子菜单收起前	BeforeOpenCloseMenuEventArgs
`onOpen`	子菜单展开后	OpenCloseMenuEventArgs
`onClose`	子菜单收起后	OpenCloseMenuEventArgs
`beforeItemRender`	菜单项渲染前	BeforeItemRenderEventArgs
`created`	组件初始化完成后	Object

Common Patterns

常见模式

Pattern 1: Responding to Menu Item Selection

模式1：响应菜单项选择

jsx

const handleMenuSelect = (args) => {
  console.log(`Selected: ${args.item.text}`);
  // Handle the selected menu item
};

<MenuComponent 
  items={menuItems} 
  select={handleMenuSelect}
></MenuComponent>

jsx

const handleMenuSelect = (args) => {
  console.log(`Selected: ${args.item.text}`);
  // Handle the selected menu item
};

<MenuComponent 
  items={menuItems} 
  select={handleMenuSelect}
></MenuComponent>

Pattern 2: Dynamically Adding Menu Items

模式2：动态添加菜单项

jsx

let menuObj: MenuComponent;

const addMenuItem = () => {
  menuObj.insertAfter([{ text: 'New Item' }], 'File');
};

<MenuComponent 
  ref={(menu) => (menuObj = menu)} 
  items={menuItems}
></MenuComponent>

jsx

let menuObj: MenuComponent;

const addMenuItem = () => {
  menuObj.insertAfter([{ text: 'New Item' }], 'File');
};

<MenuComponent 
  ref={(menu) => (menuObj = menu)} 
  items={menuItems}
></MenuComponent>

Pattern 3: Disabling Menu Items

模式3：禁用菜单项

jsx

const handleBeforeOpen = (args) => {
  if (args.item.text === 'Save') {
    args.item.disabled = true; // Disable based on condition
  }
};

<MenuComponent 
  items={menuItems} 
  beforeOpen={handleBeforeOpen}
></MenuComponent>

jsx

const handleBeforeOpen = (args) => {
  if (args.item.text === 'Save') {
    args.item.disabled = true; // Disable based on condition
  }
};

<MenuComponent 
  items={menuItems} 
  beforeOpen={handleBeforeOpen}
></MenuComponent>

Key Learning Path

核心学习路径

Start Here: references/getting-started.md - Setup and basic menu creation
Add Data: references/data-binding.md - Bind menus to data sources
Handle Interaction: references/events-and-callbacks.md - Respond to user actions
Dynamic Control: references/methods-api.md - Manipulate menus programmatically
Advanced Features: references/hamburger-mode.md - Mobile-responsive patterns
Real-World Patterns: references/use-case-scenarios.md - Production implementations

入门： references/getting-started.md - 安装与基础菜单创建
数据绑定： references/data-binding.md - 将菜单绑定到数据源
交互处理： references/events-and-callbacks.md - 响应用户操作
动态控制： references/methods-api.md - 以编程方式操作菜单
高级功能： references/hamburger-mode.md - 移动端响应式模式
实战模式： references/use-case-scenarios.md - 生产环境实现

All Reference Files

所有参考文件

Fundamentals

基础部分

getting-started.md - Installation, setup, MenuItemModel structure
properties-and-configuration.md - All 24+ component properties

getting-started.md - 安装、配置、MenuItemModel结构
properties-and-configuration.md - 所有24+组件属性

Data & State

数据与状态

data-binding.md - Hierarchical and self-referential binding
menu-items-customization.md - Dynamic item management

data-binding.md - 层级与自引用绑定
menu-items-customization.md - 动态菜单项管理

Interaction & Control

交互与控制

events-and-callbacks.md - Event system and callbacks
methods-api.md - All methods for programmatic control

events-and-callbacks.md - 事件系统与回调
methods-api.md - 所有用于编程控制的方法

Presentation & UX

展示与用户体验

styling-and-appearance.md - Icons, themes, animations
orientation-and-layout.md - Horizontal/vertical layouts
hamburger-mode.md - Mobile hamburger menus
accessibility.md - WCAG compliance and keyboard navigation

styling-and-appearance.md - 图标、主题、动画
orientation-and-layout.md - 横向/纵向布局
hamburger-mode.md - 移动端汉堡菜单
accessibility.md - WCAG合规与键盘导航

Legacy (Original Files)

遗留文件（原始文件）

events-and-interactions.md - Basic event handling (see events-and-callbacks.md for comprehensive documentation)

events-and-interactions.md - 基础事件处理（如需完整文档请查看events-and-callbacks.md）

Real-World Implementation

实战实现

use-case-scenarios.md - 8 complete patterns: file menus, toolbars, sidebars, dashboards, mobile apps, etc.

use-case-scenarios.md - 8种完整模式：文件菜单、工具栏、侧边栏、仪表盘、移动应用等