syncfusion-winforms-grid-layout

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing GridLayout in Windows Forms

在Windows Forms中实现GridLayout

GridLayout is a layout manager that automatically arranges child controls in a grid structure containing rows and columns. Use this skill when you need to organize multiple controls in a structured grid format with precise spacing control.

GridLayout是一种布局管理器，可自动将子控件排列到包含行列的网格结构中。当你需要以结构化的网格格式组织多个控件，且要精确控制间距时，可以使用这个技巧。

When to Use This Skill

适用场景

Arranging child controls in grid-based layouts
Creating uniform row and column structures
Controlling horizontal and vertical spacing between controls
Dynamically including or excluding controls from layout
Programmatic or designer-based control arrangement

基于网格布局排列子控件
创建统一的行列结构
控制控件之间的水平和垂直间距
动态将控件加入布局或从布局中排除
基于编程或设计器的控件排列

Component Overview

组件概览

GridLayout provides:

Grid Structure: Automatic arrangement in rows and columns
Spacing Control: Horizontal (HGap) and vertical (VGap) gap configuration
Control Participation: Include or exclude controls from layout management
Dynamic Configuration: Rows and columns can be set programmatically

GridLayout提供以下能力：

网格结构：自动按行列排列
间距控制：水平（HGap）和垂直（VGap）间距配置
控件参与规则：可将控件纳入布局管理或排除在外
动态配置：可通过编程方式设置行列参数

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly deployment and NuGet setup
Creating GridLayout through designer or code
Adding child controls to the layout
Basic implementation patterns

📄 阅读： references/getting-started.md

程序集部署与NuGet设置
通过设计器或代码创建GridLayout
向布局中添加子控件
基础实现模式

Rows and Columns Configuration

行列配置

📄 Read: references/rows-and-columns-configuration.md

Setting number of rows and columns
Understanding Rows property precedence
Auto-sizing behavior based on child control count
Grid division strategies

📄 阅读： references/rows-and-columns-configuration.md

设置行列数量
理解Rows属性的优先级
基于子控件数量的自动调整大小行为
网格划分策略

Spacing and Gaps

间距与留白

📄 Read: references/spacing-and-gaps.md

Configuring horizontal gaps (HGap)
Configuring vertical gaps (VGap)
Spacing calculations and effects
Common spacing patterns

📄 阅读： references/spacing-and-gaps.md

配置水平间距（HGap）
配置垂直间距（VGap）
间距计算逻辑与效果
常用间距模式

Managing Child Controls

子控件管理

📄 Read: references/managing-child-controls.md

ParticipateInLayout property overview
Adding or removing controls from layout
Checking control layout participation
Rearranging controls at design time

📄 阅读： references/managing-child-controls.md

ParticipateInLayout属性概览
向布局中添加或移除控件
检查控件的布局参与状态
设计时重新排列控件

Quick Start Example

快速入门示例

csharp

using Syncfusion.Windows.Forms.Tools;

// Create GridLayout instance
GridLayout gridLayout1 = new GridLayout();
gridLayout1.ContainerControl = this;

// Configure grid structure
gridLayout1.Rows = 2;
gridLayout1.Columns = 2;

// Set spacing
gridLayout1.HGap = 10;
gridLayout1.VGap = 10;

// Add child controls
ButtonAdv button1 = new ButtonAdv() { Text = "Button 1" };
ButtonAdv button2 = new ButtonAdv() { Text = "Button 2" };

this.Controls.Add(button1);
this.Controls.Add(button2);

// Include controls in layout
gridLayout1.SetParticipateInLayout(button1, true);
gridLayout1.SetParticipateInLayout(button2, true);

csharp

using Syncfusion.Windows.Forms.Tools;

// Create GridLayout instance
GridLayout gridLayout1 = new GridLayout();
gridLayout1.ContainerControl = this;

// Configure grid structure
gridLayout1.Rows = 2;
gridLayout1.Columns = 2;

// Set spacing
gridLayout1.HGap = 10;
gridLayout1.VGap = 10;

// Add child controls
ButtonAdv button1 = new ButtonAdv() { Text = "Button 1" };
ButtonAdv button2 = new ButtonAdv() { Text = "Button 2" };

this.Controls.Add(button1);
this.Controls.Add(button2);

// Include controls in layout
gridLayout1.SetParticipateInLayout(button1, true);
gridLayout1.SetParticipateInLayout(button2, true);

Key Configuration Properties

核心配置属性

Property	Type	Purpose
Rows	int	Specifies number of rows in the grid (dictates columns if set)
Columns	int	Specifies number of columns (used when Rows is null or negative)
HGap	int	Horizontal spacing between controls and layout border
VGap	int	Vertical spacing between controls and layout border
ContainerControl	Control	The form or container that holds the layout manager

属性	类型	用途
Rows	int	指定网格的行数（如果设置了该值，列数会由其决定）
Columns	int	指定列数（当Rows为null或负数时生效）
HGap	int	控件之间以及控件与布局边框之间的水平间距
VGap	int	控件之间以及控件与布局边框之间的垂直间距
ContainerControl	Control	承载布局管理器的窗体或容器

Common Patterns

常用模式

Pattern 1: Single Column Layout

模式1：单列布局

csharp

gridLayout1.Rows = null;  // Let rows auto-calculate
gridLayout1.Columns = 1;

Useful for vertical stacking of controls.

csharp

gridLayout1.Rows = null;  // Let rows auto-calculate
gridLayout1.Columns = 1;

适用于控件的垂直堆叠场景。

Pattern 2: Grid with Uniform Spacing

模式2：统一间距网格

csharp

gridLayout1.Rows = 3;
gridLayout1.Columns = 3;
gridLayout1.HGap = 5;
gridLayout1.VGap = 5;

Creates 3x3 grid with 5-pixel spacing.

csharp

gridLayout1.Rows = 3;
gridLayout1.Columns = 3;
gridLayout1.HGap = 5;
gridLayout1.VGap = 5;

创建间距为5像素的3×3网格。

Pattern 3: Conditional Control Visibility

模式3：条件控件可见性

csharp

// Hide a control from layout without removing it
gridLayout1.SetParticipateInLayout(controlToHide, false);

Allows dynamic layout adjustments without removing controls.

csharp

// Hide a control from layout without removing it
gridLayout1.SetParticipateInLayout(controlToHide, false);

无需移除控件即可将其从布局中隐藏，支持动态调整布局。