syncfusion-angular-menu

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Angular Menu Component

Syncfusion Angular Menu组件实现指南

The Menu component is a graphical user interface that serves as a navigation header for your application or site. It supports multi-level nested menu items, rich customization, data binding, templates, animations, comprehensive event handling, internationalization, state persistence, and mobile-friendly hamburger mode.

Menu组件是一种图形用户界面元素，可作为应用或网站的导航头部。它支持多级嵌套菜单项、丰富的自定义功能、数据绑定、模板、动画、全面的事件处理、国际化、状态持久化以及移动端友好的汉堡菜单模式。

When to Use This Skill

何时使用本指南

Use this skill when you need to:

Create navigation menus with hierarchical structures
Bind data from arrays or remote sources
Customize menu items dynamically (add, remove, enable, disable)
Handle menu events (click, open, close, select)
Apply animations and control orientation
Add icons, images, and navigation URLs to menu items
Implement accessibility features
Style and theme the menu
Build real-world patterns (sidebar menus, toolbar menus, context menus)

当你需要以下功能时，可使用本指南：

创建带层级结构的导航菜单
绑定数组或远程数据源
动态自定义菜单项（添加、删除、启用、禁用）
处理菜单事件（点击、打开、关闭、选择）
应用动画并控制菜单方向
为菜单项添加图标、图片和导航URL
实现无障碍访问功能
为菜单设置样式和主题
构建实际场景模式（侧边栏菜单、工具栏菜单、上下文菜单）

Component Overview

组件概述

Key Features:

✅ Hierarchical and self-referential data binding
✅ HTML templates and custom item rendering
✅ Multi-level submenu support with nesting
✅ Multiple animation effects (FadeIn, SlideDown, ZoomIn)
✅ Horizontal and vertical orientation
✅ Icon and image support
✅ Enable/disable, show/hide menu items dynamically
✅ Event-driven customization
✅ RTL (Right-to-Left) support
✅ Accessibility features (keyboard navigation, ARIA)
✅ CSS customization and theming

核心特性：

✅ 层级和自引用数据绑定
✅ HTML模板和自定义项渲染
✅ 多级子菜单嵌套支持
✅ 多种动画效果（FadeIn、SlideDown、ZoomIn）
✅ 横向和纵向布局
✅ 图标和图片支持
✅ 动态启用/禁用、显示/隐藏菜单项
✅ 事件驱动的自定义
✅ RTL（从右到左）布局支持
✅ 无障碍访问特性（键盘导航、ARIA）
✅ CSS自定义和主题配置

Documentation and Navigation Guide

文档与导航指南

📖 Core Documentation (Start Here)

📖 核心文档（从这里开始）

1️⃣ Getting Started

1️⃣ 快速入门

📄 Read: references/getting-started.md (Start here for new users)

✅ Installation and package setup
✅ Basic menu implementation
✅ CSS imports and theme configuration
✅ Essential properties (enablePersistence, enableRtl, cssClass, hoverDelay, enableScrolling, locale)
✅ Standalone architecture setup
✅ First application example

📄 阅读： references/getting-started.md (新用户从这里开始)

✅ 安装和包配置
✅ 基础菜单实现
✅ CSS导入和主题配置
✅ 核心属性（enablePersistence、enableRtl、cssClass、hoverDelay、enableScrolling、locale）
✅ 独立架构设置
✅ 首个应用示例

2️⃣ Data Source Binding and Templates

2️⃣ 数据源绑定与模板

📄 Read: references/data-source-binding.md

✅ Hierarchical data binding with field mappings
✅ Self-referential data structures
✅ Remote data binding with DataManager
✅ HTML templates and custom item rendering
✅ Dynamic data population
✅ FieldSettingsModel configuration

📄 阅读： references/data-source-binding.md

✅ 带字段映射的层级数据绑定
✅ 自引用数据结构
✅ 通过DataManager绑定远程数据
✅ HTML模板和自定义项渲染
✅ 动态数据填充
✅ FieldSettingsModel配置

3️⃣ Menu Items Customization & Dynamic Management

3️⃣ 菜单项自定义与动态管理

📄 Read: references/menu-items.md (Now includes methods!)

