syncfusion-react-menu

实现 Syncfusion React Menu 组件

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

何时使用此技能

• 构建导航菜单： 文件菜单、应用程序菜单、主导航栏
• 下拉菜单： 用户操作菜单、上下文相关选项
• 子菜单系统： 多级分层导航
• 汉堡菜单／移动端菜单： 适用于移动设备的自适应菜单
• 菜单自定义： 添加／移除项目、图标、分隔符、自定义样式
• 事件处理： 检测菜单项目点击、打开／关闭事件、项目状态变更
• 数据驱动菜单： 将菜单绑定到 JSON 数据结构（分层或自引用）
• 项目状态管理： 启用／禁用、显示／隐藏、更新菜单项目
• 无障碍功能： 创建支持键盘导航、便于屏幕阅读器使用的菜单
• RTL 支持： 从右向左书写语言的菜单
• 可滚动菜单： 支持水平／垂直滚动的大型菜单
• 状态持久化： 在页面重新加载后保存菜单状态

组件概述

主要功能

• 分层菜单，支持无限嵌套层级
• 数据绑定，支持分层或自引用 JSON 数据
• 支持图标和分隔符，方便进行视觉组织
• 事件系统，支持点击、打开、关闭和渲染交互
• 动画效果，可配置时间和缓动方式
• 键盘导航和符合 WCAG 的无障碍功能
• RTL 支持，适用于从右向左书写的语言
• 自适应布局，支持水平和垂直滚动
• 项目状态管理——动态添加、移除、启用／禁用、显示／隐藏项目
• 汉堡模式，适用于移动端自适应菜单
• 状态持久化——在页面重新加载后保存并恢复菜单状态
• HTML 清理，增强安全性
• 悬停延迟控制子菜单的显示时机
• 自定义 CSS 类，实现灵活的样式设置

何时选择 Menu 而非其他组件

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

快速开始

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;

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 使用 Vite/Create React App 安装并设置软件包
• CSS 导入和主题配置
• 使用 MenuItemModel 创建基本菜单
• 在 React 中集成 MenuComponent
• 首次渲染和初始化
• 涟漪效果
• 何时阅读： 开始新的 Menu 实现、设置项目时

属性和配置

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

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

方法和 API

📄 阅读： references/methods-api.md

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

事件和回调

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

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

数据绑定

📄 阅读： references/data-binding.md

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

菜单项自定义

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

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

样式和外观

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

• 图标集成和定位
• 分隔符的呈现和自定义
• 创建助记符 UI（键盘快捷键）
• RTL（从右向左）支持
• 自定义 CSS 类和主题集成
• 动画设置和效果
• 深色模式支持
• 何时阅读： 自定义外观、设置主题

汉堡菜单和移动模式

📄 阅读： references/hamburger-mode.md

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

使用场景

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

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

无障碍

📄 阅读： references/accessibility.md

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

快速入门示例

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;

关键属性参考

属性	类型	默认值	用途
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	-	汉堡菜单模式的标题文本

关键方法参考

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

关键事件参考

事件	触发条件	参数类型
select	点击菜单项	MenuEventArgs
beforeOpen	子菜单打开之前	BeforeOpenCloseMenuEventArgs
beforeClose	子菜单关闭之前	BeforeOpenCloseMenuEventArgs
onOpen	子菜单打开之后	OpenCloseMenuEventArgs
onClose	子菜单关闭之后	OpenCloseMenuEventArgs
beforeItemRender	菜单项渲染之前	BeforeItemRenderEventArgs
created	组件初始化时	Object

常见模式

模式 1：响应菜单项选择

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

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

模式 2：动态添加菜单项

let menuObj: MenuComponent;

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

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

模式 3：禁用菜单项

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

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

关键学习路径

1. 从这里开始： references/getting-started.md - 设置和创建基本菜单
2. 添加数据： references/data-binding.md - 将菜单绑定到数据源
3. 处理交互： references/events-and-callbacks.md - 响应用户操作
4. 动态控制： references/methods-api.md - 以编程方式操作菜单
5. 高级功能： references/hamburger-mode.md - 移动端响应式模式
6. 实际应用模式： references/use-case-scenarios.md - 生产环境中的实现

所有参考文件

基础知识

• getting-started.md - 安装、设置和 MenuItemModel 结构
• properties-and-configuration.md - 全部 24+ 个组件属性

数据与状态

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

交互与控制

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

演示与用户体验

• styling-and-appearance.md - 图标、主题、动画
• orientation-and-layout.md - 水平／垂直布局
• hamburger-mode.md - 移动端汉堡菜单
• accessibility.md - WCAG 合规性和键盘导航

旧版（原始文件）

• events-and-interactions.md - 基本事件处理（全面文档请参阅 events-and-callbacks.md）

实际应用实现

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

相关技能

• Implementing Sidebar - 侧边导航面板
• Implementing AppBar - 顶部导航／应用栏
• Implementing Tabs - 基于标签页的内容切换
• Implementing Accordion - 可展开的内容区块
• Implementing ListView - 基于列表的导航