syncfusion-javascript-context-menu

实现 ContextMenu

ContextMenu 是一种图形用户界面组件，会在用户右键单击或触摸并按住时显示。它支持嵌套菜单项、自定义模板、动态内容、动画和全面的事件处理，非常适合在 Web 应用中构建上下文操作。

主要功能

• 嵌套／多级菜单 - 创建分层菜单结构
• 动态管理菜单项 - 在运行时添加、移除、启用或禁用菜单项
• 丰富的样式和模板 - 自定义 CSS、图标和 HTML 模板
• 事件处理 - 完整的生命周期事件（beforeOpen、onOpen、onClose、select 等）
• 动画 - 支持多种效果的可配置打开／关闭动画
• 数据绑定 - 从数据源填充菜单
• 滚动 - 为大型菜单自动启用滚动，支持 HScroll/VScroll
• 无障碍支持 - 符合 WCAG 标准，支持键盘导航和 ARIA
• RTL 支持 - 为国际化应用提供从右到左的布局

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装依赖项并配置开发环境
• 将 ContextMenu 添加到项目中
• 使用 HTML 和 TypeScript 初始化基本组件
• 创建包含分隔符的首个可运行示例
• 运行和测试应用

菜单结构和模板

📄 阅读： references/menu-structure.md

• 创建基于模板的菜单结构
• 构建多级和嵌套菜单
• 定义分隔符和菜单项分组
• 配置用于数据映射的 FieldSettings
• 自定义菜单项结构模式

菜单项管理

📄 阅读： references/menu-items.md

• 动态添加或移除菜单项
• 以编程方式启用和禁用菜单项
• 使用 insertBefore() 和 insertAfter() 方法
• 管理菜单项状态和可见性
• 批量操作菜单项

交互和事件

📄 阅读： references/interactions.md

• 以编程方式打开和关闭 ContextMenu
• 处理生命周期事件（beforeOpen、onOpen、onClose、beforeClose）
• 响应菜单项选择（select 事件）
• 集成由菜单点击触发的对话框
• 配置动画效果和时长
• 管理菜单定位和悬停延迟

样式和外观

📄 阅读： references/styling.md

• 应用 CSS 样式和自定义主题
• 使用 iconCss 为菜单项添加图标
• 使用 href 实现 URL 导航
• 启用从右到左（RTL）布局
• 应用自定义 CSS 类
• 使用下划线字符设置文本格式

数据绑定

📄 阅读： references/data-binding.md

• 从数据源填充菜单
• 绑定到 JSON 数组和集合
• 从服务端动态更新菜单项
• 使用 FieldSettings 映射数据字段
• 实时更新菜单内容

高级功能

📄 阅读： references/advanced-features.md

• 使用 HScroll/VScroll 实现可滚动菜单
• 配置 MenuOpenType（Auto、Hover、Click）
• 应用元素筛选器，有选择地触发菜单
• 启用／禁用 HTML 清理以增强安全性
• 配置持久化和区域设置
• 无障碍功能和 ARIA 属性

API 参考

📄 阅读： references/api-reference.md

• 完整的属性文档（约 40 个核心属性）
• MenuItem 结构和配置
• 可用方法（open、close、enableItems、removeItems、hideItems 等）
• 事件接口和事件数据结构
• 动画效果和菜单打开类型
• 类型定义和枚举

快速入门示例

HTML：

<div>
  <div id="contextmenutarget" style="border: 1px solid #ccc; padding: 20px; width: 300px; height: 200px;">
    Right-click here to open the context menu
  </div>
  <ul id="contextmenu"></ul>
</div>

TypeScript：

import { ContextMenu } from '@syncfusion/ej2-navigations';

// Define menu items
const menuItems = [
  { text: 'Cut' },
  { text: 'Copy' },
  { text: 'Paste' },
  { separator: true },
  { text: 'Link' },
  { text: 'Share' }
];

// Initialize ContextMenu
const contextMenu = new ContextMenu({
  items: menuItems,
  target: '#contextmenutarget'
});

contextMenu.appendTo('#contextmenu');

常见模式

模式 1：嵌套菜单结构

const menuItems = [
  { 
    text: 'Edit',
    items: [
      { text: 'Cut' },
      { text: 'Copy' },
      { text: 'Paste' }
    ]
  },
  { 
    text: 'View',
    items: [
      { text: 'Zoom In' },
      { text: 'Zoom Out' }
    ]
  }
];

const contextMenu = new ContextMenu({
  items: menuItems,
  target: '#target'
});

模式 2：处理菜单项选择

const contextMenu = new ContextMenu({
  items: menuItems,
  target: '#target',
  select: (args) => {
    console.log('Selected: ' + args.item.text);
    // Perform action based on selected item
  }
});

模式 3：动态添加菜单项

// Add new items after initialization
const newItems = [{ text: 'New Option' }];
contextMenu.insertAfter(newItems, 'Edit');

模式 4：动画配置

const contextMenu = new ContextMenu({
  items: menuItems,
  target: '#target',
  animationSettings: {
    duration: 400,
    easing: 'ease',
    effect: 'SlideDown'  // SlideDown, ZoomIn, FadeIn, etc.
  }
});

模式 5：图标和导航

const menuItems = [
  { 
    text: 'Edit',
    iconCss: 'e-icons e-edit'
  },
  { 
    text: 'Delete',
    iconCss: 'e-icons e-delete'
  },
  { 
    text: 'External Link',
    url: 'url'
  }
];

主要属性

属性	类型	用途
items	MenuItemModel[]	菜单项配置
target	string	触发元素的 CSS 选择器
animationSettings	MenuAnimationSettingsModel	动画行为
cssClass	string	自定义 CSS 类
enableScrolling	boolean	为较长的菜单启用滚动条
enableRtl	boolean	支持从右到左的布局
showItemOnClick	boolean	点击时打开子菜单（而非悬停时）
hoverDelay	number	子菜单出现前的延迟时间（毫秒）
filter	string	用于筛选目标元素的 CSS 选择器
itemTemplate	string/Function	菜单项的自定义模板

常见用例

1. 文件操作 - 对文件/文件夹执行剪切、复制、粘贴和删除操作
2. 编辑器菜单 - 文本编辑器中的格式选项
3. 网格行操作 - 对表格/网格行执行操作
4. 应用程序菜单 - 通用应用程序上下文菜单
5. 嵌套操作 - 多级操作（编辑 → 格式）
6. 动态内容 - 从服务端加载菜单项
7. 自定义样式 - 与应用设计风格一致的主题化上下文菜单
8. 无障碍功能 - 键盘导航和屏幕阅读器支持