✅ Menu item properties (text, id, iconCss, url, separator)
✅ Icons and images in menu items
✅ Navigation URLs
✅ Custom attributes (htmlAttributes)
✅ NEW: Dynamic Methods Reference:
- ```
insertBefore()
```
  - Add items before a target
- ```
insertAfter()
```
  - Add items after a target
- ```
removeItems()
```
  - Delete menu items
- ```
enableItems()
```
  - Enable/disable items
- ```
showItems()
```
  - Display hidden items
- ```
hideItems()
```
  - Hide menu items
✅ Enable/disable menu items
✅ Show/hide menu items
✅ Add, remove, insert menu items dynamically
✅ Separators for grouping items
✅ Complete dynamic menu management example

📄 阅读： references/menu-items.md (新增方法参考!)

✅ 菜单项属性（text、id、iconCss、url、separator）
✅ 菜单项中的图标和图片
✅ 导航URL
✅ 自定义属性（htmlAttributes）
✅ 新增： 动态方法参考:
- ```
insertBefore()
```
  - 在目标项前添加菜单项
- ```
insertAfter()
```
  - 在目标项后添加菜单项
- ```
removeItems()
```
  - 删除菜单项
- ```
enableItems()
```
  - 启用/禁用菜单项
- ```
showItems()
```
  - 显示隐藏的菜单项
- ```
hideItems()
```
  - 隐藏菜单项
✅ 启用/禁用菜单项
✅ 显示/隐藏菜单项
✅ 动态添加、删除、插入菜单项
✅ 用于分组的分隔符
✅ 完整的动态菜单管理示例

4️⃣ Animation and Orientation

4️⃣ 动画与布局方向

📄 Read: references/animation-and-orientation.md

✅ Animation settings (effect, duration, easing)
✅ Animation effects (FadeIn, SlideDown, ZoomIn, None)
✅ Horizontal and vertical orientation
✅ Sub-menu positioning and behavior
✅ Menu open-on-click vs hover behavior

📄 阅读： references/animation-and-orientation.md

✅ 动画设置（效果、时长、缓动函数）
✅ 动画效果（FadeIn、SlideDown、ZoomIn、None）
✅ 横向和纵向布局
✅ 子菜单定位与行为
✅ 菜单点击触发打开 vs 悬停触发打开

5️⃣ Events and Interactions

5️⃣ 事件与交互

📄 Read: references/events-and-interactions.md (Enhanced with event arguments)

✅ Event overview (7 events documented)
✅ NEW: Complete Event Arguments Documentation:
- ```
BeforeOpenCloseMenuEventArgs
```
  - beforeOpen/beforeClose events
- ```
OpenCloseMenuEventArgs
```
  - onOpen/onClose events
- ```
MenuEventArgs
```
  - select/beforeItemRender events
✅ beforeOpen and beforeClose events (cancelable)
✅ onOpen and onClose events
✅ Select event handling
✅ beforeItemRender event (for tooltips and custom rendering)
✅ Created event for initialization
✅ Dynamic menu modification through events

📄 阅读： references/events-and-interactions.md (新增事件参数文档)

✅ 事件概述（7个已文档化的事件）
✅ 新增： 完整的事件参数文档:
- ```
BeforeOpenCloseMenuEventArgs
```
  - beforeOpen/beforeClose事件
- ```
OpenCloseMenuEventArgs
```
  - onOpen/onClose事件
- ```
MenuEventArgs
```
  - select/beforeItemRender事件
✅ beforeOpen和beforeClose事件（可取消）
✅ onOpen和onClose事件
✅ 选择事件处理
✅ beforeItemRender事件（用于提示框和自定义渲染）
✅ 初始化完成的Created事件
✅ 通过事件动态修改菜单

🎯 Advanced Features & Patterns

🎯 高级特性与模式

6️⃣ Complete API Reference

6️⃣ 完整API参考

📄 Read: references/api-reference.md (Comprehensive API documentation!)

✅ All MenuModel properties with examples (16 properties)
✅ All MenuItem properties with examples (7 properties)
✅ Animation settings configuration
✅ Field settings for data binding
✅ All Menu Methods with signatures and examples:
- insertBefore(), insertAfter(), removeItems()
- enableItems(), showItems(), hideItems()
✅ All Menu Events with arguments
✅ Event arguments interfaces
✅ Enumerations (Orientation, MenuEffect, MenuOpenType)
✅ Quick reference summary

