syncfusion-winforms-docking-manager

实现 Syncfusion WinForms Docking Manager

DockingManager 控件采用一种架构，可将面板停靠在窗体的任意位置，从而创建类似 Visual Studio 的可停靠窗口。运行时，用户可以交互式地拖动、调整大小、浮动、自动隐藏、以选项卡形式显示停靠面板，并将其排列成复杂布局。

何时使用此技能

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

• 创建类似 Visual Studio 的停靠布局，包含可停靠面板和窗口
• 实现多种停靠状态：已停靠、浮动、自动隐藏、选项卡式、MDI 或 TDI 窗口
• 构建基于文档的应用程序，使用 TDI（选项卡式文档界面）或 MDI（多文档界面）
• 向已停靠窗口添加标题栏按钮（关闭、固定、菜单、最大化）
• 使用序列化功能，在不同应用程序会话之间保存停靠布局
• 处理停靠事件，以响应激活、状态更改和用户交互
• 使用视觉样式、主题和颜色自定义外观
• 管理嵌套或链接的停靠管理器，以支持复杂布局
• 实现拖放停靠，并提供视觉反馈和提示

组件概览

DockingManager 可将任意控件转换为功能齐全的停靠窗口，支持：

• 停靠状态：已停靠（左、右、上、下）、浮动、自动隐藏、选项卡式、填充
• 文档窗口：TDI（选项卡式文档）和 MDI（多文档）
• 标题栏按钮：关闭、固定（自动隐藏）、菜单、最大化、还原和自定义按钮
• 视觉样式：Metro、Office2016（Colorful、White、DarkGray、Black）、VS2010、Office2007/2010
• 序列化：将停靠状态保存或加载到 XML、二进制文件、内存流或独立存储
• 事件：用于停靠状态更改、激活、拖动和上下文菜单的 25 个以上事件
• 高级功能：嵌套管理器、链接管理器、停靠限制、选项卡组

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和程序集部署
• 创建 DockingManager 实例
• 使用 SetEnableDocking 添加子停靠窗口
• 设置停靠标签和图标
• 基本停靠设置和配置

停靠状态和布局

📄 阅读： references/dock-states.md

• 停靠状态概览（已停靠、浮动、自动隐藏、选项卡式、填充）
• 用于以编程方式更改状态的 DockControl 函数
• 设置停靠侧（左、右、上、下、选项卡式）
• 检测和管理停靠状态
• 停靠能力限制

文档窗口（TDI/MDI）

📄 阅读： references/document-windows.md

• TDI（选项卡式文档界面）的实现
• MDI（多文档界面）的设置
• EnableDocumentMode 属性
• 使用 DockAsDocument 函数添加文档选项卡
• 窗口模式（工具窗口与文档窗口行为）
• 创建和管理文档选项卡组
• 冻结文档状态

标题栏按钮和自定义

📄 阅读： references/caption-buttons.md

• 默认标题栏按钮（关闭、固定、菜单、最大化、还原）
• 使用 Set/Get 函数显示或隐藏特定按钮
• 向 CaptionButtons 集合添加自定义标题栏按钮
• 按钮单击处理和事件
• 自定义按钮外观和颜色
• 按钮工具提示和 SuperTooltips

浮动窗口

📄 阅读： references/floating-windows.md

• 使用 FloatControl 创建浮动窗口
• 通过用户拖动操作使窗口浮动
• 启用或禁用浮动功能
• 浮动窗口属性（边框、大小、位置）
• 最大化浮动窗口
• 仅浮动窗口（禁止重新停靠）
• 在浮动状态下显示自定义按钮

自动隐藏窗口

📄 阅读： references/auto-hide-windows.md

• 自动隐藏功能概述
• SetAutoHideMode 函数
• 通过编程方式或用户固定按钮启用自动隐藏
• 使用 DockControlInAutoHideMode 更改自动隐藏侧边
• 使用 SetAutoHideOnLoad 在加载时启用自动隐藏
• 动画设置和速度
• 自定义自动隐藏标签
• 自动隐藏选择样式（MouseHover 与 Click）

标签式窗口

📄 阅读： references/tabbed-windows.md

