syncfusion-aspnetcore-context-menu

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion ContextMenu

实现Syncfusion ContextMenu

When to Use This Skill

何时使用该技能

Use the ContextMenu component when you need to:

Display context-sensitive menus triggered by right-click or long-touch on target elements
Create nested multi-level menus with hierarchical menu item structures
Add icons and visual indicators to menu items using CSS icon classes
Implement navigation links within menu items to route to different pages
Handle menu item selection with programmatic or event-driven logic
Customize menu appearance with CSS classes, templates, and animations
Support keyboard navigation for accessible menu interactions
Enable scrollable menus for large numbers of menu items exceeding viewport
Apply animations to submenu transitions with multiple effect options
Persist component state between page reloads and maintain locale customization
Support RTL (right-to-left) rendering for international applications
Render custom item templates for complex menu item layouts beyond simple text

在以下场景中使用ContextMenu组件：

显示上下文敏感菜单：通过右键点击或长按目标元素触发
创建嵌套多级菜单：构建具有层级结构的菜单项
为菜单项添加图标和视觉指示器：使用CSS图标类实现
在菜单项中添加导航链接：跳转到不同页面
处理菜单项选择：通过程序化或事件驱动逻辑实现
自定义菜单外观：使用CSS类、模板和动画
支持键盘导航：实现无障碍菜单交互
启用可滚动菜单：处理超出视口的大量菜单项
为子菜单过渡添加动画：提供多种效果选项
在页面刷新之间保留组件状态：并维护区域设置自定义
支持RTL（从右到左）渲染：适配国际化应用
渲染自定义菜单项模板：实现超出纯文本的复杂菜单项布局

Component Overview

组件概述

The Syncfusion ContextMenu is a lightweight navigation component that displays a list of commands or menu items in response to user interactions, typically a right-click on a target element. It provides:

Target-Based Triggering: Attach context menu to specific DOM elements via CSS selector
Multi-Level Nesting: Support for submenu items nested within parent menu items
Icon Support: Apply CSS icon classes (e.g., e-icons, Font Awesome) to menu items
Navigation Integration: Direct navigation via URL property on menu items
Rich Animations: Multiple transition effects (SlideDown, ZoomIn, FadeIn, None) with configurable duration
Scrollable Content: Enable vertical scrolling for menus exceeding viewport height
Template Customization: Define custom HTML templates for complex menu item layouts
Event System: Capture menu lifecycle events (beforeOpen, onOpen, select, beforeClose, onClose)
Item Rendering Hooks: Use beforeItemRender event to customize individual items per render
Selector Filtering: Filter target elements within a container using CSS selector patterns
Hover Delay: Configure delay duration before submenu appears on hover
State Persistence: Automatically restore component state on page reloads
Locale Support: Override global culture for component-specific localization
RTL Support: Automatic right-to-left rendering for RTL languages
HTML Sanitization: Optional sanitization of untrusted HTML content in menu items
Submenu Behavior: Control whether submenus open on hover or click-only

Syncfusion ContextMenu是一款轻量级导航组件，响应用户交互（通常是右键点击目标元素）显示命令或菜单项列表。它具备以下特性：

基于目标的触发：通过CSS选择器将上下文菜单附加到特定DOM元素
多级嵌套：支持在父菜单项内嵌套子菜单项
图标支持：为菜单项应用CSS图标类（如e-icons、Font Awesome）
导航集成：通过菜单项上的URL属性实现直接导航
丰富动画：多种过渡效果（SlideDown、ZoomIn、FadeIn、None），可配置时长
可滚动内容：为超出视口高度的菜单启用垂直滚动
模板自定义：为复杂菜单项布局定义自定义HTML模板
事件系统：捕获菜单生命周期事件（beforeOpen、onOpen、select、beforeClose、onClose）
菜单项渲染钩子：使用beforeItemRender事件在每次渲染时自定义单个项
选择器过滤：使用CSS选择器模式过滤容器内的目标元素
悬停延迟：配置悬停时子菜单显示前的延迟时长
状态持久化：页面刷新时自动恢复组件状态
区域设置支持：为组件特定本地化覆盖全局文化设置
RTL支持：自动为RTL语言实现从右到左渲染
HTML清理：可选清理菜单项中的不可信HTML内容
子菜单行为：控制子菜单是悬停打开还是仅点击打开

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Prerequisites and ASP.NET Core project setup
NuGet package installation (Syncfusion.EJ2.AspNet.Core)
TagHelper registration in _ViewImports.cshtml
Stylesheet and script resource references
Script Manager registration
Basic ContextMenu implementation with target element
Rendering first context menu with simple menu items
Initial data binding with items property

