syncfusion-winforms-border-layout

实现 Syncfusion Windows Forms BorderLayout

BorderLayout 是一种 Windows Forms 布局管理器，可将子控件沿边缘（North、South、East、West）排列，并将剩余区域留给中心，类似于 .NET framework 内置的停靠支持。与自动布局管理器不同，BorderLayout 可让你明确控制控件的位置。

何时使用此技能

• 按边缘区域布局：需要沿边缘和中心区域排列控件时
• 顶部／底部标题栏或页脚：需要固定标题栏（North）和页脚（South），并在两者之间放置内容时
• 左侧／右侧边栏：需要在左侧或右侧放置边栏面板，并在中心放置主要内容时
• 间距控制：需要使用 HGap 和 VGap 精确控制控件间距时
• 设计器或基于代码的布局：无论是在设计器中还是通过 C#/VB.NET 以编程方式构建 UI
• 停靠的替代方案：希望采用比 Windows Forms 停靠更有结构化的方式时

组件概览

主要功能：

• 5 个位置的布局：子控件可放置于 North、South、East、West、Center
• 间距配置：自定义控件之间的水平（HGap）和垂直（VGap）间距
• 设计器支持：通过 Visual Studio 设计器添加 BorderLayout 和子控件
• 基于代码创建：使用 C# 或 VB.NET 以编程方式创建和配置 BorderLayout
• 容器控件：将任意控件（通常是 Form）设为 BorderLayout 的容器

文档导航指南

入门

📄 阅读： references/getting-started.md

• 程序集和 NuGet 包设置
• 在设计器中创建 BorderLayout
• 通过代码创建 BorderLayout（C# 和 VB.NET）
• 添加子控件
• 容器设置

控件定位

📄 阅读： references/positioning-controls.md

• 设置控件位置（North、South、East、West、Center）
• SetPosition() 方法的用法
• BorderPosition 枚举
• 在同一位置放置多个控件
• 各位置的代码示例
• 常见的位置配置

间距配置

📄 阅读： references/spacing-configuration.md

• HGap 属性（水平间距）
• VGap 属性（垂直间距）
• 在设计器中设置间距
• 在代码中设置间距（C# 和 VB.NET）
• 响应式间距模式

布局模式

📄 阅读： references/layout-patterns.md

• 常见布局（标题栏／页脚、边栏、多面板）
• 最佳实践和模式
• 响应式注意事项
• 何时使用 BorderLayout，而非其他方案
• 完整的可运行示例

快速开始

以下是最精简的 BorderLayout 配置：

using Syncfusion.Windows.Forms.Tools;

// In your form
BorderLayout borderLayout1 = new BorderLayout();
this.borderLayout1.ContainerControl = this;

// Add controls
ButtonAdv topButton = new ButtonAdv() { Text = "Header", Dock = DockStyle.Top };
ButtonAdv leftButton = new ButtonAdv() { Text = "Sidebar", Dock = DockStyle.Left };
ButtonAdv centerButton = new ButtonAdv() { Text = "Content", Dock = DockStyle.Fill };

this.Controls.Add(topButton);
this.Controls.Add(leftButton);
this.Controls.Add(centerButton);

// Set positions
borderLayout1.SetPosition(topButton, BorderPosition.North);
borderLayout1.SetPosition(leftButton, BorderPosition.West);
borderLayout1.SetPosition(centerButton, BorderPosition.Center);

// Configure spacing
borderLayout1.HGap = 10;
borderLayout1.VGap = 10;

VB.NET 等效代码：

Imports Syncfusion.Windows.Forms.Tools

' In your form
Dim borderLayout1 As BorderLayout = New BorderLayout()
Me.borderLayout1.ContainerControl = Me

' Add controls
Dim topButton As ButtonAdv = New ButtonAdv() With {.Text = "Header", .Dock = DockStyle.Top}
Dim leftButton As ButtonAdv = New ButtonAdv() With {.Text = "Sidebar", .Dock = DockStyle.Left}
Dim centerButton As ButtonAdv = New ButtonAdv() With {.Text = "Content", .Dock = DockStyle.Fill}

Me.Controls.Add(topButton)
Me.Controls.Add(leftButton)
Me.Controls.Add(centerButton)

' Set positions
borderLayout1.SetPosition(topButton, BorderPosition.North)
borderLayout1.SetPosition(leftButton, BorderPosition.West)
borderLayout1.SetPosition(centerButton, BorderPosition.Center)

' Configure spacing
borderLayout1.HGap = 10
borderLayout1.VGap = 10

常见模式

模式 1：标题栏 + 内容 + 页脚

最常见的布局，包含固定标题栏、可滚动内容区域和固定页脚。

// Create panels for header, content, footer
Panel headerPanel = new Panel() { Height = 50 };
Panel contentPanel = new Panel();
Panel footerPanel = new Panel() { Height = 40 };

// Add to form
this.Controls.Add(headerPanel);
this.Controls.Add(contentPanel);
this.Controls.Add(footerPanel);

// Position with BorderLayout
borderLayout1.SetPosition(headerPanel, BorderPosition.North);
borderLayout1.SetPosition(footerPanel, BorderPosition.South);
borderLayout1.SetPosition(contentPanel, BorderPosition.Center);

模式 2：边栏 + 内容

左侧边栏和主要内容区域。

// Create sidebar and content panels
Panel sidebarPanel = new Panel() { Width = 200 };
Panel contentPanel = new Panel();

this.Controls.Add(sidebarPanel);
this.Controls.Add(contentPanel);

// Position
borderLayout1.SetPosition(sidebarPanel, BorderPosition.West);
borderLayout1.SetPosition(contentPanel, BorderPosition.Center);

模式 3：多边缘布局

在多个边缘放置控件，并在中心区域放置内容。

Panel top = new Panel() { Height = 40 };
Panel bottom = new Panel() { Height = 40 };
Panel left = new Panel() { Width = 150 };
Panel right = new Panel() { Width = 150 };
Panel center = new Panel();

this.Controls.Add(top);
this.Controls.Add(bottom);
this.Controls.Add(left);
this.Controls.Add(right);
this.Controls.Add(center);

borderLayout1.SetPosition(top, BorderPosition.North);
borderLayout1.SetPosition(bottom, BorderPosition.South);
borderLayout1.SetPosition(left, BorderPosition.West);
borderLayout1.SetPosition(right, BorderPosition.East);
borderLayout1.SetPosition(center, BorderPosition.Center);

主要属性

属性	类型	描述
ContainerControl	Control	作为 BorderLayout 容器的控件
HGap	int	控件之间的水平间距
VGap	int	控件之间的垂直间距

主要方法

方法	参数	描述
SetPosition()	Control, BorderPosition	设置子控件的边缘位置

支持的位置（BorderPosition 枚举）

• North - 布局顶部
• South - 布局底部
• East - 布局右侧
• West - 布局左侧
• Center - 中心区域（填充剩余空间）