syncfusion-winforms-main-frame-bar-manager

实现 Syncfusion WinForms MainFrameBarManager

何时使用此技能

在以下情况下，MainFrameBarManager 组件必不可少：

• 创建分层菜单结构（“文件”“编辑”“视图”菜单及子菜单）
• 构建可自定义的工具栏和命令栏
• 为菜单项添加键盘快捷键和助记键
• 实现上下文菜单和交互式工具提示
• 支持带有合并菜单的 MDI（多文档界面）应用程序
• 在不同应用程序会话之间保留菜单和工具栏状态
• 允许最终用户在运行时自定义菜单布局

此组件遵循 XP 菜单框架模式，为 Windows Forms 应用程序提供专业的企业级菜单管理系统。

快速入门示例

// Create MainFrameBarManager
MainFrameBarManager mainFrameBarManager1 = new MainFrameBarManager();
mainFrameBarManager1.Style = Syncfusion.Windows.Forms.VisualStyle.Office2016Colorful;
mainFrameBarManager1.Form = this;

// Create a bar (menu container)
Bar fileBar = new Syncfusion.Windows.Forms.Tools.XPMenus.Bar();
fileBar.BarName = "File";
fileBar.Caption = "File";
fileBar.Manager = mainFrameBarManager1;

// Create parent menu item
ParentBarItem fileMenu = new ParentBarItem();
fileMenu.Text = "&File";

// Create sub-menu items
BarItem newItem = new BarItem() { Text = "&New" };
BarItem openItem = new BarItem() { Text = "&Open" };
BarItem exitItem = new BarItem() { Text = "E&xit" };

// Assign shortcuts and mnemonics
newItem.Shortcut = Shortcut.CtrlN;
openItem.Shortcut = Shortcut.CtrlO;
exitItem.Shortcut = Shortcut.AltF4;

// Build hierarchy
fileMenu.Items.AddRange(new BarItem[] { newItem, openItem, exitItem });
fileBar.Items.Add(fileMenu);

// Add to manager
mainFrameBarManager1.Items.AddRange(new BarItem[] { fileMenu, newItem, openItem, exitItem });
mainFrameBarManager1.Bars.Add(fileBar);
mainFrameBarManager1.Categories.Add("Menu");

常见模式

模式 1：创建多级菜单

为子菜单创建嵌套的 ParentBarItem（文件 → 最近 → Document1）。将相关项归入父容器。

模式 2：添加交互控件

使用带有 PopupControlContainer 的 DropDownBarItem 创建颜色选择器，使用 ComboBoxBarItem 创建选项列表，使用 TextBoxBarItem 创建输入字段。

模式 3：实现自定义

启用 AutoPersistCustomization，允许用户重新排列菜单项并自动保存偏好设置。

模式 4：集成 MDI 应用程序

父窗体使用 MainFrameBarManager，子窗体使用 ChildFrameBarManager。调用 RegisterMdiChildTypes() 自动合并菜单。

模式 5：键盘导航

设置 Shortcut 属性，并在 Text 中使用 & 符号作为助记键（例如，“&Save”会创建 Alt+S 快捷键）。

关键属性

属性	类型	用途
Form	Form	将菜单管理器与父窗体关联
Style	VisualStyle	设置视觉样式（Office2016、XPBlue 等）
Bars	BarCollection	Bar 实例集合（菜单、工具栏）
Items	BarItemCollection	此管理器管理的所有 BarItem 实例
Categories	StringCollection	用于在自定义 UI 中整理菜单项的类别
AutoLoadToolBarPositions	bool	启动时自动加载已保存的工具栏位置
AutoPersistCustomization	bool	自动保存菜单和工具栏自定义设置
DetachedCommandBars	CommandBarCollection	可分离的 CommandBar 实例集合

文档与导航指南

开始使用

📄 阅读： references/getting-started.md

• NuGet 包设置和程序集引用
• 创建 MainFrameBarManager 实例
• 设置视觉样式并关联窗体
• 配置许可证密钥

构建菜单

📄 阅读： references/menu-items-via-code.md

• 通过编程方式创建 Bar 实例
• 添加 BarItem 和 ParentBarItem
• 子项层次结构和子菜单
• 事件处理程序设置及代码示例

📄 阅读： references/menu-items-via-designer.md

• 基于设计器创建菜单（拖放）
• 用于设置栏和项的自定义对话框
• 通过 UI 进行视觉布局
• 自动注入程序集引用

菜单项类型与功能

📄 阅读： references/menu-item-types.md

• BarItem（基本可点击项）
• ParentBarItem（子菜单容器）
• DropDownBarItem（自定义弹出控件）
• ComboBoxBarItem（下拉选项）
• StaticBarItem（类似标签的显示项）
• TextBoxBarItem（文本输入字段）
• ToolBarListBarItem（工具栏自定义选项）

交互功能

📄 阅读： references/interactive-features.md

• SuperTooltip 设置和外观自定义
• 上下文菜单集成
• 工具提示可见性控制
• 高级工具提示编辑器配置

键盘与无障碍功能

📄 阅读： references/keyboard-support.md

• 为菜单项分配键盘快捷键
• 使用 & 符号实现助记符文本
• ShowMnemonicUnderlinesAlways 属性
• 键盘导航模式

状态持久化与 MDI

📄 阅读： references/state-persistence-mdi.md

• 使用 AutoLoadToolBarPositions 启用状态持久化
• 自动序列化自定义设置
• MDI 父窗体/子窗体集成
• ChildFrameBarManager 和菜单合并
• 使用 RegisterMdiChildTypes() 显式合并
• MDI 合并行为矩阵

可分离工具栏

📄 阅读： references/detachable-command-bars.md

• 创建和停靠 CommandBar
• 配置 DockState 属性
• 添加到 DetachedCommandBars 集合
• 设计器与基于代码的实现方式

常见用例

文件菜单： 使用 ParentBarItem 层级创建标准文件菜单，包含“新建”“打开”“保存”“最近文档”和“退出”项。

工具栏： 使用多个具有不同 BarNames 的 Bar 实例创建独立工具栏，并将它们分别停靠在不同位置。

搜索栏： 将 TextBoxBarItem 或 ComboBoxBarItem 添加到工具栏，以实现搜索/筛选功能。

菜单中的颜色选取器： 使用包含 ColorPickerUIAdv 控件的 PopupControlContainer 创建 DropDownBarItem。

本地化菜单： 将 Text 属性设为本地化字符串；助记符和快捷键可在所有语言中使用。

自定义快捷键： 对不需要快捷键的项分配 Shortcut.None，或通过 Shortcut 枚举使用自定义组合键。

快速链接

• Syncfusion WinForms 菜单 API 参考
• BarItem API 参考
• Bar 组件参考