📄 阅读： references/getting-started.md

前提条件与ASP.NET Core项目设置
安装NuGet包（Syncfusion.EJ2.AspNet.Core）
在_ViewImports.cshtml中注册TagHelper
样式表与脚本资源引用
注册Script Manager
基础ContextMenu实现与目标元素
使用简单菜单项渲染首个上下文菜单
通过items属性进行初始数据绑定

Menu Items and Data Binding

菜单项与数据绑定

📄 Read: references/menu-items-and-data-binding.md

MenuItem structure and required properties (text, id)
Data binding patterns using List and JSON objects
Menu item properties: text, id, separator, iconCss, items, url
Creating single-level and multi-level nested menus
Separator usage for visual grouping (separator: true)
Dynamic menu item updates and modifications
Local data source patterns and data transformation

📄 阅读： references/menu-items-and-data-binding.md

MenuItem结构与必填属性（text、id）
使用List和JSON对象的数据绑定模式
菜单项属性：text、id、separator、iconCss、items、url
创建单级与多级嵌套菜单
使用分隔符进行视觉分组（separator: true）
动态更新和修改菜单项
本地数据源模式与数据转换

Icons, Navigation, and Customization

图标、导航与自定义

📄 Read: references/icons-navigation-customization.md

iconCss property for adding icons to menu items
e-icons CSS class for Syncfusion built-in icons
URL property for navigation links in menu items
Creating action vs navigation menu items
Custom CSS classes for styling menu items (cssClass property)
Hover delay configuration (hoverDelay property)
Filter selector for target element matching (filter property)

📄 阅读： references/icons-navigation-customization.md

使用iconCss属性为菜单项添加图标
用于Syncfusion内置图标的e-icons CSS类
用于菜单项导航链接的URL属性
创建操作型与导航型菜单项
使用自定义CSS类设置菜单项样式（cssClass属性）
配置悬停延迟（hoverDelay属性）
用于匹配目标元素的过滤选择器（filter属性）

Animation and Scrolling

动画与滚动

📄 Read: references/animation-scrolling.md

animationSettings configuration for submenu transitions
Animation effects: None, SlideDown, ZoomIn, FadeIn
Duration and easing properties for animation timing
enableScrolling property for handling large menu lists
Vertical scrolling behavior for overflow menu items
BeforeOpen event for dynamic menu height adjustment
Performance considerations for scrollable menus

📄 阅读： references/animation-scrolling.md

用于子菜单过渡的animationSettings配置
动画效果：None、SlideDown、ZoomIn、FadeIn
动画时长与缓动属性
用于处理大型菜单列表的enableScrolling属性
溢出菜单项的垂直滚动行为
使用BeforeOpen事件动态调整菜单高度
可滚动菜单的性能考量

Templates and Custom Rendering

模板与自定义渲染

📄 Read: references/templates-customization.md

itemTemplate property for custom menu item layouts
beforeItemRender event for individual item customization
Rendering custom HTML within menu items
Adding UI components (checkboxes, inputs) to menu items
Event arguments in beforeItemRender (name property in MenuEventArgs)
Dynamic item HTML generation based on data
CSS customization through rendered elements

📄 阅读： references/templates-customization.md

用于自定义菜单项布局的itemTemplate属性
用于单个项自定义的beforeItemRender事件
在菜单项内渲染自定义HTML
为菜单项添加UI组件（复选框、输入框）
beforeItemRender中的事件参数（MenuEventArgs中的name属性）
根据数据动态生成项HTML
通过渲染元素进行CSS自定义

Event Handling and Integration

