syncfusion-winforms-commandbar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Windows Forms CommandBar

实现Windows Forms CommandBar

The CommandBar control provides a complete framework for creating and hosting toolbars, rebars, and status bars similar to Visual Studio and Office interfaces. It supports docking, floating windows, state persistence, and hosting custom controls.

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

When to use this skill

什么时候使用这个技能

Use CommandBar when you need to:

Create customizable toolbars and status bars
Implement Office-like UI with docking/floating capabilities
Allow users to reposition and rearrange bars
Save and restore bar layout state across sessions
Host controls like dropdowns, textboxes, and buttons
Build complex multi-bar command frameworks

当你需要实现以下需求时可以使用CommandBar：

创建可自定义的工具栏和状态栏
实现具备停靠/浮动能力的类Office UI
允许用户重新定位和排列工具栏
在不同会话间保存和恢复工具栏布局状态
承载下拉框、文本框、按钮等控件
构建复杂的多工具栏命令框架

CommandBar overview

CommandBar概述

CommandBar operates through the CommandBarController component which manages multiple CommandBar instances. Each bar can host controls, dock to form sides, float as separate windows, and fire events during state transitions. Bars can be serialized to preserve user customization.

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

Documentation and navigation guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly dependencies and NuGet setup
Adding CommandBar via designer and code
Creating CommandBarController with HostForm
Adding child controls (single and multiple)
Code-first initialization patterns

📄 阅读: references/getting-started.md

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

Appearance Customization

外观自定义

📄 Read: references/appearance-customization.md

Customizing buttons (close, chevron, dropdown)
Cursor and gripper visibility control
Background color customization (docked bar and CommandBar)
Text display settings and font styling
Visual property configuration

📄 阅读: references/appearance-customization.md

自定义按钮（关闭、展开、下拉）
光标与拖动手柄可见性控制
背景色自定义（停靠栏与CommandBar）
文本显示设置与字体样式
视觉属性配置

Interactive Features

交互功能

📄 Read: references/interactive-features.md

Floating bars and float mode wrapping
Docking modes and dock state management
Dock border restrictions
Event handling (state changed, wrapping, closing)
Complete event subscription examples

📄 阅读: references/interactive-features.md

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

Hosting Controls

承载控件

📄 Read: references/hosting-controls.md

Integrating PopupMenu for dropdown functionality
Adding XPToolBar for menu items
Designer vs code-based integration
Container patterns for complex layouts

📄 阅读: references/hosting-controls.md

集成PopupMenu实现下拉功能
添加XPToolBar用于菜单项展示
设计器集成与基于代码的集成对比
适用于复杂布局的容器模式

Serialization

序列化

📄 Read: references/serialization.md

Persistence support and state management
AppStateSerializer class usage
XML, Binary, Registry, and IsolatedStorage formats
Load and save workflows
State restoration on application launch

📄 阅读: references/serialization.md

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

Quick start example

快速入门示例

csharp

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);
    }
}

csharp

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);
    }
}

Common patterns

常见模式

Office-like layout

类Office布局

Use Top CommandBar for main menu items (via XPToolBar)
Use additional CommandBars for formatting toolbars
Enable user to dock/float each bar independently
Set AllowedDockBorders to restrict positioning

使用顶部CommandBar承载主菜单项（通过XPToolBar）
使用额外的CommandBar作为格式工具栏
允许用户独立停靠/浮动每个工具栏
设置AllowedDockBorders限制可停靠位置

Responsive toolbars

响应式工具栏

Enable FloatModeWrapping for space-constrained layouts
Use chevron to handle overflow items
Implement dynamic control addition based on context

为空间受限的布局启用FloatModeWrapping
使用展开按钮处理溢出项
根据上下文动态添加控件

Persistent state

持久化状态

Enable PersistState on CommandBarController
Load state in Form_Load event
Save state in Form_Closing event
Use serialization format matching your storage preference

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

Key properties

核心属性

CommandBarController

```
HostForm
```
- The form containing all command bars (required)
```
CommandBars
```
- Collection of CommandBar instances
```
PersistState
```
- Enable/disable state persistence
```
BackColor
```
- Color of docked bar area
```
Style
```
- Visual appearance (Office, Metro, etc.)

CommandBar

```
Text
```
- Display name in dock/float mode
```
DockState
```
- Current position (Top, Bottom, Left, Right)
```
DisableDocking
```
- Prevent docking (force float mode)
```
DisableFloating
```
- Prevent floating (force docked mode)
```
AllowedDockBorders
```
- Restrict docking to specific sides
```
FloatModeWrapping
```
- Enable content wrapping in float mode
```
HideGripper
```
- Hide drag handle
```
HideCloseButton
```
- Hide close button in float mode
```
HideChevron
```
- Hide overflow menu button

CommandBarController

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

CommandBar

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

Common use cases

常见用例

1. Visual Studio-like interface

Multiple docked toolbars with different functions
Floating tool windows
Save user layout preferences
Restore on application restart

2. Customizable dashboard

Allow users to show/hide specific bars
Reposition bars as needed
Preserve layout in settings
Different layouts for different modes

3. Single toolbar with multiple controls

Host textbox for search
Host dropdown for filtering
Host buttons for actions
Responsive to window resizing

4. Status bar implementation

Dock CommandBar to bottom
Add status labels and progress indicators
Disable floating/moving (DisableDocking = true)
Update content based on application state

1. 类Visual Studio界面

具备不同功能的多个停靠工具栏
浮动工具窗口
保存用户布局偏好
应用重启时自动恢复

2. 可自定义仪表盘

允许用户显示/隐藏特定工具栏
根据需要重新定位工具栏
在设置中保存布局
适配不同模式的不同布局

3. 承载多个控件的单工具栏

承载搜索用的文本框
承载筛选用的下拉框
承载操作按钮
适配窗口大小变化

4. 状态栏实现

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