• 使用 Tabbed 停靠样式将窗口放入同一标签组
• 在设计时和运行时创建标签组
• 标签对齐选项（Top、Bottom、Left、Right）
• 使用 AllowTabsMoving 重新排序标签
• 使用 DockAbility 禁止标签分组
• 使用 Set/GetTabPosition 管理标签位置
• 标签滚动按钮

外观和视觉样式

📄 阅读： references/appearance-customization.md

• 视觉样式（Default、Metro、Office2016、VS2010、Office2007/2010）
• Office 配色方案（Blue、Silver、Black、Managed）
• Office2007/2010 的自定义颜色
• 标题栏自定义（背景、前景、字体）
• 边框颜色和分隔条自定义
• 停靠标签外观（颜色、字体、高度）
• 文档标签样式
• 自动隐藏标签样式
• 拖动提供程序样式（VS2005、VS2008、VS2010、VS2012、Office2016）
• 从右向左支持

序列化和状态持久化

📄 阅读： references/serialization.md

• 使用 PersistState 属性自动序列化
• SaveDockState 和 LoadDockState 函数
• 序列化为 XML 文件
• 序列化为二进制文件
• 序列化到内存流以存储到数据库
• 序列化到独立存储
• 仅序列化特定控件
• 恢复到设计器初始状态

停靠事件

📄 阅读： references/docking-events.md

• DockControlActivated 和 DockControlDeactivated
• DockStateChanged 和 DockStateChanging
• AutoHideAnimationStart 和 AutoHideAnimationStop
• DragAllow、DragFeedbackStart、DragFeedbackStop
• DockContextMenu 和 AutoHideTabContextMenu
• ControlMaximizing、Maximized、Restored、Minimized
• DockVisibilityChanged 和 DockVisibilityChanging
• NewDockStateBeginLoad 和 NewDockStateEndLoad
• 使用 PreviewDockHints 限制停靠侧边
• TabGroupCreating 和 TabGroupCreated
• TransferredToManager 和 TransferringFromManager

高级功能

📄 阅读： references/advanced-features.md

• 嵌套停靠管理器（父级中的子管理器）
• 链接管理器（在管理器之间拖动）
• 停靠能力限制（SetDockAbility、SetOuterDockAbility）
• 大小限制（最小尺寸、禁止调整大小）
• 阻止关闭和停靠操作
• 自定义上下文菜单（添加/移除项目）
• 自定义分隔条宽度和颜色
• 设计时停靠功能
• 本地化支持

快速入门示例

基本停靠设置

using Syncfusion.Windows.Forms.Tools;

public partial class Form1 : Form
{
    private DockingManager dockingManager1;
    private Panel solutionExplorer;
    private Panel toolbox;
    private Panel properties;
    private Panel output;

    public Form1()
    {
        InitializeComponent();
        
        // Create DockingManager
        this.dockingManager1 = new DockingManager(this.components);
        this.dockingManager1.HostControl = this;
        
        // Create dock panels
        this.solutionExplorer = new Panel();
        this.toolbox = new Panel();
        this.properties = new Panel();
        this.output = new Panel();
        
        // Add panels to form
        this.Controls.AddRange(new Control[] { 
            solutionExplorer, toolbox, properties, output 
        });
        
        // Enable docking for all panels
        this.dockingManager1.SetEnableDocking(solutionExplorer, true);
        this.dockingManager1.SetEnableDocking(toolbox, true);
        this.dockingManager1.SetEnableDocking(properties, true);
        this.dockingManager1.SetEnableDocking(output, true);
        
        // Set dock labels
        this.dockingManager1.SetDockLabel(solutionExplorer, "Solution Explorer");
        this.dockingManager1.SetDockLabel(toolbox, "Toolbox");
        this.dockingManager1.SetDockLabel(properties, "Properties");
        this.dockingManager1.SetDockLabel(output, "Output");
        
        // Arrange dock positions
        this.dockingManager1.DockControl(solutionExplorer, this, DockingStyle.Right, 250);
        this.dockingManager1.DockControl(toolbox, this, DockingStyle.Left, 200);
        this.dockingManager1.DockControl(properties, solutionExplorer, DockingStyle.Tabbed, 200);
        this.dockingManager1.DockControl(output, this, DockingStyle.Bottom, 150);
        
        // Apply visual style
        this.dockingManager1.VisualStyle = VisualStyle.Office2016Colorful;
    }
}

