syncfusion-winforms-ribbon

实现 Syncfusion WinForms RibbonControlAdv

何时使用此技能

在实现 Syncfusion 的 WinForms RibbonControlAdv、创建 Microsoft Office 风格的功能区界面时，请使用此技能。此组件提供全面的功能区菜单系统，包含选项卡、组、各种控件类型、Backstage 视图、快速访问工具栏以及现代化的简化布局选项。

在用户需要以下功能时使用此技能：

• 创建 Office 风格的功能区界面（Office 2007/2010/2013/2016/Touch 样式）
• 添加选项卡和组（ToolStripEx）以组织命令
• 实现 Backstage 视图或应用程序菜单
• 添加快速访问工具栏（QAT）功能
• 支持简化布局模式，便于紧凑显示
• 处理功能区状态（最大化、最小化、自动隐藏）
• 添加各种功能区控件（按钮、下拉菜单、图库、组合框）
• 在设计时或运行时自定义功能区的外观和行为
• 支持键盘导航和触控界面

组件概述

RibbonControlAdv 是一种高级导航控件，可在单个易于导航的用户界面中容纳应用程序所需的所有工具，其界面类似于 Microsoft Office。它提供：

• 多种视觉样式： Office2007、Office2010、Office2013、Office2016、TouchStyle
• 灵活布局： 普通和简化布局模式
• 丰富的控件支持： 按钮、下拉菜单、分割按钮、组合框、图库、复选框、单选按钮、文本框等
• 快速访问工具栏（QAT）： 一键访问常用命令
• BackStage 视图： Office 2016 风格的应用程序菜单
• 应用程序菜单： Office 2007 风格的菜单按钮
• 动态调整大小： 根据窗口大小智能折叠
• 自定义： 通过对话框在运行时进行自定义
• 键盘和触控支持： 完整的键盘导航和针对触控优化的界面

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装并添加 RibbonControlAdv（通过设计器和代码）
• 配置 RibbonForm，以实现正确的视觉样式
• 应用视觉样式（Office2007、Office2010、Office2013、Office2016、TouchStyle）
• 添加选项卡（ToolStripTabItem）以组织功能
• 在选项卡中创建组（ToolStripEx）
• 添加基本按钮控件
• 完整的最小可运行示例

何时阅读： 开始实现新的功能区、设置基本结构或选择视觉样式时。

---

功能区控件

📄 阅读： references/ribbon-controls.md

• ToolStripButton - 标准可单击按钮
• ToolStripRadioButton - 单选按钮
• ToolStripDropDownButton - 下拉菜单
• ToolStripSplitButton/Ex - 带下拉菜单的分割按钮
• ToolStripComboBoxEx - 下拉选择列表
• ToolStripGallery - 带滚动器的可视化项目图库
• ToolStripCheckBox - 复选框选项
• ToolStripTextBox - 文本输入字段
• ToolStripProgressBar - 进度指示器
• ToolStripLabel - 文本标签
• ToolStripSeparator - 视觉分隔符
• ToolStripPanelItem - 多行布局容器
• 每种控件类型的代码示例

何时阅读： 向功能区添加特定类型的控件、了解控件属性和事件，或实现复杂的控件布局时。

---

功能区状态和显示模式

📄 阅读： references/ribbon-states.md

• 最大化、最小化和自动隐藏状态
• DisplayOption 属性（ShowTabsAndCommands、ShowTabs、AutoHide）
• 状态更改机制（显示选项按钮、双击、最小化按钮、上下文菜单）
• DisplayOptionChanged 事件
• 键盘快捷键（Ctrl+F1）
• 最小化/最大化按钮的工具提示
• ShowRibbonDisplayOptionButton 和 ShowMinimizeButton 属性

何时阅读： 控制功能区的可见性、实现最小化/最大化功能、处理功能区状态更改，或排查最小化/最大化问题时。

---

快速访问工具栏（QAT）

📄 阅读： references/quick-access-toolbar.md