📄 阅读： references/api-reference.md (全面的API文档!)

✅ 所有MenuModel属性及示例（16个属性）
✅ 所有MenuItem属性及示例（7个属性）
✅ 动画设置配置
✅ 数据绑定字段设置
✅ 所有Menu方法及签名和示例:
- insertBefore()、insertAfter()、removeItems()
- enableItems()、showItems()、hideItems()
✅ 所有Menu事件及参数
✅ 事件参数接口
✅ 枚举类型（Orientation、MenuEffect、MenuOpenType）
✅ 快速参考摘要

7️⃣ Hamburger Mode and Responsive Design

7️⃣ 汉堡菜单模式与响应式设计

📄 Read: references/hamburger-and-responsive.md (Mobile-first design)

✅ Hamburger mode overview
✅ hamburgerMode property configuration
✅ target and title properties
✅ Basic hamburger implementation
✅ Responsive toggle (Desktop/Mobile)
✅ Hamburger with animations
✅ Complete mobile menu solution
✅ State persistence with hamburger
✅ Accessibility best practices
✅ Touch-friendly interactions

📄 阅读： references/hamburger-and-responsive.md (移动端优先设计)

✅ 汉堡菜单模式概述
✅ hamburgerMode属性配置
✅ target和title属性
✅ 基础汉堡菜单实现
✅ 响应式切换（桌面/移动端）
✅ 带动画的汉堡菜单
✅ 完整的移动端菜单解决方案
✅ 汉堡菜单状态持久化
✅ 无障碍访问最佳实践
✅ 触控友好的交互

8️⃣ Internationalization and State Management

8️⃣ 国际化与状态管理

📄 Read: references/internationalization-and-persistence.md (i18n + Storage)

✅ Localization (i18n) with 15+ locales
✅ RTL language support (Arabic, Hebrew, Persian)
✅ State persistence (enablePersistence)
✅ HTML sanitization (enableHtmlSanitizer)
✅ Hover delay control (hoverDelay)
✅ Custom CSS classes (cssClass)
✅ Advanced configuration patterns
✅ Complete setup example

📄 阅读： references/internationalization-and-persistence.md (i18n + 存储)

✅ 本地化（i18n）支持15+种语言
✅ RTL语言支持（阿拉伯语、希伯来语、波斯语）
✅ 状态持久化（enablePersistence）
✅ HTML内容清理（enableHtmlSanitizer）
✅ 悬停延迟控制（hoverDelay）
✅ 自定义CSS类（cssClass）
✅ 高级配置模式
✅ 完整设置示例

9️⃣ Styling and Appearance

9️⃣ 样式与外观

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

✅ CSS styling and custom classes
✅ Rounded corner styling
✅ Title and icon positioning
✅ Theme customization
✅ Material3 and other theme integration
✅ CSS variable customization

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

✅ CSS样式和自定义类
✅ 圆角样式
✅ 标题和图标定位
✅ 主题自定义
✅ Material3及其他主题集成
✅ CSS变量自定义

🔟 Advanced Features and Scrolling

🔟 高级特性与滚动

📄 Read: references/advanced-features.md

✅ Right-to-Left (RTL) language support
✅ Horizontal and vertical scrolling
✅ Large menu handling
✅ Menu item grouping with separators
✅ Accessibility features (keyboard navigation, ARIA)
✅ Nested submenu patterns

📄 阅读： references/advanced-features.md

✅ 从右到左（RTL）语言支持
✅ 横向和纵向滚动
✅ 大型菜单处理
✅ 使用分隔符分组菜单项
✅ 无障碍访问特性（键盘导航、ARIA）
✅ 嵌套子菜单模式

1️⃣1️⃣ Use Cases and Real-World Patterns

1️⃣1️⃣ 使用场景与实际模式

📄 Read: references/use-cases-and-scenarios.md

✅ Sidebar menu implementations
✅ Toolbar menu patterns
✅ Context menu scenarios
✅ ListView and other component integrations
✅ Multi-level menu structures
✅ Mobile navigation
✅ Admin dashboard patterns
✅ Best practices and common patterns