常见模式

创建文档窗口（TDI）

// Enable document mode
this.dockingManager1.EnableDocumentMode = true;

// Add document tabs in NewDockStateEndLoad event
this.dockingManager1.NewDockStateEndLoad += (s, e) =>
{
    this.dockingManager1.DockAsDocument(document1);
    this.dockingManager1.DockAsDocument(document2);
};

// Set window mode (Tool allows dock/float, Document allows float only)
this.dockingManager1.SetWindowMode(document1, WindowMode.Document);

以编程方式更改停靠状态

// Dock a control to specific side
this.dockingManager1.DockControl(panel1, this, DockingStyle.Left, 200);

// Float a control at specific location
Rectangle bounds = new Rectangle(100, 100, 300, 400);
this.dockingManager1.FloatControl(panel1, bounds);

// Auto-hide a control
this.dockingManager1.SetAutoHideMode(panel1, true);

// Tab control with another
this.dockingManager1.DockControl(panel2, panel1, DockingStyle.Tabbed, 200);

自定义标题栏按钮

// Hide close button for specific control
this.dockingManager1.SetCloseButtonVisibility(panel1, false);

// Hide pin (auto-hide) button
this.dockingManager1.SetAutoHideButtonVisibility(panel1, false);

// Add custom caption button
CaptionButton customBtn = new CaptionButton();
customBtn.Name = "CustomButton";
customBtn.ImageIndex = 3; // From ImageList
customBtn.Type = CaptionButtonType.Custom;
this.dockingManager1.CaptionButtons.Add(customBtn);

// Customize button colors
this.dockingManager1.ActiveCaptionButtonForeColor = Color.Red;
this.dockingManager1.InActiveCaptionButtonForeColor = Color.Gray;

序列化（保存/加载布局）

using Syncfusion.Runtime.Serialization;

// Enable auto-save on close
this.dockingManager1.PersistState = true;

// Save to XML file manually
AppStateSerializer serializer = new AppStateSerializer(
    SerializeMode.XMLFile, "DockLayout");
this.dockingManager1.SaveDockState(serializer);
serializer.PersistNow();

// Load from XML file
AppStateSerializer serializer = new AppStateSerializer(
    SerializeMode.XMLFile, "DockLayout");
this.dockingManager1.LoadDockState(serializer);

// Save to memory stream (for database)
MemoryStream ms = new MemoryStream();
AppStateSerializer serializer = new AppStateSerializer(
    SerializeMode.BinaryFmtStream, ms);
this.dockingManager1.SaveDockState(serializer);
serializer.PersistNow();
// Store ms.ToArray() in database

处理停靠事件

// Track dock state changes
this.dockingManager1.DockStateChanged += (s, e) =>
{
    foreach (Control ctrl in e.Controls)
    {
        Console.WriteLine($"{ctrl.Name} state changed");
    }
};

// Prevent specific dock operations
this.dockingManager1.DockStateChanging += (s, e) =>
{
    if (e.NewState == DockState.Float && e.Controls[0] == panel1)
    {
        e.Cancel = true; // Prevent panel1 from floating
    }
};

// Handle control activation
this.dockingManager1.DockControlActivated += (s, e) =>
{
    Console.WriteLine($"{e.Control.Name} activated");
};

// Restrict dock sides dynamically
this.dockingManager1.PreviewDockHints += (s, e) =>
{
    if (e.DraggingTarget == panel2)
    {
        // Only allow right docking on panel2
        e.DockAbility = DockAbility.Right;
    }
};

限制停靠能力

// Restrict where control can dock (inner docking)
this.dockingManager1.SetDockAbility(panel1, DockAbility.Top | DockAbility.Bottom);

// Restrict where control can dock in client area (outer docking)
this.dockingManager1.SetOuterDockAbility(panel1, 
    DockAbility.Left | DockAbility.Right);

// Make control float-only (cannot re-dock)
this.dockingManager1.SetFloatOnly(panel1, true);

// Disable floating for specific control
this.dockingManager1.SetAllowFloating(panel1, false);

自定义外观

// Set visual style
this.dockingManager1.VisualStyle = VisualStyle.Office2016Colorful;

// Customize active caption colors
this.dockingManager1.ActiveCaptionBackground = new BrushInfo(
    GradientStyle.Horizontal, Color.DarkBlue, Color.LightBlue);
