syncfusion-winforms-popup-menu

在 Windows Forms 中实现 PopupMenu

本技能提供在 Windows Forms 应用程序中实现 Syncfusion PopupMenu 控件的全面指南。PopupMenu 是一种上下文菜单，会在用户交互时显示，支持多种 BarItem 类型、多级层级结构、键盘导航，以及与 Bar Manager 集成。

何时使用此技能

在以下情况下使用此技能：

• 需要在 WinForms 中实现上下文菜单或右键菜单
• 想要创建包含各种项目类型（按钮、下拉框、组合框、列表）的弹出菜单
• 需要包含嵌套子菜单的多级菜单结构
• 想要为菜单添加键盘快捷键、助记符或触控支持
• 需要使用分隔符对菜单项分组
• 想要在菜单中设置已选中／未选中状态，或禁用菜单项
• 需要在菜单项中显示图像和工具提示
• 想要将弹出菜单与 Bar Manager 或 CommandBar 集成
• 需要优先显示常用项目的部分菜单
• 正在为桌面应用程序构建上下文相关的菜单系统

组件概述

PopupMenu 是一种上下文菜单控件，默认处于隐藏状态，在触发时（通常通过右键单击）显示在任何控件上方。它支持丰富的菜单结构，包含 7 种 BarItem 类型、多级嵌套、视觉自定义，以及全面的键盘／触控交互。

主要功能：

• 7 种 BarItem 类型： BarItem、ParentBarItem、DropDownBarItem、ComboBoxBarItem、ListBarItem、StaticBarItem、TextBoxBarItem
• 多级菜单： 可无限嵌套的子菜单结构
• 分组： 在相关菜单项之间添加分隔符
• 状态： 支持已选中／未选中、启用／禁用状态
• 视觉自定义： 图像（普通、禁用、高亮）、工具提示
• 键盘支持： 快捷键、助记符、键盘导航
• 触控支持： 默认启用触控，适用于现代设备
• 部分菜单： 优先显示常用项目，隐藏其他项目
• 集成： Bar Manager、CommandBar、PopupMenusManager
• 事件： BeforePopup、Popup、Collapse、ParentBarItemChanged

核心组件：

• PopupMenu： 承载菜单结构的主控件
• ParentBarItem： 容纳所有菜单项的根容器
• PopupMenusManager： 将弹出菜单与控件关联
• BarItems： 单个菜单项（提供 7 种类型）

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集引用和依赖项
• 通过设计器添加 PopupMenu（从工具箱拖放）
• 通过代码添加 PopupMenu（初始化和设置）
• 配置 PopupMenusManager
• 将弹出菜单与控件关联（RichTextBox、Button 等）
• 添加默认 ParentBarItem
• 创建带有文本和图像的基本 BarItems
• 安装 NuGet 包

BarItem 类型和配置

📄 阅读： references/baritem-types.md

• BarItem： 包含文本、图像和事件的标准菜单项
• ParentBarItem： 子菜单项的容器（层级菜单）
• DropDownBarItem： 带有自定义 PopupControlContainer 的下拉项（ColorPicker 等）
• ComboBoxBarItem： 菜单中的可编辑组合框
• ListBarItem： 菜单中的子项列表
• StaticBarItem： 相邻项目的标签／静态文本
• TextBoxBarItem： 菜单中的文本输入框
• 每种类型的设计器和代码示例
• 每种 BarItem 类型的适用场景

多级菜单和分组

📄 阅读： references/multilevel-menus.md

• 创建嵌套菜单结构
• 添加 ParentBarItem 作为子菜单容器
• 构建分层菜单（File → New → New Project）
• 菜单层级深度不限
• 包含多级结构的复杂菜单示例

📄 阅读： references/grouping-baritems.md

• 在菜单项之间添加分隔符
• 用于分组的 SeparatorIndices 属性
• 通过 BeginGroupAt() 方法以编程方式分组
• 使用 RemoveGroupAt() 方法移除分隔符
• 使用 IsGroupBeginning() 检查分组状态
• 视觉组织模式

视觉自定义

📄 阅读： references/baritem-states.md

• 选中／未选中状态（Checked 属性）
• 通过 Click 事件切换状态
• 启用／禁用状态（Enabled 属性）
• 状态管理模式
• OverlapCheckBoxImageBounds（控制复选框与图像的重叠）
• 何时使用选中状态而非其他指示方式

📄 阅读： references/images-and-tooltips.md

• 为 BarItems 添加图像（Image 属性）
• 用于加载图像的 ImageExt 类
• 禁用状态的 DisabledImage
• 悬停／选中状态的 HighlightedImage
• 工具提示配置（Tooltip 属性）
• 使用 ShowToolTipInPopUp 启用工具提示
• 图标指南和最佳实践

键盘和交互

📄 阅读： references/keyboard-interaction.md

• 触控支持（默认启用）
• 键盘快捷键（Shortcut 属性，例如 Ctrl+F）
• 自定义快捷键文本（ShortcutText 属性）
• 键盘助记键（&Text，例如 "&File"）
• 使用 ShowMnemonicUnderlinesAlways 显示助记键下划线
• 处理菜单项选择的 Click 事件
• 通过键盘或鼠标触发操作