📄 阅读： references/use-cases-and-scenarios.md

✅ 侧边栏菜单实现
✅ 工具栏菜单模式
✅ 上下文菜单场景
✅ ListView及其他组件集成
✅ 多级菜单结构
✅ 移动端导航
✅ 后台仪表盘模式
✅ 最佳实践与通用模式

🔍 Quick Access by Task

🔍 按任务快速访问

I need to...

▶️ Install and get started → getting-started.md
▶️ Add dynamic menu items → menu-items.md
▶️ Bind data from array/API → data-source-binding.md
▶️ Handle menu clicks and events → events-and-interactions.md
▶️ Add animations → animation-and-orientation.md
▶️ Make mobile-friendly menu → hamburger-and-responsive.md
▶️ Support multiple languages → internationalization-and-persistence.md
▶️ Find all properties/methods/events → api-reference.md
▶️ Style and customize appearance → styling-and-appearance.md
▶️ Build production pattern → use-cases-and-scenarios.md

我需要...

▶️ 安装并快速入门 → getting-started.md
▶️ 添加动态菜单项 → menu-items.md
▶️ 绑定数组/API数据源 → data-source-binding.md
▶️ 处理菜单点击和事件 → events-and-interactions.md
▶️ 添加动画 → animation-and-orientation.md
▶️ 创建移动端友好菜单 → hamburger-and-responsive.md
▶️ 支持多语言 → internationalization-and-persistence.md
▶️ 查找所有属性/方法/事件 → api-reference.md
▶️ 设置样式和自定义外观 → styling-and-appearance.md
▶️ 构建生产环境模式 → use-cases-and-scenarios.md

Quick Start Example

快速入门示例

typescript

import { Component } from '@angular/core';
import { MenuModule } from '@syncfusion/ej2-angular-navigations';
import { MenuItemModel } from '@syncfusion/ej2-angular-navigations';
import { enableRipple } from '@syncfusion/ej2-base';

enableRipple(true);

@Component({
  imports: [MenuModule],
  standalone: true,
  selector: 'app-root',
  template: `<ejs-menu [items]="menuItems"></ejs-menu>`
})
export class AppComponent {
  public menuItems: MenuItemModel[] = [
    {
      text: 'File',
      items: [
        { text: 'Open' },
        { text: 'Save' },
        { separator: true },
        { text: 'Exit' }
      ]
    },
    {
      text: 'Edit',
      items: [
        { text: 'Cut' },
        { text: 'Copy' },
        { text: 'Paste' }
      ]
    },
    { text: 'Help' }
  ];
}

CSS Setup:

css

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-navigations/styles/material3.css';

typescript

import { Component } from '@angular/core';
import { MenuModule } from '@syncfusion/ej2-angular-navigations';
import { MenuItemModel } from '@syncfusion/ej2-angular-navigations';
import { enableRipple } from '@syncfusion/ej2-base';

enableRipple(true);

@Component({
  imports: [MenuModule],
  standalone: true,
  selector: 'app-root',
  template: `<ejs-menu [items]="menuItems"></ejs-menu>`
})
export class AppComponent {
  public menuItems: MenuItemModel[] = [
    {
      text: 'File',
      items: [
        { text: 'Open' },
        { text: 'Save' },
        { separator: true },
        { text: 'Exit' }
      ]
    },
    {
      text: 'Edit',
      items: [
        { text: 'Cut' },
        { text: 'Copy' },
        { text: 'Paste' }
      ]
    },
    { text: 'Help' }
  ];
}

CSS设置:

css

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-navigations/styles/material3.css';

Common Patterns

通用模式

1. Menu with Icons

1. 带图标的菜单

typescript

public menuItems: MenuItemModel[] = [
  {
    text: 'File',
    iconCss: 'e-icons e-file',
    items: [
      { text: 'Open', iconCss: 'e-icons e-open' },
      { text: 'Save', iconCss: 'e-icons e-save' }
    ]
  }
];

typescript

public menuItems: MenuItemModel[] = [
  {
    text: 'File',
    iconCss: 'e-icons e-file',
    items: [
      { text: 'Open', iconCss: 'e-icons e-open' },
      { text: 'Save', iconCss: 'e-icons e-save' }
    ]
  }
];

