syncfusion-winforms-layout-managers
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion WinForms LayoutManagers
实现Syncfusion WinForms LayoutManagers
The LayoutManagers Package provides five specialized layout managers that automatically arrange child controls within container controls (Panel, Form, etc.) based on specific layout strategies. These managers eliminate manual positioning and provide professional, maintainable layouts.
LayoutManagers 包提供了5种专用布局管理器,可根据特定的布局策略自动排列容器控件(Panel、Form等)内的子控件。这些管理器免去了手动定位的麻烦,可帮你构建专业、易维护的布局。
When to Use This Skill
何时使用本指南
Use this skill when the user needs to:
- Automatic Layout Management: Let layout managers position controls instead of manual placement
- BorderLayout (5-Region Docking): Dock controls to North, South, East, West, or Center positions
- CardLayout (Wizard/Property Pages): Show one control at a time in a stack (wizards, tabbed content)
- FlowLayout (Flow Arrangement): Arrange controls horizontally or vertically with automatic wrapping
- GridLayout (Uniform Grid): Position controls in a uniform grid with equal-sized cells
- GridBagLayout (Flexible Grid): Create complex layouts with variable cell sizes and control spanning
- Container-Based Layouts: Apply layouts to Panel, Form, or any ContainerControl
- Constraint-Based Positioning: Define layout rules instead of absolute coordinates
- Responsive Layouts: Layouts that adapt when container resizes
- Professional Forms: Create consistent, maintainable form layouts
当用户需要实现以下需求时可使用本指南:
- 自动布局管理: 交由布局管理器定位控件,无需手动摆放
- BorderLayout(5区域停靠): 将控件停靠到北、南、东、西、中五个位置
- CardLayout(向导/属性页): 以堆叠形式一次展示一个控件(适用于向导、标签式内容)
- FlowLayout(流式排列): 水平或垂直排列控件,支持自动换行
- GridLayout(均匀网格): 将控件摆放在单元格大小统一的网格中
- GridBagLayout(灵活网格): 支持可变单元格大小和控件跨列/行的复杂布局
- 容器级布局: 为Panel、Form或任意ContainerControl应用布局规则
- 基于约束的定位: 定义布局规则而非使用绝对坐标
- 响应式布局: 容器大小变化时布局可自动适配
- 专业表单开发: 创建统一、易维护的表单布局
Component Overview
组件概览
The LayoutManagers Package () provides five layout managers:
Syncfusion.Windows.Forms.ToolsLayoutManagers 包()提供5种布局管理器:
Syncfusion.Windows.Forms.Tools1. BorderLayout
1. BorderLayout
Purpose: Dock controls along borders and center (like .NET docking)
Key Features:
- 5 regions: North, South, East, West, Center
- Position-based constraints
- Spacing control (HGap, VGap)
- Size customization per position
When to use: MDI-style interfaces, dock panels, application shells with header/footer/sidebar
用途: 沿容器边框和中心区域停靠控件(类似.NET原生停靠功能)
核心特性:
- 5个区域:北、南、东、西、中心
- 基于位置的约束规则
- 间距控制(HGap、VGap)
- 支持按位置自定义尺寸
适用场景: MDI风格界面、停靠面板、带头部/底部/侧边栏的应用外壳
2. CardLayout
2. CardLayout
Purpose: Show one child control at a time from a stack
Key Features:
- Stack of cards (only one visible)
- Navigation (First, Last, Next, Previous)
- Card naming/identification
- Layout modes (Default, Fill)
- Image support per card
When to use: Wizards, property pages, tabbed content without tabs, step-by-step forms
用途: 从堆叠控件中一次展示一个子控件
核心特性:
- 卡片堆叠(仅一张可见)
- 导航功能(第一张、最后一张、下一张、上一张)
- 卡片命名/标识功能
- 布局模式(默认、填充)
- 支持为每张卡片配置图片
适用场景: 向导、属性页、无标签的标签式内容、分步表单
3. FlowLayout
3. FlowLayout
Purpose: Arrange controls in horizontal or vertical flow (MOST COMMONLY USED)
Key Features:
- Horizontal or vertical layout modes
- Automatic wrapping
- Alignment options (Near, Far, Center, ChildConstraints)
- Per-child constraints (MinSize, PreferredSize)
- Flow direction (normal, reverse)
- AutoHeight feature
When to use: Toolbars, button panels, tag lists, responsive content, most general-purpose layouts
用途: 水平或垂直流式排列控件(最常用)
核心特性:
- 水平/垂直布局模式
- 自动换行
- 对齐选项(近侧、远侧、居中、子控件约束)
- 子控件级约束(最小尺寸、首选尺寸)
- 流动方向(正向、反向)
- 自动高度特性
适用场景: 工具栏、按钮面板、标签列表、响应式内容、绝大多数通用布局
4. GridLayout
4. GridLayout
Purpose: Position controls in a uniform grid
Key Features:
- Rows and columns configuration
- Equal-sized cells
- Automatic child placement
- Spacing control (HGap, VGap)
When to use: Calculator layouts, button grids, uniform icon panels, simple tabular layouts
用途: 将控件摆放在均匀网格中
核心特性:
- 可配置行列数
- 单元格大小统一
- 子控件自动摆放
- 间距控制(HGap、VGap)
适用场景: 计算器布局、按钮网格、统一大小的图标面板、简单表格布局
5. GridBagLayout
5. GridBagLayout
Purpose: Create complex layouts with flexible grid
Key Features:
- Variable row/column sizes
- Cell spanning (row and column)
- Anchor positions (9 options)
- Fill modes (None, Horizontal, Vertical, Both)
- Weight-based resizing (WeightX, WeightY)
- Per-cell padding (Insets)
When to use: Complex forms, dialog boxes, layouts with variable cell sizes, advanced positioning requirements
Key Namespace:
Syncfusion.Windows.Forms.ToolsAssembly:
Syncfusion.Shared.Base.dll用途: 基于灵活网格创建复杂布局
核心特性:
- 可变行列尺寸
- 单元格跨列/跨行
- 锚点位置(9种选项)
- 填充模式(无、水平、垂直、双向)
- 基于权重的缩放(WeightX、WeightY)
- 单元格内边距(Insets)
适用场景: 复杂表单、对话框、可变单元格大小的布局、高级定位需求
核心命名空间:
Syncfusion.Windows.Forms.Tools程序集:
Syncfusion.Shared.Base.dllDocumentation and Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
When to read: User needs to install, understand container concepts, or set up their first layout manager.
Topics covered:
- Assembly deployment and NuGet packages
- Container control concept (Panel, Form, ContainerControl)
- Child control management
- Adding layout managers via designer
- Adding layout managers via code
- Basic setup for all layout types
- Common settings (spacing, gaps)
- Layout events
📄 阅读: references/getting-started.md
适用场景: 用户需要安装组件、理解容器概念或搭建第一个布局管理器时
涵盖主题:
- 程序集部署与NuGet包
- 容器控件概念(Panel、Form、ContainerControl)
- 子控件管理
- 通过设计器添加布局管理器
- 通过代码添加布局管理器
- 所有布局类型的基础配置
- 通用设置(间距、间隙)
- 布局事件
BorderLayout (5-Region Docking)
BorderLayout(5区域停靠)
📄 Read: references/border-layout.md
When to read: User wants to dock controls to borders (North, South, East, West, Center).
Topics covered:
- BorderLayout overview and position constraints
- Adding controls to each position
- Designer vs code approaches
- SetConstraints method
- Spacing configuration (HGap, VGap)
- Size customization per position
- MDI-style layout example
- Dock panel example
- Best practices for border layouts
📄 阅读: references/border-layout.md
适用场景: 用户需要将控件停靠到边框(北、南、东、西、中心)时
涵盖主题:
- BorderLayout概述与位置约束
- 为每个位置添加控件
- 设计器与代码实现方式对比
- SetConstraints方法
- 间距配置(HGap、VGap)
- 按位置自定义尺寸
- MDI风格布局示例
- 停靠面板示例
- BorderLayout最佳实践
CardLayout (Wizard/Stack)
CardLayout(向导/堆叠布局)
📄 Read: references/card-layout.md
When to read: User needs wizards, property pages, or stack-based navigation.
Topics covered:
- CardLayout overview (one visible card at a time)
- Card naming and identification
- Navigation methods (First, Last, Next, Previous, ActivateCard)
- LayoutMode (Default, Fill)
- Image settings per card
- Designer usage (SelectedCard property)
- Programmatic card management
- Wizard control implementation
- Property page implementation
- Complete wizard example
- Best practices
📄 阅读: references/card-layout.md
适用场景: 用户需要实现向导、属性页或基于堆叠的导航时
涵盖主题:
- CardLayout概述(一次仅展示一张卡片)
- 卡片命名与标识
- 导航方法(First、Last、Next、Previous、ActivateCard)
- LayoutMode(默认、填充)
- 单卡片图片设置
- 设计器使用(SelectedCard属性)
- 编程方式管理卡片
- 向导控件实现
- 属性页实现
- 完整向导示例
- 最佳实践
FlowLayout (Flow Arrangement)
FlowLayout(流式排列)
📄 Read: references/flow-layout.md
When to read: User needs horizontal/vertical flow layouts (MOST COMMON use case).
Topics covered:
- FlowLayout overview (most versatile)
- LayoutMode (Horizontal, Vertical)
- Flow direction (normal, reverse)
- Alignment options (Near, Far, Center, ChildConstraints)
- AutoHeight feature for wrapping
- HGap and VGap spacing
- Per-child constraints (MinSize, PreferredSize)
- SetConstraints method
- Wrapping behavior
- Horizontal toolbar example
- Vertical sidebar example
- Tag list example
- Advanced constraint scenarios
- Best practices
📄 阅读: references/flow-layout.md
适用场景: 用户需要实现水平/垂直流式布局时(最常见的使用场景)
涵盖主题:
- FlowLayout概述(通用性最强)
- LayoutMode(水平、垂直)
- 流动方向(正向、反向)
- 对齐选项(近侧、远侧、居中、子控件约束)
- 支持换行的自动高度特性
- HGap与VGap间距配置
- 子控件级约束(最小尺寸、首选尺寸)
- SetConstraints方法
- 换行行为
- 水平工具栏示例
- 垂直侧边栏示例
- 标签列表示例
- 高级约束场景
- 最佳实践
GridLayout (Uniform Grid)
GridLayout(均匀网格)
📄 Read: references/grid-layout.md
When to read: User needs uniform grid with equal-sized cells.
Topics covered:
- GridLayout overview
- Rows and Columns configuration
- Automatic child placement order
- HGap and VGap spacing
- Designer vs code approaches
- Grid sizing behavior
- Calculator layout example
- Button grid example
- Best practices
📄 阅读: references/grid-layout.md
适用场景: 用户需要使用等大单元格的均匀网格时
涵盖主题:
- GridLayout概述
- 行列数配置
- 子控件自动摆放顺序
- HGap与VGap间距配置
- 设计器与代码实现方式对比
- 网格缩放行为
- 计算器布局示例
- 按钮网格示例
- 最佳实践
GridBagLayout (Flexible Grid)
GridBagLayout(灵活网格)
📄 Read: references/grid-bag-layout.md
When to read: User needs complex layouts with variable cell sizes and control spanning.
Topics covered:
- GridBagLayout overview (most powerful)
- Virtual grid concept (variable row/column sizes)
- GridBagConstraints configuration
- Anchor property (North, South, East, West, Center, NorthEast, NorthWest, SouthEast, SouthWest)
- Fill property (None, Horizontal, Vertical, Both)
- CellSpan (RowSpan, ColSpan)
- WeightX and WeightY (resize distribution)
- Insets (cell padding)
- Form layout example
- Calculator layout example
- Advanced spanning scenarios
- Best practices
📄 阅读: references/grid-bag-layout.md
适用场景: 用户需要实现支持可变单元格大小和控件跨列/行的复杂布局时
涵盖主题:
- GridBagLayout概述(功能最强大)
- 虚拟网格概念(可变行列尺寸)
- GridBagConstraints配置
- Anchor属性(北、南、东、西、中、东北、西北、东南、西南)
- Fill属性(无、水平、垂直、双向)
- CellSpan(RowSpan、ColSpan)
- WeightX与WeightY(缩放权重分配)
- Insets(单元格内边距)
- 表单布局示例
- 计算器布局示例
- 高级跨列/行场景
- 最佳实践
Layout Type Selection Guide
布局类型选择指南
Choose your layout based on requirements:
| Requirement | Recommended Layout | Why |
|---|---|---|
| Dock to borders (header/footer/sidebar) | BorderLayout | Simple 5-region positioning |
| Wizard or multi-step form | CardLayout | One visible card at a time with navigation |
| Horizontal button toolbar | FlowLayout (Horizontal) | Auto-wrapping, flexible spacing |
| Vertical sidebar or list | FlowLayout (Vertical) | Auto-wrapping, flexible spacing |
| Calculator or keypad | GridLayout or GridBagLayout | Uniform grid or flexible grid |
| Complex form with labels/fields | GridBagLayout | Variable cell sizes, spanning, alignment |
| Simple tabular layout (equal cells) | GridLayout | Uniform rows and columns |
| General-purpose responsive layout | FlowLayout | Most versatile, widely applicable |
根据需求选择合适的布局:
| 需求 | 推荐布局 | 原因 |
|---|---|---|
| 停靠到边框(头部/底部/侧边栏) | BorderLayout | 简单的5区域定位 |
| 向导或多步表单 | CardLayout | 一次展示一张可见卡片,支持导航 |
| 水平按钮工具栏 | FlowLayout(水平模式) | 自动换行、灵活间距 |
| 垂直侧边栏或列表 | FlowLayout(垂直模式) | 自动换行、灵活间距 |
| 计算器或键盘 | GridLayout 或 GridBagLayout | 均匀网格或灵活网格 |
| 带标签/输入框的复杂表单 | GridBagLayout | 可变单元格大小、跨列/行、对齐能力 |
| 简单表格布局(等大单元格) | GridLayout | 统一步调的行列 |
| 通用响应式布局 | FlowLayout | 通用性最强、适用场景广 |
Quick Start Examples
快速入门示例
BorderLayout: Dock to Borders
BorderLayout:停靠到边框
csharp
using Syncfusion.Windows.Forms.Tools;
// Create BorderLayout
BorderLayout borderLayout = new BorderLayout();
borderLayout.ContainerControl = panel1; // Panel as container
// Create controls for each position
Label northLabel = new Label { Text = "Header", BackColor = Color.LightBlue };
Label southLabel = new Label { Text = "Footer", BackColor = Color.LightGray };
Label eastLabel = new Label { Text = "Right", BackColor = Color.LightYellow };
Label westLabel = new Label { Text = "Left", BackColor = Color.LightGreen };
Panel centerPanel = new Panel { BackColor = Color.White };
// Add controls to container
panel1.Controls.Add(northLabel);
panel1.Controls.Add(southLabel);
panel1.Controls.Add(eastLabel);
panel1.Controls.Add(westLabel);
panel1.Controls.Add(centerPanel);
// Set constraints (position each control)
borderLayout.SetConstraints(northLabel, BorderPosition.North);
borderLayout.SetConstraints(southLabel, BorderPosition.South);
borderLayout.SetConstraints(eastLabel, BorderPosition.East);
borderLayout.SetConstraints(westLabel, BorderPosition.West);
borderLayout.SetConstraints(centerPanel, BorderPosition.Center);
// Configure spacing
borderLayout.HGap = 5;
borderLayout.VGap = 5;csharp
using Syncfusion.Windows.Forms.Tools;
// 创建BorderLayout
BorderLayout borderLayout = new BorderLayout();
borderLayout.ContainerControl = panel1; // 用Panel作为容器
// 为每个位置创建控件
Label northLabel = new Label { Text = "Header", BackColor = Color.LightBlue };
Label southLabel = new Label { Text = "Footer", BackColor = Color.LightGray };
Label eastLabel = new Label { Text = "Right", BackColor = Color.LightYellow };
Label westLabel = new Label { Text = "Left", BackColor = Color.LightGreen };
Panel centerPanel = new Panel { BackColor = Color.White };
// 向容器添加控件
panel1.Controls.Add(northLabel);
panel1.Controls.Add(southLabel);
panel1.Controls.Add(eastLabel);
panel1.Controls.Add(westLabel);
panel1.Controls.Add(centerPanel);
// 设置约束(为每个控件指定位置)
borderLayout.SetConstraints(northLabel, BorderPosition.North);
borderLayout.SetConstraints(southLabel, BorderPosition.South);
borderLayout.SetConstraints(eastLabel, BorderPosition.East);
borderLayout.SetConstraints(westLabel, BorderPosition.West);
borderLayout.SetConstraints(centerPanel, BorderPosition.Center);
// 配置间距
borderLayout.HGap = 5;
borderLayout.VGap = 5;CardLayout: Wizard Pages
CardLayout:向导页面
csharp
// Create CardLayout
CardLayout cardLayout = new CardLayout();
cardLayout.ContainerControl = panel1;
// Create wizard pages
Panel page1 = new Panel { BackColor = Color.AliceBlue };
Label label1 = new Label { Text = "Step 1: Welcome", Dock = DockStyle.Fill };
page1.Controls.Add(label1);
Panel page2 = new Panel { BackColor = Color.Honeydew };
Label label2 = new Label { Text = "Step 2: Configure", Dock = DockStyle.Fill };
page2.Controls.Add(label2);
Panel page3 = new Panel { BackColor = Color.LavenderBlush };
Label label3 = new Label { Text = "Step 3: Finish", Dock = DockStyle.Fill };
page3.Controls.Add(label3);
// Add pages to container
panel1.Controls.Add(page1);
panel1.Controls.Add(page2);
panel1.Controls.Add(page3);
// Name each card
cardLayout.SetConstraints(page1, "Welcome");
cardLayout.SetConstraints(page2, "Configure");
cardLayout.SetConstraints(page3, "Finish");
// Navigation
cardLayout.LayoutMode = CardLayoutMode.Fill; // Fill container
cardLayout.First(); // Show first card
// Navigate programmatically
// cardLayout.Next(); // Next card
// cardLayout.Previous(); // Previous card
// cardLayout.ActivateCard("Configure"); // Jump to specific cardcsharp
// 创建CardLayout
CardLayout cardLayout = new CardLayout();
cardLayout.ContainerControl = panel1;
// 创建向导页面
Panel page1 = new Panel { BackColor = Color.AliceBlue };
Label label1 = new Label { Text = "Step 1: Welcome", Dock = DockStyle.Fill };
page1.Controls.Add(label1);
Panel page2 = new Panel { BackColor = Color.Honeydew };
Label label2 = new Label { Text = "Step 2: Configure", Dock = DockStyle.Fill };
page2.Controls.Add(label2);
Panel page3 = new Panel { BackColor = Color.LavenderBlush };
Label label3 = new Label { Text = "Step 3: Finish", Dock = DockStyle.Fill };
page3.Controls.Add(label3);
// 向容器添加页面
panel1.Controls.Add(page1);
panel1.Controls.Add(page2);
panel1.Controls.Add(page3);
// 为每张卡片命名
cardLayout.SetConstraints(page1, "Welcome");
cardLayout.SetConstraints(page2, "Configure");
cardLayout.SetConstraints(page3, "Finish");
// 导航配置
cardLayout.LayoutMode = CardLayoutMode.Fill; // 填充容器
cardLayout.First(); // 展示第一张卡片
// 编程方式导航
// cardLayout.Next(); // 下一张卡片
// cardLayout.Previous(); // 上一张卡片
// cardLayout.ActivateCard("Configure"); // 跳转到指定卡片FlowLayout: Horizontal Toolbar
FlowLayout:水平工具栏
csharp
// Create FlowLayout
FlowLayout flowLayout = new FlowLayout();
flowLayout.ContainerControl = panel1;
flowLayout.LayoutMode = FlowLayoutMode.Horizontal;
flowLayout.Alignment = FlowAlignment.Near;
flowLayout.HGap = 10;
flowLayout.VGap = 5;
// Add buttons
for (int i = 1; i <= 8; i++)
{
Button btn = new Button { Text = $"Button {i}", Size = new Size(80, 30) };
panel1.Controls.Add(btn);
}
// Buttons will flow horizontally and wrap to next line automaticallycsharp
// 创建FlowLayout
FlowLayout flowLayout = new FlowLayout();
flowLayout.ContainerControl = panel1;
flowLayout.LayoutMode = FlowLayoutMode.Horizontal;
flowLayout.Alignment = FlowAlignment.Near;
flowLayout.HGap = 10;
flowLayout.VGap = 5;
// 添加按钮
for (int i = 1; i <= 8; i++)
{
Button btn = new Button { Text = $"Button {i}", Size = new Size(80, 30) };
panel1.Controls.Add(btn);
}
// 按钮会自动水平排列,超出容器宽度时自动换行GridLayout: Button Grid
GridLayout:按钮网格
csharp
// Create GridLayout (3x3 grid)
GridLayout gridLayout = new GridLayout();
gridLayout.ContainerControl = panel1;
gridLayout.Rows = 3;
gridLayout.Columns = 3;
gridLayout.HGap = 5;
gridLayout.VGap = 5;
// Add 9 buttons (automatic placement in grid)
for (int i = 1; i <= 9; i++)
{
Button btn = new Button { Text = i.ToString() };
panel1.Controls.Add(btn);
}csharp
// 创建GridLayout(3x3网格)
GridLayout gridLayout = new GridLayout();
gridLayout.ContainerControl = panel1;
gridLayout.Rows = 3;
gridLayout.Columns = 3;
gridLayout.HGap = 5;
gridLayout.VGap = 5;
// 添加9个按钮(自动摆放到网格中)
for (int i = 1; i <= 9; i++)
{
Button btn = new Button { Text = i.ToString() };
panel1.Controls.Add(btn);
}GridBagLayout: Form Layout
GridBagLayout:表单布局
csharp
// Create GridBagLayout
GridBagLayout gridBagLayout = new GridBagLayout();
gridBagLayout.ContainerControl = panel1;
// Create form controls
Label nameLabel = new Label { Text = "Name:", AutoSize = true };
TextBox nameTextBox = new TextBox { Width = 200 };
Label emailLabel = new Label { Text = "Email:", AutoSize = true };
TextBox emailTextBox = new TextBox { Width = 200 };
Button submitButton = new Button { Text = "Submit" };
// Add to container
panel1.Controls.Add(nameLabel);
panel1.Controls.Add(nameTextBox);
panel1.Controls.Add(emailLabel);
panel1.Controls.Add(emailTextBox);
panel1.Controls.Add(submitButton);
// Create constraints
GridBagConstraints labelConstraints = new GridBagConstraints(0, 0, 1, 1);
labelConstraints.Anchor = GridBagAnchor.East; // Align right
GridBagConstraints fieldConstraints = new GridBagConstraints(1, 0, 1, 1);
fieldConstraints.Fill = GridBagFill.Horizontal;
fieldConstraints.WeightX = 1; // Take extra horizontal space
// Apply constraints
gridBagLayout.SetConstraints(nameLabel, new GridBagConstraints(0, 0, 1, 1) { Anchor = GridBagAnchor.East });
gridBagLayout.SetConstraints(nameTextBox, new GridBagConstraints(1, 0, 1, 1) { Fill = GridBagFill.Horizontal, WeightX = 1 });
gridBagLayout.SetConstraints(emailLabel, new GridBagConstraints(0, 1, 1, 1) { Anchor = GridBagAnchor.East });
gridBagLayout.SetConstraints(emailTextBox, new GridBagConstraints(1, 1, 1, 1) { Fill = GridBagFill.Horizontal, WeightX = 1 });
gridBagLayout.SetConstraints(submitButton, new GridBagConstraints(1, 2, 1, 1) { Anchor = GridBagAnchor.West });csharp
// 创建GridBagLayout
GridBagLayout gridBagLayout = new GridBagLayout();
gridBagLayout.ContainerControl = panel1;
// 创建表单控件
Label nameLabel = new Label { Text = "Name:", AutoSize = true };
TextBox nameTextBox = new TextBox { Width = 200 };
Label emailLabel = new Label { Text = "Email:", AutoSize = true };
TextBox emailTextBox = new TextBox { Width = 200 };
Button submitButton = new Button { Text = "Submit" };
// 添加到容器
panel1.Controls.Add(nameLabel);
panel1.Controls.Add(nameTextBox);
panel1.Controls.Add(emailLabel);
panel1.Controls.Add(emailTextBox);
panel1.Controls.Add(submitButton);
// 创建约束
GridBagConstraints labelConstraints = new GridBagConstraints(0, 0, 1, 1);
labelConstraints.Anchor = GridBagAnchor.East; // 右对齐
GridBagConstraints fieldConstraints = new GridBagConstraints(1, 0, 1, 1);
fieldConstraints.Fill = GridBagFill.Horizontal;
fieldConstraints.WeightX = 1; // 占用额外水平空间
// 应用约束
gridBagLayout.SetConstraints(nameLabel, new GridBagConstraints(0, 0, 1, 1) { Anchor = GridBagAnchor.East });
gridBagLayout.SetConstraints(nameTextBox, new GridBagConstraints(1, 0, 1, 1) { Fill = GridBagFill.Horizontal, WeightX = 1 });
gridBagLayout.SetConstraints(emailLabel, new GridBagConstraints(0, 1, 1, 1) { Anchor = GridBagAnchor.East });
gridBagLayout.SetConstraints(emailTextBox, new GridBagConstraints(1, 1, 1, 1) { Fill = GridBagFill.Horizontal, WeightX = 1 });
gridBagLayout.SetConstraints(submitButton, new GridBagConstraints(1, 2, 1, 1) { Anchor = GridBagAnchor.West });Common Patterns
常用模式
Application Shell (BorderLayout)
应用外壳(BorderLayout)
csharp
// Header + Footer + Sidebar + Content area
BorderLayout borderLayout = new BorderLayout();
borderLayout.ContainerControl = this; // Form as container
borderLayout.HGap = 0;
borderLayout.VGap = 0;
Panel header = new Panel { Height = 60, BackColor = Color.Navy };
Panel footer = new Panel { Height = 30, BackColor = Color.Gray };
Panel sidebar = new Panel { Width = 200, BackColor = Color.LightGray };
Panel content = new Panel { BackColor = Color.White };
this.Controls.AddRange(new Control[] { header, footer, sidebar, content });
borderLayout.SetConstraints(header, BorderPosition.North);
borderLayout.SetConstraints(footer, BorderPosition.South);
borderLayout.SetConstraints(sidebar, BorderPosition.West);
borderLayout.SetConstraints(content, BorderPosition.Center);When to use: Main application window with fixed header/footer and sidebar.
csharp
// 头部 + 底部 + 侧边栏 + 内容区域
BorderLayout borderLayout = new BorderLayout();
borderLayout.ContainerControl = this; // 用Form作为容器
borderLayout.HGap = 0;
borderLayout.VGap = 0;
Panel header = new Panel { Height = 60, BackColor = Color.Navy };
Panel footer = new Panel { Height = 30, BackColor = Color.Gray };
Panel sidebar = new Panel { Width = 200, BackColor = Color.LightGray };
Panel content = new Panel { BackColor = Color.White };
this.Controls.AddRange(new Control[] { header, footer, sidebar, content });
borderLayout.SetConstraints(header, BorderPosition.North);
borderLayout.SetConstraints(footer, BorderPosition.South);
borderLayout.SetConstraints(sidebar, BorderPosition.West);
borderLayout.SetConstraints(content, BorderPosition.Center);适用场景: 带固定头部/底部和侧边栏的主应用窗口
Multi-Step Wizard (CardLayout)
多步向导(CardLayout)
See Quick Start example above. Add Next/Previous buttons to navigate between wizard steps.
参考上方快速入门示例,添加下一页/上一页按钮即可在向导步骤之间导航。
Responsive Toolbar (FlowLayout)
响应式工具栏(FlowLayout)
See Quick Start example above. Buttons automatically wrap when window resizes.
参考上方快速入门示例,窗口大小变化时按钮会自动换行。
Login Form (GridBagLayout)
登录表单(GridBagLayout)
csharp
// Labels in column 0, fields in column 1
// Submit button spans both columns
// All elements properly aligned and spacedSee GridBagLayout reference for complete example.
csharp
// 标签在第0列,输入框在第1列
// 提交按钮跨两列
// 所有元素对齐和间距统一规范完整示例参考GridBagLayout文档。
Key Properties
核心属性
Common to All Layouts
所有布局通用
| Property | Type | Description |
|---|---|---|
| ContainerControl | | Container (Panel, Form) where layout is applied |
| 属性 | 类型 | 描述 |
|---|---|---|
| ContainerControl | | 应用布局的容器(Panel、Form) |
BorderLayout
BorderLayout
| Property | Type | Description |
|---|---|---|
| HGap | | Horizontal gap between regions |
| VGap | | Vertical gap between regions |
| 属性 | 类型 | 描述 |
|---|---|---|
| HGap | | 区域之间的水平间距 |
| VGap | | 区域之间的垂直间距 |
CardLayout
CardLayout
| Property | Type | Description |
|---|---|---|
| LayoutMode | | Default or Fill |
| SelectedCard | | Currently visible card (designer) |
| 属性 | 类型 | 描述 |
|---|---|---|
| LayoutMode | | 默认或填充模式 |
| SelectedCard | | 当前可见的卡片(设计器使用) |
FlowLayout
FlowLayout
| Property | Type | Description |
|---|---|---|
| LayoutMode | | Horizontal or Vertical |
| Alignment | | Near, Far, Center, ChildConstraints |
| ReverseRows | | Reverse flow direction |
| AutoHeight | | Auto-adjust height for wrapping |
| HGap | | Horizontal gap between controls |
| VGap | | Vertical gap between controls |
| 属性 | 类型 | 描述 |
|---|---|---|
| LayoutMode | | 水平或垂直模式 |
| Alignment | | 近侧、远侧、居中、子控件约束 |
| ReverseRows | | 反转流动方向 |
| AutoHeight | | 换行时自动调整高度 |
| HGap | | 控件之间的水平间距 |
| VGap | | 控件之间的垂直间距 |
GridLayout
GridLayout
| Property | Type | Description |
|---|---|---|
| Rows | | Number of rows |
| Columns | | Number of columns |
| HGap | | Horizontal gap between cells |
| VGap | | Vertical gap between cells |
| 属性 | 类型 | 描述 |
|---|---|---|
| Rows | | 行数 |
| Columns | | 列数 |
| HGap | | 单元格之间的水平间距 |
| VGap | | 单元格之间的垂直间距 |
GridBagLayout
GridBagLayout
| Property | Type | Description |
|---|---|---|
| (Constraints set per child) | | See GridBagLayout reference |
| 属性 | 类型 | 描述 |
|---|---|---|
| (子控件级约束) | | 参考GridBagLayout文档 |
Common Use Cases
常见使用场景
1. Application Main Window
1. 应用主窗口
Scenario: Header, footer, sidebar, content area.
- Use BorderLayout
- North: Header, South: Footer, West: Sidebar, Center: Content
- Read: border-layout.md
场景: 头部、底部、侧边栏、内容区域。
- 使用 BorderLayout
- 北:头部,南:底部,西:侧边栏,中:内容
- 阅读:border-layout.md
2. Setup Wizard
2. 安装向导
Scenario: Multi-step configuration wizard.
- Use CardLayout
- Each card is one step, navigate with Next/Previous buttons
- Read: card-layout.md
场景: 多步配置向导。
- 使用 CardLayout
- 每张卡片对应一个步骤,通过下一页/上一页按钮导航
- 阅读:card-layout.md
3. Toolbar with Auto-Wrapping
3. 自动换行工具栏
Scenario: Horizontal toolbar that wraps to next line.
- Use FlowLayout (Horizontal mode)
- Set AutoHeight = true
- Read: flow-layout.md
场景: 超出宽度时自动换行的水平工具栏。
- 使用 FlowLayout(水平模式)
- 设置 AutoHeight = true
- 阅读:flow-layout.md
4. Calculator Keypad
4. 计算器键盘
Scenario: 4x4 button grid.
- Use GridLayout (4 rows, 4 columns)
- Or GridBagLayout for variable button sizes
- Read: grid-layout.md or grid-bag-layout.md
场景: 4x4按钮网格。
- 使用 GridLayout(4行4列)
- 若需要可变按钮大小可使用 GridBagLayout
- 阅读:grid-layout.md 或 grid-bag-layout.md
5. Data Entry Form
5. 数据录入表单
Scenario: Labels on left, fields on right.
- Use GridBagLayout
- Column 0: Labels (right-aligned), Column 1: Fields (fill horizontal)
- Read: grid-bag-layout.md
场景: 标签在左侧,输入框在右侧。
- 使用 GridBagLayout
- 第0列:标签(右对齐),第1列:输入框(水平填充)
- 阅读:grid-bag-layout.md
6. Tag Cloud
6. 标签云
Scenario: Tags that flow and wrap.
- Use FlowLayout (Horizontal mode)
- Add Label controls dynamically
- Read: flow-layout.md
场景: 可流动和换行的标签。
- 使用 FlowLayout(水平模式)
- 动态添加Label控件
- 阅读:flow-layout.md
Events
事件
Common layout event:
- LayoutComplete - Raised when layout recalculation is complete
csharp
flowLayout.LayoutComplete += (sender, e) => {
// Layout has been recalculated
};通用布局事件:
- LayoutComplete - 布局重新计算完成时触发
csharp
flowLayout.LayoutComplete += (sender, e) => {
// 布局已重新计算完成
};Best Practices
最佳实践
- Layout Selection: Use the selection guide above to choose the right layout type
- Container Requirements: Always set ContainerControl property (Panel, Form)
- Child Addition Order: Add children to container BEFORE setting constraints
- FlowLayout for Most Cases: When in doubt, start with FlowLayout (most versatile)
- GridBagLayout for Complex Forms: Use for professional data entry forms
- Spacing Consistency: Use HGap/VGap for consistent spacing
- Designer Support: Use designer for rapid prototyping, code for dynamic layouts
- Constraint Objects: Reuse GridBagConstraints objects for similar controls
- Testing Resize: Always test layouts with different container sizes
- Documentation: Comment constraint configurations for maintainability
- 布局选型: 参考上方选型指南选择合适的布局类型
- 容器要求: 始终设置ContainerControl属性(Panel、Form)
- 子控件添加顺序: 设置约束前先将子控件添加到容器中
- 绝大多数场景优先使用FlowLayout: 不确定用什么布局时先从FlowLayout开始(通用性最强)
- 复杂表单使用GridBagLayout: 用于开发专业的数据录入表单
- 间距统一: 使用HGap/VGap保证间距一致性
- 设计器支持: 快速原型开发使用设计器,动态布局使用代码实现
- 约束对象复用: 同类控件可复用GridBagConstraints对象
- 缩放测试: 始终用不同的容器尺寸测试布局适配性
- 文档说明: 为约束配置添加注释提升可维护性