高级集成

📄 阅读： references/advanced-features.md

• 部分菜单（UsePartialMenus 属性）
• 使用 IsRecentlyUsedItem 优先显示常用项
• 集成 Bar Manager 以创建应用程序级菜单
• 关联 CommandBar（将 PopupMenu 作为下拉菜单）
• 设置 CommandBarController
• 事件：BeforePopup、Popup、Collapse、ParentBarItemChanged
• 事件驱动的菜单自定义

📄 阅读： references/troubleshooting.md

• 常见设置问题
• 设计器与代码之间的差异
• 程序集引用问题
• PopupMenusManager 配置问题
• BarItem 可见性问题
• 事件处理故障排除

快速入门示例

使用 BarItems 的基本 PopupMenu

using Syncfusion.Windows.Forms.Tools.XPMenus;
using System.Windows.Forms;

public partial class Form1 : Form
{
    private PopupMenu popupMenu1;
    private ParentBarItem parentBarItem1;
    private BarItem barItem1;
    private BarItem barItem2;
    private BarItem barItem3;
    private PopupMenusManager popupMenusManager1;
    private RichTextBox richTextBox1;

    public Form1()
    {
        InitializeComponent();
        
        // Initialize components
        this.popupMenu1 = new PopupMenu(this.components);
        this.parentBarItem1 = new ParentBarItem();
        this.barItem1 = new BarItem();
        this.barItem2 = new BarItem();
        this.barItem3 = new BarItem();
        this.richTextBox1 = new RichTextBox();
        this.popupMenusManager1 = new PopupMenusManager(this.components);
        
        // Configure popup menu
        this.popupMenu1.ParentBarItem = this.parentBarItem1;
        
        // Configure BarItems
        this.barItem1.Text = "Cut";
        this.barItem1.Shortcut = Shortcut.CtrlX;
        this.barItem1.Click += BarItem1_Click;
        
        this.barItem2.Text = "Copy";
        this.barItem2.Shortcut = Shortcut.CtrlC;
        this.barItem2.Click += BarItem2_Click;
        
        this.barItem3.Text = "Paste";
        this.barItem3.Shortcut = Shortcut.CtrlV;
        this.barItem3.Click += BarItem3_Click;
        
        // Add items to parent
        this.parentBarItem1.Items.AddRange(new BarItem[] { 
            this.barItem1, this.barItem2, this.barItem3 
        });
        this.parentBarItem1.SizeToFit = true;
        
        // Associate with control
        this.richTextBox1.Size = new System.Drawing.Size(300, 200);
        this.popupMenusManager1.SetXPContextMenu(this.richTextBox1, this.popupMenu1);
        
        // Add to form
        this.Controls.Add(this.richTextBox1);
    }
    
    private void BarItem1_Click(object sender, EventArgs e)
    {
        if (richTextBox1.SelectionLength > 0)
        {
            richTextBox1.Cut();
        }
    }
    
    private void BarItem2_Click(object sender, EventArgs e)
    {
        if (richTextBox1.SelectionLength > 0)
        {
            richTextBox1.Copy();
        }
    }
    
    private void BarItem3_Click(object sender, EventArgs e)
    {
        richTextBox1.Paste();
    }
}

常见模式

模式 1：多级菜单结构

// Create hierarchy: File → New → New Project, New Website
ParentBarItem fileMenu = new ParentBarItem();
fileMenu.Text = "File";

ParentBarItem newSubmenu = new ParentBarItem();
newSubmenu.Text = "New";

BarItem newProject = new BarItem();
newProject.Text = "New Project...";
newProject.Click += NewProject_Click;

BarItem newWebsite = new BarItem();
newWebsite.Text = "New Website...";
newWebsite.Click += NewWebsite_Click;

// Build hierarchy
newSubmenu.Items.AddRange(new BarItem[] { newProject, newWebsite });
fileMenu.Items.Add(newSubmenu);
parentBarItem1.Items.Add(fileMenu);

模式 2：使用分隔符分组

// Create menu items
BarItem cut = new BarItem { Text = "Cut" };
BarItem copy = new BarItem { Text = "Copy" };
BarItem paste = new BarItem { Text = "Paste" };
BarItem selectAll = new BarItem { Text = "Select All" };

// Add items
parentBarItem1.Items.AddRange(new BarItem[] { cut, copy, paste, selectAll });

// Add separator after index 2 (after Paste)
parentBarItem1.SeparatorIndices.Add(2);

// Alternative: Use method
parentBarItem1.BeginGroupAt(selectAll);

模式 3：选中状态的菜单项

BarItem wordWrap = new BarItem();
wordWrap.Text = "Word Wrap";
wordWrap.Checked = true;  // Initial state
wordWrap.Click += (s, e) => 
{
    wordWrap.Checked = !wordWrap.Checked;  // Toggle
    richTextBox1.WordWrap = wordWrap.Checked;  // Apply setting
};

模式 4：带图像的菜单项