2. Menu with Animation

2. 带动画的菜单

typescript

public animationSettings: MenuAnimationSettingsModel = {
  effect: 'FadeIn',
  duration: 800
};

Use in template:

<ejs-menu [animationSettings]="animationSettings"></ejs-menu>

typescript

public animationSettings: MenuAnimationSettingsModel = {
  effect: 'FadeIn',
  duration: 800
};

在模板中使用:

<ejs-menu [animationSettings]="animationSettings"></ejs-menu>

3. Menu with Events

3. 带事件的菜单

typescript

public onItemSelect(args: MenuEventArgs): void {
  console.log('Selected item:', args.item.text);
}

Use in template:

<ejs-menu (select)="onItemSelect($event)"></ejs-menu>

typescript

public onItemSelect(args: MenuEventArgs): void {
  console.log('Selected item:', args.item.text);
}

在模板中使用:

<ejs-menu (select)="onItemSelect($event)"></ejs-menu>

4. Dynamic Menu Modification

4. 动态修改菜单

typescript

@ViewChild('menu')
public menuObj?: MenuComponent;

public addItem(): void {
  const newItem: MenuItemModel[] = [
    { text: 'New Menu Item' }
  ];
  this.menuObj?.insertAfter(newItem, 'File', false);
}

typescript

@ViewChild('menu')
public menuObj?: MenuComponent;

public addItem(): void {
  const newItem: MenuItemModel[] = [
    { text: 'New Menu Item' }
  ];
  this.menuObj?.insertAfter(newItem, 'File', false);
}

Complete API Reference

完整API参考

The Menu component includes 16 component properties, 7 menu item properties, 7 events, 3 animation properties, 6 field settings properties, and 10+ methods.

See references/api-reference.md for complete documentation of:

✅ All MenuModel properties with examples
✅ All MenuItem properties with examples
✅ All methods (insertBefore, insertAfter, removeItems, enableItems, showItems, hideItems)
✅ All events with event arguments
✅ Enumerations and quick reference

Menu组件包含16个组件属性、7个菜单项属性、7个事件、3个动画属性、6个字段设置属性以及10+个方法。

查看references/api-reference.md获取完整文档:

✅ 所有MenuModel属性及示例
✅ 所有MenuItem属性及示例
✅ 所有方法（insertBefore、insertAfter、removeItems、enableItems、showItems、hideItems）
✅ 所有事件及事件参数
✅ 枚举类型和快速参考

Key Properties

核心属性

Essential Properties (Most Used)

常用核心属性

Property	Type	Purpose	Default
`items`	`MenuItemModel[]`	Array of menu items to render	`[]`
`fields`	`FieldSettingsModel`	Maps data source fields to menu structure	-
`template`	`string`	Custom template for menu items	-
`animationSettings`	`MenuAnimationSettingsModel`	Controls menu animation behavior	-
`orientation`	`Orientation`	'Horizontal' or 'Vertical'	`'Horizontal'`
`showItemOnClick`	`boolean`	Open submenu on click (true) or hover (false)	`false`
`cssClass`	`string`	Custom CSS class for styling	-
`enableRtl`	`boolean`	Enable right-to-left layout	`false`

属性	类型	用途	默认值
`items`	`MenuItemModel[]`	用于渲染的菜单项数组	`[]`
`fields`	`FieldSettingsModel`	将数据源字段映射到菜单结构	-
`template`	`string`	菜单项的自定义模板	-
`animationSettings`	`MenuAnimationSettingsModel`	控制菜单动画行为	-
`orientation`	`Orientation`	'Horizontal'（横向）或 'Vertical'（纵向）	`'Horizontal'`
`showItemOnClick`	`boolean`	点击（true）或悬停（false）打开子菜单	`false`
`cssClass`	`string`	用于样式设置的自定义CSS类	-
`enableRtl`	`boolean`	启用从右到左布局	`false`

Advanced Properties (For Special Cases)

高级属性（特殊场景使用）