• QAT 概述和可见性控制
• 添加项目（上下文菜单、自定义窗口、AddQuickItem 方法）
• 从 QAT 中移除项目，以及限制项目添加到 QAT
• 快速访问菜单配置
• 使用 QATImageProvider 为 QAT 项目设置自定义图像
• 将后台项目添加到 QAT
• 以编程方式创建新的 QAT 项目
• QAT 事件（BeforeAddItem、BeforeRemoveItem、QuickItemAdded）

阅读时机： 实现快速访问工具栏、添加常用命令、自定义 QAT 外观、处理 QAT 事件。

---

BackStage 视图

📄 阅读： references/backstage.md

• BackStage 概述（Office 2016 风格的应用程序菜单）
• 创建和配置 BackStageView 组件
• 为内容页面添加 BackStage 选项卡
• 为操作添加 BackStage 按钮
• 使用 BackStageSeparator 进行视觉分组
• 通过 MenuButtonText 与 RibbonControlAdv 集成
• 完整代码示例

阅读时机： 实现 Office 2016 风格的后台视图、创建文件／应用程序菜单、添加后台选项卡和按钮。

---

应用程序菜单

📄 阅读： references/application-menu.md

• ApplicationMenu 概述（Office 2007 风格的菜单）
• 向菜单面板添加控件
• Mini-ToolBar 集成
• ApplicationMenu 与 BackStage 的区别
• 何时使用 ApplicationMenu 与 BackStage

阅读时机： 实现 Office 2007 风格的应用程序菜单、了解 Office2007 功能区样式下菜单按钮的功能。

---

简化布局

📄 阅读： references/simplified-layout.md

• LayoutMode 属性（Normal 与 Simplified）
• 使用 EnableSimplifiedLayoutMode 在运行时切换
• RibbonItemDisplayMode 枚举（Normal、Simplified、OverflowMenu）
• 使用 SetDisplayMode 函数控制项目可见性
• 中等尺寸图像支持（通过 SetMediumItemImage 设置 20x20 图标）
• 调整大小时溢出菜单的行为
• 通过 QAT 窗口进行运行时自定义
• 简化布局的最佳实践

阅读时机： 实现紧凑型功能区界面、支持布局切换、配置溢出菜单、优化屏幕空间使用。

---

自定义和运行时配置

📄 阅读： references/customization.md

• 上下文菜单选项和自定义
• 自定义快速访问工具栏对话框
• 用于运行时自定义的自定义功能区对话框
• 添加自定义上下文菜单项（BeforeContextMenuOpen 事件）
• 支持序列化以保存／加载状态
• 设计器支持和智能标记
• 使用 SetUseInCustomQuickAccessDialog 限制项目

阅读时机： 启用运行时自定义、添加自定义上下文菜单项、实现功能区状态的保存／加载、限制自定义选项。

---

调整大小行为和折叠选项

📄 阅读： references/resize-behavior.md

• 默认折叠行为（立即转换为下拉菜单）
• CollapseBehavior 属性（Default 与 Office2010）
• Office2010 折叠行为（Large → Small → ExtraSmall → Dropdown）
• 用于多尺寸图像的 ToolStripExImageProvider
• SetLargeItemImage 和 SetSmallItemImage 方法
• 根据窗口宽度动态调整大小
• 启动器按钮配置（ShowLauncher 属性）

阅读时机： 配置调整大小行为、实现多尺寸图标、自定义折叠模式、为组添加启动器按钮。

高级功能

📄 阅读： references/advanced-features.md

• 使用选项卡（管理 ToolStripTabItem）
• 使用上下文选项卡组处理上下文相关选项卡
• 在窗体底部集成 StatusStripEx
• 为 MDI 应用程序提供功能区合并支持
• 键盘支持和 KeyTips
• 触控支持和触控优化 UI
• 本地化支持
• 外观自定义（颜色、字体、主题）
• 用于可视化设计的功能区设计器
• ToolTip 和 SuperTooltip 配置
• 使用 EnableAeroTheme 设置经典 Windows 样式

阅读时机： 实现高级场景、上下文选项卡、MDI 集成、键盘快捷键、触控支持、本地化和主题自定义时。

---

快速入门示例

以下是一个创建带有选项卡和基本控件的功能区的最简示例：

using Syncfusion.Windows.Forms.Tools;