BarItem saveItem = new BarItem();
saveItem.Text = "Save";
saveItem.Image = new ImageExt(Image.FromFile(@"icons\save.png"));
saveItem.DisabledImage = new ImageExt(Image.FromFile(@"icons\save_disabled.png"));
saveItem.HighlightedImage = new ImageExt(Image.FromFile(@"icons\save_highlight.png"));
saveItem.Shortcut = Shortcut.CtrlS;
saveItem.Tooltip = "Save the current document";
saveItem.ShowToolTipInPopUp = true;

模式 5：部分菜单（常用项）

// Enable partial menus
parentBarItem1.UsePartialMenus = true;

// Mark items as frequently used (visible by default)
cutItem.IsRecentlyUsedItem = true;
copyItem.IsRecentlyUsedItem = true;
pasteItem.IsRecentlyUsedItem = true;

// Mark items as less frequently used (hidden initially)
advancedItem.IsRecentlyUsedItem = false;
optionsItem.IsRecentlyUsedItem = false;

关键属性和事件

PopupMenu 属性

• ParentBarItem： 包含所有菜单项的根容器（必需）

ParentBarItem 属性

• Items： 菜单中的 BarItems 集合
• SizeToFit： 自动调整菜单项大小以适应内容
• SeparatorIndices： 显示分隔符的索引集合
• UsePartialMenus： 启用优先级菜单显示
• OverlapCheckBoxImageBounds： 控制复选框与图像的重叠行为

BarItem 属性

• Text： 菜单项的显示文本
• Image： 与菜单项一同显示的图标
• DisabledImage： 菜单项禁用时显示的图标
• HighlightedImage： 菜单项高亮或悬停时显示的图标
• Tooltip： 悬停时显示的工具提示文本
• ShowToolTipInPopUp： 启用工具提示显示
• Shortcut： 键盘快捷键（Ctrl+C、Alt+F 等）
• ShortcutText： 快捷键显示的自定义文本
• Checked： 在文本前显示勾选标记
• Enabled： 启用或禁用菜单项
• IsRecentlyUsedItem： 将菜单项标记为常用项（用于部分菜单）
• ShowMnemonicUnderlinesAlways： 始终显示助记键下划线
• SizeToFit： 自动调整菜单项大小以适应内容

PopupMenusManager 方法

• SetXPContextMenu(Control, PopupMenu)： 将弹出菜单关联到控件

ParentBarItem 方法

• BeginGroupAt(BarItem)： 在指定菜单项前添加分隔符
• RemoveGroupAt(BarItem)： 移除指定菜单项前的分隔符
• IsGroupBeginning(BarItem)： 检查菜单项是否为组的起始项

事件

• BeforePopup： 菜单显示前触发（获取鼠标位置、自定义菜单）
• Popup： 菜单显示后触发
• Collapse： 菜单关闭时触发
• ParentBarItemChanged： ParentBarItem 属性发生更改时触发
• Click (BarItem)： 单击菜单项时触发

常见用例

用例 1：文本编辑器上下文菜单

为 RichTextBox 创建包含剪切、复制、粘贴、全选和格式设置选项的上下文菜单。

用例 2：Grid/DataGridView 上下文菜单

为网格添加上下文菜单，其中包含添加行、删除行、编辑单元格、导出数据等选项。

用例 3：文件/文件夹上下文菜单

实现 Windows 资源管理器风格的上下文菜单，包含打开、复制、删除、属性和嵌套子菜单。

用例 4：窗体控件上下文菜单

为按钮、标签或面板添加具有控件专属操作的上下文菜单。

用例 5：应用程序级菜单系统

将 PopupMenu 与 Bar Manager 集成，在整个应用程序中提供一致的菜单体验。

用例 6：动态上下文菜单

使用 BeforePopup 事件，根据应用程序状态自定义菜单项（启用或禁用菜单项、显示或隐藏选项）。

用例 7：支持触控的菜单

利用内置触控支持，适用于平板电脑和触摸屏应用程序。

提示和最佳实践

BarItem 类型选择：

• 标准菜单命令使用 BarItem
• 子菜单使用 ParentBarItem
• 需要自定义控件（ColorPicker、自定义面板）时使用 DropDownBarItem
• 需要支持编辑的选择功能使用 ComboBoxBarItem
• 固定选项列表使用 ListBarItem
• 标签或标题使用 StaticBarItem
• 在菜单中输入文本时使用 TextBoxBarItem

性能：

• 尽可能在多个控件间重复使用 PopupMenu 实例
• 使用 BeforePopup 事件进行动态自定义，而不是重新创建菜单
• 避免为菜单项加载大尺寸图像；使用 16x16 或 24x24 图标

无障碍：

• 始终为常用命令提供键盘快捷键
• 使用助记键（&Text）进行键盘导航
• 为仅包含图标的菜单项设置描述性工具提示文本
• 确保禁用的菜单项在视觉上易于区分

设计器与代码：

• 对于静态菜单结构，使用设计器更快捷
• 对于动态菜单，使用代码可以更好地控制
• 使用设计器中的智能标记快速进行设置
• 测试设计器和代码两种方式，确保一致性

---

如需详细的实现指南，请参阅“文档和导航指南”部分中列出的参考文件。