syncfusion-aspnetcore-context-menu

实现 Syncfusion ContextMenu

何时使用此技能

在需要以下功能时使用 ContextMenu 组件：

• 显示上下文相关菜单：在目标元素上通过右键单击或长按触发
• 创建多层嵌套菜单：使用分层的菜单项结构
• 为菜单项添加图标和视觉指示：使用 CSS 图标类
• 在菜单项中实现导航链接：跳转到不同页面
• 处理菜单项选择：使用程序化逻辑或事件驱动逻辑
• 自定义菜单外观：使用 CSS 类、模板和动画
• 支持键盘导航：实现无障碍菜单交互
• 启用可滚动菜单：当菜单项过多、超出视口时使用
• 应用动画：为子菜单过渡效果设置多种动画选项
• 保持组件状态：在页面重新加载后保留状态，并维持区域设置自定义项
• 支持 RTL（从右到左）渲染：用于国际化应用
• 渲染自定义项模板：构建超出简单文本范围的复杂菜单项布局

组件概述

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 内容
• 子菜单行为：控制子菜单是悬停时打开还是仅在单击时打开

文档与导航指南

入门

📄 阅读： references/getting-started.md

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

菜单项与数据绑定

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

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

图标、导航和自定义

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

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

动画和滚动

📄 阅读： references/animation-scrolling.md

• 配置 animationSettings 以设置子菜单过渡效果
• 动画效果：None、SlideDown、ZoomIn、FadeIn
• 设置动画时长和缓动属性
• 使用 enableScrolling 属性处理较长的菜单列表
• 菜单项溢出时的垂直滚动行为
• 使用 BeforeOpen 事件动态调整菜单高度
• 可滚动菜单的性能注意事项

模板和自定义渲染

📄 阅读： references/templates-customization.md

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

事件处理和集成

📄 阅读： references/event-handling.md

• 使用 select 事件处理菜单项选择或点击
• 打开子菜单前触发 beforeOpen 事件
• 关闭菜单前触发 beforeClose 事件
• 打开子菜单时触发 onOpen 事件
• 关闭菜单时触发 onClose 事件
• 使用 beforeItemRender 事件在渲染时进行自定义
• 使用 created 事件指示组件已完成初始化
• 事件驱动的菜单操作和条件逻辑

---

快速入门示例

Razor 标记（Index.cshtml）：

@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）：

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" }
                }
            }
        };
    }
}

---

常见模式

模式	用例	参考
右键菜单	由鼠标右键触发的上下文菜单	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

---

关键属性

属性	类型	用途	示例
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 or 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（用户内容建议启用）

---

常见用例

1. 文件管理器上下文菜单 为文件列表添加上下文菜单，以便执行剪切、复制、粘贴、删除和重命名操作，并显示图标。

2. 文本编辑器工具栏 通过右键菜单提供格式选项（粗体、斜体、下划线）和文本处理功能。

3. 数据网格行操作 在网格行上显示上下文菜单，以便对选中的行执行编辑、查看、删除和导出操作。

4. 导航快捷方式 提供快捷访问菜单，其中包含指向应用程序不同分区或外部资源的链接。

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

---

后续步骤

• 查看API 参考，了解完整的属性和方法文档
• 将 ContextMenu 与其他导航组件（Toolbar、Sidebar）结合使用，构建全面的 UI
• 除上下文菜单外，还应实现键盘快捷键，以增强可访问性
• 如果面向国际用户，请测试 RTL 渲染
• 渲染大量菜单列表（>100 项）时，请考虑其对性能的影响