事件处理与集成

📄 Read: references/event-handling.md

select event for menu item selection/click handling
beforeOpen event triggered before submenu opens
beforeClose event triggered before menu closes
onOpen event triggered when submenu is opened
onClose event triggered when menu closes
beforeItemRender event for render-time customization
created event indicating component initialization complete
Event-driven menu operations and conditional logic

📄 阅读： references/event-handling.md

处理菜单项选择/点击的select事件
子菜单打开前触发的beforeOpen事件
菜单关闭前触发的beforeClose事件
子菜单打开时触发的onOpen事件
菜单关闭时触发的onClose事件
渲染时自定义的beforeItemRender事件
表示组件初始化完成的created事件
基于事件的菜单操作与条件逻辑

Quick Start Example

快速入门示例

Razor Markup (Index.cshtml):

html

@page
@model IndexModel

<div id="target">Right-click me</div>

<ejs-contextmenu id="contextmenu" target="#target" items="Model.MenuItems"></ejs-contextmenu>

PageModel (Index.cshtml.cs):

csharp

public class IndexModel : PageModel
{
    public List<object> MenuItems { get; set; }
    
    public void OnGet()
    {
        MenuItems = new List<object>
        {
            new { text = "Cut", id = "cut", iconCss = "e-icons e-cut" },
            new { text = "Copy", id = "copy", iconCss = "e-icons e-copy" },
            new { text = "Paste", id = "paste", iconCss = "e-icons e-paste" },
            new { separator = true },
            new { 
                text = "Font", 
                id = "font",
                items = new List<object>
                {
                    new { text = "Bold", id = "bold" },
                    new { text = "Italic", id = "italic" }
                }
            }
        };
    }
}

Razor标记（Index.cshtml）：

html

@page
@model IndexModel

<div id="target">Right-click me</div>

<ejs-contextmenu id="contextmenu" target="#target" items="Model.MenuItems"></ejs-contextmenu>

页面模型（Index.cshtml.cs）：

csharp

public class IndexModel : PageModel
{
    public List<object> MenuItems { get; set; }
    
    public void OnGet()
    {
        MenuItems = new List<object>
        {
            new { text = "Cut", id = "cut", iconCss = "e-icons e-cut" },
            new { text = "Copy", id = "copy", iconCss = "e-icons e-copy" },
            new { text = "Paste", id = "paste", iconCss = "e-icons e-paste" },
            new { separator = true },
            new { 
                text = "Font", 
                id = "font",
                items = new List<object>
                {
                    new { text = "Bold", id = "bold" },
                    new { text = "Italic", id = "italic" }
                }
            }
        };
    }
}

Common Patterns

常见模式

Pattern	Use Case	Reference
Right-Click Menu	Context menu triggered by mouse right-click	getting-started.md
Hierarchical Items	Multi-level nested menu structure	menu-items-and-data-binding.md
Icon Support	Menu items with visual icons	icons-navigation-customization.md
Navigation Links	Menu items as navigation shortcuts	icons-navigation-customization.md
Animated Transitions	Submenu appearance effects	animation-scrolling.md
Scrollable Menus	Large menu lists with overflow	animation-scrolling.md
Custom Templates	Complex item layouts	templates-customization.md
Selection Handling	React to item selection	event-handling.md
Hover Delay	Control submenu timing	icons-navigation-customization.md
RTL Support	Right-to-left language rendering	getting-started.md

模式	使用场景	参考文档
右键菜单	通过鼠标右键点击触发的上下文菜单	getting-started.md
层级菜单项	多级嵌套菜单结构	menu-items-and-data-binding.md
图标支持	带有视觉图标的菜单项	icons-navigation-customization.md
导航链接	作为导航快捷方式的菜单项	icons-navigation-customization.md
动画过渡	子菜单显示效果	animation-scrolling.md
可滚动菜单	带有溢出内容的大型菜单列表	animation-scrolling.md
自定义模板	复杂项布局	templates-customization.md
选择处理	响应用户选择项的操作	event-handling.md
悬停延迟	控制子菜单显示时机	icons-navigation-customization.md
RTL支持	从右到左语言渲染	getting-started.md