// 1. Make your form inherit from RibbonForm instead of Form
public partial class Form1 : RibbonForm
{
    private RibbonControlAdv ribbonControlAdv1;
    private ToolStripTabItem homeTab;
    private ToolStripEx clipboardToolStrip;
    private ToolStripButton pasteButton;
    private ToolStripButton cutButton;
    private ToolStripButton copyButton;
    
    public Form1()
    {
        InitializeComponent();
        InitializeRibbon();
    }
    
    private void InitializeRibbon()
    {
        // Create ribbon control
        ribbonControlAdv1 = new RibbonControlAdv();
        ribbonControlAdv1.RibbonStyle = RibbonStyle.Office2016;
        ribbonControlAdv1.MenuButtonText = "File";
        
        // Create Home tab
        homeTab = new ToolStripTabItem();
        homeTab.Text = "Home";
        
        // Create Clipboard group (ToolStripEx)
        clipboardToolStrip = new ToolStripEx();
        clipboardToolStrip.Text = "Clipboard";
        
        // Add buttons to group
        pasteButton = new ToolStripButton();
        pasteButton.Text = "Paste";
        pasteButton.Image = Image.FromFile("paste.png");
        
        cutButton = new ToolStripButton();
        cutButton.Text = "Cut";
        cutButton.Image = Image.FromFile("cut.png");
        
        copyButton = new ToolStripButton();
        copyButton.Text = "Copy";
        copyButton.Image = Image.FromFile("copy.png");
        
        // Build hierarchy
        clipboardToolStrip.Items.AddRange(new ToolStripItem[] { 
            pasteButton, cutButton, copyButton 
        });
        homeTab.Panel.Controls.Add(clipboardToolStrip);
        ribbonControlAdv1.Header.AddMainItem(homeTab);
        
        // Add ribbon to form
        this.Controls.Add(ribbonControlAdv1);
    }
}

常见模式

添加多个选项卡

ToolStripTabItem homeTab = new ToolStripTabItem { Text = "Home" };
ToolStripEx clipboardGroup = new ToolStripEx { Text = "Clipboard" };
homeTab.Panel.Controls.Add(clipboardGroup);
ribbonControlAdv1.Header.AddMainItem(homeTab);

快速访问工具栏

ribbonControlAdv1.Header.AddQuickItem(new QuickButtonReflectable(saveButton));

简化布局

ribbonControlAdv1.LayoutMode = RibbonLayoutMode.Simplified;
ribbonControlAdv1.EnableSimplifiedLayoutMode = true;
ribbonControlAdv1.SetDisplayMode(pasteButton, RibbonItemDisplayMode.Simplified);

状态更改

ribbonControlAdv1.DisplayOptionChanged += (sender, e) => {
    Console.WriteLine($"Ribbon changed to {e.NewValue}");
};

BackStage 设置

BackStage backStage1 = new BackStage();
backStage1.Controls.Add(new BackStageTab { Text = "Info" });
ribbonControlAdv1.BackStage = backStage1;

多尺寸图像

ribbonControlAdv1.CollapseBehavior = CollapseBehavior.Office2010;
ToolStripExImageProvider imageProvider = new ToolStripExImageProvider(clipboardToolStrip);
imageProvider.SetLargeItemImage(pasteButton, 0);
imageProvider.SetSmallItemImage(pasteButton, 0);

关键属性和方法

基本属性

• RibbonStyle - Office2007/2010/2013/2016/TouchStyle
• LayoutMode - 普通或简化布局
• DisplayOption - ShowTabsAndCommands、ShowTabs、AutoHide
• CollapseBehavior - 默认或 Office2010 折叠模式
• MenuButtonText - 文件/应用程序菜单按钮文本
• BackStage - 关联的 BackStage 视图
• EnableSimplifiedLayoutMode - 允许切换布局

关键方法

• Header.AddMainItem(tab) - 将选项卡添加到功能区
• Header.AddQuickItem(item) - 将项目添加到 QAT
• SetDisplayMode(item, mode) - 控制项目的可见性

重要事件

• DisplayOptionChanged - 功能区状态更改
• BeforeContextMenuOpen - 自定义上下文菜单
• Header.QuickItems.BeforeAddItem/BeforeRemoveItem - QAT 更改

常见用例

