syncfusion-winforms-commandbar

实现 Windows Forms CommandBar

CommandBar 控件提供了一套完整的框架，可用于创建和承载类似 Visual Studio 和 Office 界面的工具栏、重排栏和状态栏。它支持停靠、浮动窗口、状态持久化以及承载自定义控件。

何时使用此技能

需要执行以下操作时，请使用 CommandBar：

• 创建可自定义的工具栏和状态栏
• 实现支持停靠和浮动的 Office 风格 UI
• 允许用户重新定位和排列工具栏
• 跨会话保存和恢复工具栏布局状态
• 承载下拉框、文本框和按钮等控件
• 构建复杂的多工具栏命令框架

CommandBar 概览

CommandBar 通过 CommandBarController 组件运行，由该组件管理多个 CommandBar 实例。每个工具栏都可以承载控件、停靠到窗体边缘、作为独立窗口浮动，并在状态转换期间触发事件。工具栏可以序列化，以保留用户自定义设置。

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 程序集依赖项和 NuGet 设置
• 通过设计器和代码添加 CommandBar
• 使用 HostForm 创建 CommandBarController
• 添加子控件（单个和多个）
• 代码优先初始化模式

外观自定义

📄 阅读： references/appearance-customization.md

• 自定义按钮（关闭、折叠、下拉）
• 控制光标和抓手的可见性
• 自定义背景色（停靠工具栏和 CommandBar）
• 文本显示设置和字体样式
• 配置视觉属性

交互功能

📄 阅读： references/interactive-features.md

• 浮动工具栏和浮动模式换行
• 停靠模式和停靠状态管理
• 停靠边框限制
• 事件处理（状态更改、换行、关闭）
• 完整的事件订阅示例

承载控件

📄 阅读： references/hosting-controls.md

• 集成 PopupMenu 以实现下拉功能
• 添加 XPToolBar 作为菜单项
• 设计器集成与基于代码的集成
• 复杂布局的容器模式

序列化

📄 阅读： references/serialization.md

• 持久化支持和状态管理
• AppStateSerializer 类的用法
• XML、Binary、Registry 和 IsolatedStorage 格式
• 加载和保存工作流
• 应用启动时恢复状态

快速入门示例

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

public partial class Form1 : Form
{
    private CommandBarController commandBarController1;
    private CommandBar commandBar1;

    public Form1()
    {
        InitializeComponent();
        
        // Create controller
        commandBarController1 = new CommandBarController();
        commandBarController1.HostForm = this;
        
        // Create command bar
        commandBar1 = new CommandBar();
        commandBar1.Text = "Main Toolbar";
        commandBarController1.CommandBars.Add(commandBar1);
        
        // Add child controls
        TextBox textBox1 = new TextBox();
        commandBar1.Controls.Add(textBox1);
    }
}

常见模式

Office 风格布局

• 使用顶部 CommandBar 放置主菜单项（通过 XPToolBar）
• 使用其他 CommandBar 创建格式工具栏
• 允许用户独立停靠或浮动每个工具栏
• 设置 AllowedDockBorders 以限制位置

响应式工具栏

• 启用 FloatModeWrapping，以适应空间受限的布局
• 使用折叠按钮处理溢出项
• 根据上下文动态添加控件

持久化状态

• 在 CommandBarController 上启用 PersistState
• 在 Form_Load 事件中加载状态
• 在 Form_Closing 事件中保存状态
• 使用符合存储偏好的序列化格式

关键属性

CommandBarController

• HostForm - 包含所有工具栏的窗体（必需）
• CommandBars - CommandBar 实例的集合
• PersistState - 启用/禁用状态持久化
• BackColor - 停靠工具栏区域的颜色
• Style - 视觉外观（Office、Metro 等）

CommandBar

• Text - 停靠/浮动模式下显示的名称
• DockState - 当前位置（顶部、底部、左侧、右侧）
• DisableDocking - 禁止停靠（强制浮动模式）
• DisableFloating - 禁止浮动（强制停靠模式）
• AllowedDockBorders - 将停靠限制在指定边缘
• FloatModeWrapping - 启用浮动模式下的内容换行
• HideGripper - 隐藏拖动手柄
• HideCloseButton - 在浮动模式下隐藏关闭按钮
• HideChevron - 隐藏溢出菜单按钮

常见用例

1. 类似 Visual Studio 的界面

• 多个停靠的工具栏，各自具有不同功能
• 浮动工具窗口
• 保存用户的布局偏好
• 在应用程序重启后恢复布局

2. 可自定义的仪表板

• 允许用户显示或隐藏特定的栏
• 按需重新定位各栏
• 在设置中保留布局
• 为不同模式使用不同的布局

3. 包含多个控件的单个工具栏

• 添加用于搜索的文本框
• 添加用于筛选的下拉菜单
• 添加用于执行操作的按钮
• 窗口大小调整时自动适配

4. 状态栏实现

• 将 CommandBar 停靠在底部
• 添加状态标签和进度指示器
• 禁止浮动和移动（DisableDocking = true）
• 根据应用程序状态更新内容