Key Properties

关键属性

Property	Type	Purpose	Example
`target`	string	CSS selector for target element	"#menuTarget" or ".menu-area"
`items`	MenuItemModel[]	Array of menu item definitions	List of objects with text, id properties
`animationSettings`	MenuAnimationSettingsModel	Submenu open animation config	effect: "ZoomIn", duration: 500
`enableScrolling`	boolean	Enable vertical scrolling for overflow	true for large menus
`hoverDelay`	number	Delay in ms before submenu opens on hover	500
`showcItemOnClick`	boolean	Submenu opens only on click	true to disable hover opening
`itemTemplate`	string or Function	Custom HTML template for items	HTML string or callback function
`cssClass`	string	CSS class for menu wrapper styling	"custom-context-menu dark-theme"
`filter`	string	CSS selector to filter target elements	".menu-enabled"
`enableRtl`	boolean	Right-to-left rendering	true
`enablePersistence`	boolean	Preserve state on page reload	true
`locale`	string	Component locale override	"fr-FR"
`enableHtmlSanitizer`	boolean	Sanitize untrusted HTML	true (recommended for user content)

属性	类型	用途	示例
`target`	string	目标元素的CSS选择器	"#menuTarget"或".menu-area"
`items`	MenuItemModel[]	菜单项定义数组	包含text、id属性的对象列表
`animationSettings`	MenuAnimationSettingsModel	子菜单打开动画配置	effect: "ZoomIn", duration: 500
`enableScrolling`	boolean	为溢出内容启用垂直滚动	大型菜单设为true
`hoverDelay`	number	悬停时子菜单打开前的延迟（毫秒）	500
`showcItemOnClick`	boolean	子菜单仅通过点击打开	设置为true禁用悬停打开
`itemTemplate`	string或Function	菜单项的自定义HTML模板	HTML字符串或回调函数
`cssClass`	string	菜单容器的CSS类	"custom-context-menu dark-theme"
`filter`	string	过滤目标元素的CSS选择器	".menu-enabled"
`enableRtl`	boolean	从右到左渲染	true
`enablePersistence`	boolean	页面刷新时保留状态	true
`locale`	string	组件区域设置覆盖	"fr-FR"
`enableHtmlSanitizer`	boolean	清理不可信HTML	true（推荐用于用户内容）

Common Use Cases

常见使用场景

1. File Manager Context Menu Attach context menu to file list for Cut, Copy, Paste, Delete, Rename operations with icons.

2. Text Editor Toolbar Provide right-click access to formatting options (Bold, Italic, Underline) and text manipulation.

3. Data Grid Row Actions Context menu on grid rows for Edit, View, Delete, Export operations on selected rows.

4. Navigation Shortcuts Quick access menu providing links to different application sections or external resources.

5. Multi-Language Support Configure locale-specific formatting and override default culture for globalized applications.

1. 文件管理器上下文菜单 为文件列表附加上下文菜单，实现剪切、复制、粘贴、删除、重命名等带图标的操作。

2. 文本编辑器工具栏 提供右键访问格式化选项（粗体、斜体、下划线）和文本操作功能。

3. 数据表格行操作 为表格行添加上下文菜单，实现选中行的编辑、查看、删除、导出操作。

4. 导航快捷方式 提供快速访问菜单，链接到应用不同区域或外部资源。

5. 多语言支持 配置区域特定格式，覆盖默认文化设置以适配全球化应用。

Next Steps

后续步骤

Review the API Reference for complete property and method documentation
Combine ContextMenu with other navigation components (Toolbar, Sidebar) for comprehensive UI
Implement keyboard shortcuts alongside context menu for enhanced accessibility
Test RTL rendering if targeting international audiences
Consider performance implications when rendering large menu lists (>100 items)

查看API参考文档获取完整的属性和方法说明
将ContextMenu与其他导航组件（Toolbar、Sidebar）结合，构建完整UI
为上下文菜单添加键盘快捷键，增强无障碍性
如果面向国际用户，测试RTL渲染效果
渲染大型菜单列表（>100项）时考虑性能影响