Property	Type	Purpose	Default
`hamburgerMode`	`boolean`	Enable mobile hamburger menu	`false`
`target`	`string`	Hamburger toggle button selector	-
`title`	`string`	Title for hamburger drawer	-
`enablePersistence`	`boolean`	Save menu state to localStorage	`false`
`enableScrolling`	`boolean`	Enable scrollbar for large menus	`false`
`enableHtmlSanitizer`	`boolean`	Sanitize HTML content (security)	`true`
`hoverDelay`	`number`	Delay before submenu opens (ms)	`0`
`locale`	`string`	Localization culture code	`'en-US'`

属性	类型	用途	默认值
`hamburgerMode`	`boolean`	启用移动端汉堡菜单	`false`
`target`	`string`	汉堡菜单切换按钮的选择器	-
`title`	`string`	汉堡菜单抽屉的标题	-
`enablePersistence`	`boolean`	将菜单状态保存到localStorage	`false`
`enableScrolling`	`boolean`	为大型菜单启用滚动条	`false`
`enableHtmlSanitizer`	`boolean`	清理HTML内容（安全特性）	`true`
`hoverDelay`	`number`	子菜单打开前的延迟（毫秒）	`0`
`locale`	`string`	本地化语言代码	`'en-US'`

Common Use Cases

常见使用场景

Application Menu Bar - File, Edit, View, Tools menus with submenus
Navigation Sidebar - Vertical menu for page navigation
Toolbar Menu - Horizontal menu with icons and commands
Context Menu - Right-click menu with dynamic items
Mobile Navigation - Collapsible menu for responsive design
Admin Dashboard - Multi-level navigation for admin panels

应用菜单栏 - 包含File、Edit、View、Tools等带子菜单的菜单
导航侧边栏 - 用于页面导航的纵向菜单
工具栏菜单 - 带图标和命令的横向菜单
上下文菜单 - 带动态项的右键菜单
移动端导航 - 用于响应式设计的可折叠菜单
后台仪表盘 - 用于后台面板的多级导航

Feature Summary

特性汇总

✅ Data Binding

Hierarchical menus (parent-child structure)
Self-referential data (id/parentId relationships)
Remote data binding via DataManager/HTTP
Custom templates for items

✅ Customization

Dynamic add/remove/insert menu items
Enable/disable items (grayed out)
Show/hide items programmatically
Custom HTML attributes and content
Icon and image support
Navigation URLs

✅ Interactivity

7 events (beforeOpen, beforeClose, onOpen, onClose, select, beforeItemRender, created)
Cancelable events for control flow
Keyboard shortcuts support
Mnemonic UI

✅ Styling & Theming

6+ built-in themes (Material3, Bootstrap5, Fluent2, etc.)
Custom CSS classes
Rounded corners support
Icon/title customization
Dark mode support

✅ Responsive & Mobile

Hamburger mode for mobile
RTL language support (15+ locales)
Horizontal and vertical layouts
Touch-friendly interactions
Hamburger animations

✅ Performance & State

State persistence to localStorage
Hover delay control
HTML sanitization for security
Efficient rendering of large menus

Next Steps:

Start with getting-started.md for installation
Choose a reference based on your task (see "Quick Access by Task" above)
Refer to api-reference.md for complete API details

✅ 数据绑定

层级菜单（父子结构）
自引用数据（id/parentId关系）
通过DataManager/HTTP绑定远程数据
自定义菜单项模板

✅ 自定义功能

动态添加/删除/插入菜单项
启用/禁用菜单项（灰显）
程序化显示/隐藏菜单项
自定义HTML属性和内容
图标和图片支持
导航URL

✅ 交互性

7个事件（beforeOpen、beforeClose、onOpen、onClose、select、beforeItemRender、created）
可取消的事件用于控制流程
键盘快捷键支持
助记符UI

✅ 样式与主题

6+内置主题（Material3、Bootstrap5、Fluent2等）
自定义CSS类
圆角支持
图标/标题自定义
深色模式支持

✅ 响应式与移动端

移动端汉堡菜单模式
RTL语言支持（15+种语言）
横向和纵向布局
触控友好的交互
汉堡菜单动画

✅ 性能与状态

状态持久化到localStorage
悬停延迟控制
HTML内容清理保障安全
高效渲染大型菜单

下一步：

从getting-started.md开始学习安装
根据你的任务选择对应参考文档（见上方“按任务快速访问”）
查看api-reference.md获取完整API详情