用例 1：Office 风格的文档编辑器

实现完整的功能区界面，包含“主页”“插入”和“视图”选项卡，以及剪贴板操作、格式设置工具和视图选项。

前往： getting-started.md → ribbon-controls.md → quick-access-toolbar.md

---

用例 2：带 BackStage 设置的应用程序

创建带有现代 BackStage 视图的应用程序，用于文件操作、选项和应用程序设置。

前往： backstage.md → customization.md

---

用例 3：紧凑型移动风格界面

1. Office 风格的文档编辑器 - 包含“主页”“插入”“视图”选项卡的完整功能区 → getting-started.md、ribbon-controls.md
2. BackStage 设置 - 用于文件操作的现代 BackStage 视图 → backstage.md
3. 紧凑界面 - 带溢出菜单的简化布局 → simplified-layout.md
4. 可自定义应用程序 - 运行时自定义功能区 → customization.md
5. 带上下文选项卡的 MDI - 根据子窗口动态调整功能区 → advanced-feature 解决方案： 使用 QATImageProvider 设置单独的 QAT 图像。标准按钮图像可能无法很好地缩放。有关 QATImageProvider 的用法，请参阅 quick-access-toolbar.md。

---

问题：调整窗口大小时控件消失

问题： 缩小窗口时，功能区控件消失。

解决方案： 这是预期的折叠行为。将 CollapseBehavior 配置为 Office2010，以实现逐步缩放；或者使用 ToolStripExImageProvider 实现多尺寸图像。请参阅 resize-behavior.md。

---

问题：简化布局项目未显示

问题： 切换到简化布局时，项目没有显示。

解决方案： 使用 SetDisplayMode 配置项目的可见性。设置 RibbonItemDisplayMode.Simplified 或 Normal | Simplified，使项目在不同布局中都可见。通过 SetMediumItemImage 添加中尺寸图像（20x20）。请参阅 simplified-layout.md。

---

问题：BackStage 未显示

问题： 菜单按钮未显示 BackStage 视图。

解决方案： 确认已设置 ribbonControlAdv1.BackStage，并配置了 MenuButtonText。BackStage 仅适用于 Office 2016 样式。对于 Office 2007，请改用 ApplicationMenu。请参阅 backstage.md 和 application-menu.md。

---

最佳实践

1. 使用 RibbonForm： 始终继承自 RibbonForm，而不是 Form，以确保正确的视觉样式和主题支持。

2. 合理组织： 在 ToolStripEx 组中对相关命令进行分组，并按照工作流在选项卡内组织这些组。

• 最小化不起作用 - 检查 DisplayOption；AutoHide 会临时显示内容，要持续显示，请使用 ShowTabsAndCommands → ribbon-states.md
• QAT 自定义图标缺失 - 使用 QATImageProvider 设置 QAT 专用图像 → quick-access-toolbar.md
• 控件在调整大小时消失 - 这是预期的折叠行为；使用 CollapseBehavior.Office2010 和多尺寸图像 → resize-behavior.md
• 简化布局项隐藏 - 使用 SetDisplayMode(item, RibbonItemDisplayMode.Simplified) 并添加 20x20 的中等尺寸图像 → simplified-layout.md
• BackStage 未显示 - 确认已设置 BackStage 属性并配置 MenuButtonText；需要 Office2016 样式（Office2007 请使用 ApplicationMenu）→ backstage.md- 使用 RibbonForm - 继承自 RibbonForm，以确保正确的样式和主题支持
• 合理组织 - 在 ToolStripEx 中对相关命令进行分组，并按照工作流组织
• 实现 QAT - 启用快速访问工具栏，以便使用常用命令
• 多尺寸图像 - 为所有状态提供 32x32、16x16、20x20 的图像
• 处理状态更改 - 使用 DisplayOptionChanged 事件保存用户偏好设置
• 运行时自定义 - 启用自定义对话框，方便用户进行个性化设置
• 键盘和触控 - 利用内置的 KeyTips 和触控支持
• 上下文选项卡 - 显示特定上下文的选项卡（例如，选中图像时显示“图片工具”）
• 测试调整大小 - 验证控件在不同窗口尺寸下都能平滑折叠