this.dockingManager1.ActiveCaptionForeGround = Color.White;

// Customize dock tab colors
this.dockingManager1.DockTabBackColor = Color.LightGray;
this.dockingManager1.ActiveDockTabBackColor = Color.White;
this.dockingManager1.DockTabForeColor = Color.Black;

// Customize document tab colors
this.dockingManager1.DocumentWindowSettings.TabBackColor = Color.SteelBlue;
this.dockingManager1.DocumentWindowSettings.ActiveTabBackColor = Color.Green;
this.dockingManager1.DocumentWindowSettings.TabHeight = 38;

// Set drag provider style
this.dockingManager1.DragProviderStyle = DragProviderStyle.VS2012;

关键属性和方法

基本属性

• HostControl：获取/设置承载停靠布局的父控件
• EnableDocumentMode：启用 TDI（标签式文档界面）模式
• PersistState：启用停靠状态的自动保存/加载
• VisualStyle：设置外观主题（Metro、Office2016、VS2010 等）
• DragProviderStyle：设置拖动提示样式（VS2005、VS2008、VS2010、VS2012）
• AutoHideEnabled：启用/禁用自动隐藏（固定）功能
• AllowTabsMoving：启用通过拖放重新排序标签
• ShowCaption：显示/隐藏所有停靠窗口的标题栏
• CaptionButtons：标题栏按钮集合（Close、Pin、Menu 等）

核心方法

添加停靠子项：

• SetEnableDocking(Control, bool)：为控件启用停靠
• SetDockLabel(Control, string)：设置标题标签文本
• SetDockIcon(Control, Icon)：设置标题图标

更改停靠状态：

• DockControl(Control, Control, DockingStyle, int)：将控件停靠到指定侧
• FloatControl(Control, Rectangle)：将控件浮动到指定位置
• SetAutoHideMode(Control, bool)：设置自动隐藏状态
• SetAsMDIChild(Control, bool)：将控件转换为 MDI 子窗口
• DockAsDocument(Control)：将控件作为 TDI 文档选项卡添加

状态管理：

• GetDockStyle(Control)：获取当前停靠样式
• IsFloating(Control)：检查控件是否处于浮动状态
• GetAutoHideMode(Control)：检查控件是否处于自动隐藏状态
• IsMDIMode(Control)：检查控件是否为 MDI 子项
• IsTabbed(Control)：检查控件是否已选项卡化

序列化：

• SaveDockState()：保存到独立存储
• SaveDockState(AppStateSerializer)：保存到文件／流
• LoadDockState()：从独立存储加载
• LoadDockState(AppStateSerializer)：从文件／流加载

标题栏按钮：

• SetCloseButtonVisibility(Control, bool)：显示／隐藏关闭按钮
• SetAutoHideButtonVisibility(Control, bool)：显示／隐藏图钉按钮
• SetMenuButtonVisibility(Control, bool)：显示／隐藏菜单按钮

限制：

• SetDockAbility(Control, DockAbility)：限制内部停靠侧
• SetOuterDockAbility(Control, DockAbility)：限制外部停靠侧
• SetFloatOnly(Control, bool)：将控件设为仅浮动
• SetAllowFloating(Control, bool)：启用／禁用浮动

常见用例

1. Visual Studio 风格的 IDE 布局

创建解决方案资源管理器、工具箱、属性和输出窗口，并支持停靠、浮动和自动隐藏。

2. 文档编辑应用程序

实现选项卡式文档界面（TDI），以便同时编辑多个文档，并在边缘放置工具窗口。

3. 仪表板布局管理器

构建可自定义的仪表板，其中包含可停靠的小组件面板，用户可以排列并保存布局。

4. 多面板数据查看器

通过灵活的停靠和选项卡布局显示多个数据网格、图表和详细信息面板。

5. 具有持久化布局的应用程序

通过序列化保存并恢复用户偏好的窗口排列，以便在不同会话间沿用。

6. MDI 应用程序现代化

将传统 MDI 应用程序转换为现代停靠界面，并支持浮动窗口和选项卡式文档。

7. 自定义开发工具

构建类似 Visual Studio 的可停靠窗口，例如代码编辑器、调试器或设计工具。