对于Qt:QGripLayout常见属性、方法以及QSizePolicy的解析

开篇介绍:

hello 大家,本篇博客我们来学习QGripLayout常见属性、方法以及QSizePolicy。

前面的文章里,我们花了超两万字的篇幅,详细讲解了 Qt 中最基础、最常用的两个线性布局管理器:**QVBoxLayout(垂直布局)** 和 QHBoxLayout(水平布局)------ 它们能帮我们解决绝大多数 "单列" 或 "单行" 的控件排列问题,替代了繁琐的绝对定位。

但在实际开发中,我们经常会遇到更复杂的界面需求:比如一个表单,有 "姓名""邮箱""电话" 等标签和输入框,它们需要 "多行多列" 排列;比如一个计算器,数字键和符号键需要按网格排列;比如一个图片查看器,缩略图需要按 M×N 的网格展示。

这时候,只用 QVBoxLayout 或 QHBoxLayout 就会很麻烦 ------ 我们需要多层嵌套,代码写起来复杂,维护起来也困难。

这时候,我们就需要今天要学的 Qt 中最灵活、最强大的布局管理器之一:QGridLayout(网格布局管理器)。

QGridLayout 就像 "我们平时用的 Excel 表格"------ 它把控件放在一个二维的网格里,你可以精准地把控件放到 "第 N 行第 M 列";你可以让一个控件 "合并单元格",占多行多列;你可以独立设置 "列与列之间的水平间距" 和 "行与行之间的垂直间距";你还可以设置 "窗口缩放时,哪一列 / 行分配更多的空间"。

值得一提的是,QGridLayout 完全兼容 QVBoxLayout 和 QHBoxLayout 的效果 ------ 如果你把所有控件都放在同一行,它就是 QHBoxLayout;如果你把所有控件都放在同一列,它就是 QVBoxLayout。可以说,QGridLayout 是 "一个顶俩" 的布局管理器。

当然,QGridLayout 虽然强大,但也有一些细节需要注意:比如行 / 列索引从 0 开始、稀疏行列不占位、设置行拉伸时必须配合控件的 QSizePolicy(尺寸策略) 等等。特别是 QSizePolicy,这是 90% 的新手都会踩的坑 ------ 很多新手设置了行拉伸因子,但发现控件高度没变,就是因为没设置 QSizePolicy。

这篇文章我会结合 Qt 官方文档和实际开发经验,按照最常用的顺序:先讲 QGridLayout 的基础概念 (是什么、为什么用它、和 QVBox/QHBox 的区别),再逐个讲 QGridLayout 的核心属性 (四边距、水平 / 垂直间距、行 / 列拉伸系数),然后讲 QGridLayout 的核心方法 (addWidget 基础定位与跨行列、addLayout 嵌套布局、setColumnStretch/setRowStretch 拉伸因子、setSpacing/setContentsMargins 间距边距),接着单独用一章讲 QSizePolicy(尺寸策略) (这是行拉伸的关键,必须搞懂),最后是综合示例 和全文总结。

话不多说,我们正式开始!


第一章 先搞懂基础:QGridLayout 是什么?为什么要用它?

在讲具体属性和方法之前,我们必须先搞懂几个最基础、最重要的问题:QGridLayout 是用来做什么的?为什么要用它?它和我们之前学的 QVBoxLayout、QHBoxLayout 有什么区别?以及,布局管理器的通用规则是什么?

1.1 QGridLayout 的核心定位

QGridLayout 是 Qt Widgets 模块中网格布局管理器------ 它支持将子控件按 M×N 的二维网格形式排列(行 + 列布局),是 Qt 布局管理器体系中最灵活的核心组件之一。

通俗理解:QGridLayout 就是 "一个 Excel 表格"------ 你可以把每个控件想象成 Excel 里的 "单元格内容";你可以精准地把内容填到 "第 N 行第 M 列";你可以像 "合并单元格" 一样,让一个控件占多行多列;你可以调整 "单元格之间的空隙";你还可以设置 "表格变宽 / 变高时,哪一列 / 行分更多的空间"。

QGridLayout 的核心价值,主要有三个:

  1. 精准二维定位:突破了 QVBox/QHBox 单一方向排列的限制,支持 "行 + 列" 的二维坐标定位,想把控件放哪儿就放哪儿;
  2. 精细化空间控制:可独立设置水平 / 垂直方向的间距,以及行 / 列的拉伸系数,精细化控制控件的尺寸比例;
  3. 兼容线性布局:所有控件放同一行 = QHBoxLayout,所有控件放同一列 = QVBoxLayout,一个顶俩;
  4. 自动适配窗口缩放:和其他布局管理器一样,无需手动计算控件坐标 / 尺寸,窗口缩放时控件自动调整。

1.2 QGridLayout 和 QVBoxLayout、QHBoxLayout 的核心区别(必知!)

为了让大家更直观地理解,我用一个表格把它们的核心区别列出来:

对比维度 QVBoxLayout 垂直布局 QHBoxLayout 水平布局 QGridLayout 网格布局
排列方式 单一垂直方向(从上到下) 单一水平方向(从左到右) 二维网格(行 + 列)
定位方式 按添加顺序排列 按添加顺序排列 按 "行索引 + 列索引" 精准定位
灵活性 低(仅单列) 低(仅单行) 高(多行多列,可跨行列)
间距控制 单一 spacing(垂直间距) 单一 spacing(水平间距) 独立 horizontalSpacing(列间距)+ verticalSpacing(行间距)
空间控制 无(或需嵌套) 无(或需嵌套) setColumnStretch/setRowStretch(独立控制行列拉伸)
适用场景 单列控件排列 单行控件排列 复杂多行多列控件排列
代码复杂度 低(简单场景) 低(简单场景) 低(简单场景)~ 中(复杂场景),但比多层嵌套线性布局简单

通俗理解:

  • QVBoxLayout 是 "一列书架"------ 书只能从上到下排;
  • QHBoxLayout 是 "一排桌子"------ 东西只能从左到右排;
  • QGridLayout 是 "一个 Excel 表格"------ 东西可以放到任意单元格,还能合并单元格。

1.3 布局管理器的通用规则(开篇就讲,刻在脑子里!)

和 QVBoxLayout、QHBoxLayout 一样,QGridLayout 也遵循布局管理器的通用规则,这些规则超级重要,新手最容易踩坑,必须开篇就讲,刻在脑子里:

  1. 一个 QWidget 对象仅能设置一个顶层布局管理器!(超级重要!说三遍!) :
    • 你不能给同一个 Widget 调用两次 setLayout();
    • 第二次调用会无效,甚至会导致程序崩溃;
    • 如果你想做多个布局,需要通过 "嵌套 Widget + 嵌套布局" 来实现(后面会讲);
  2. 控件添加到布局后,不需要手动设置父对象!(超级重要!) :
    • 当你把一个控件添加到布局后,布局会自动将该控件的父对象设为 "布局所属的 Widget";
    • 你不需要手动写 btn->setParent(this);
    • 当然,写了也不会错,但没必要;
  3. 布局管理器仅负责界面布局,无任何用户交互相关的信号!(超级重要!) :
    • 布局管理器是 "纯视觉 / 布局控制组件";
    • 它没有任何信号(比如 clicked、pressed 等);
    • 它只负责把控件摆好,不负责和用户交互;
  4. 布局管理器不是 Qt 独有!(拓展知识) :
    • 其实很多 GUI 框架都有类似的布局机制;
    • 核心思想都是一样的:自动管理控件的位置和尺寸,替代手动绝对定位。

第二章 QGridLayout 核心属性详解

好,我们正式开始!按照最常用的顺序,我们逐个讲 QGridLayout 的核心属性:layoutLeftMargin、layoutRightMargin、layoutTopMargin、layoutBottomMargin、layoutHorizontalSpacing、layoutVerticalSpacing、layoutRowStretch、layoutColumnStretch。

注意:这些属性不是直接访问的,而是通过对应的成员函数来设置和获取的,我会在每个属性里详细讲。


2.1 属性一:layoutLeftMargin------ 布局管理器左侧与父 Widget 边缘的内边距

2.1.1 属性的核心定义

layoutLeftMargin 是 QGridLayout 用于控制整个网格布局最左侧与父 Widget 左边界距离的样式属性 ------ 在网格布局中,它具体控制的是 "最左列的最左侧" 与父 Widget 左边界的距离,默认值由系统样式决定(通常为 9 像素左右),你可以自定义调整。

通俗理解:layoutLeftMargin 就像 "Excel 表格和左边墙之间的距离"------ 距离越大,表格最左边的那一列离左边墙越远;距离越小,表格最左边的那一列离左边墙越近。

这里有几个超级重要的规则,必须牢记:

  1. 整体生效:它控制的是 "整个网格布局的整体" 与父 Widget 左边界的距离,不是单个控件;
  2. 默认值由系统决定:不同操作系统(Windows、macOS、Linux)的默认值可能不一样;
  3. 推荐批量设置 :单独设置单侧边距易导致样式不一致,优先使用 setContentsMargins() 批量设置四边距(后面会讲)。
2.1.2 关联 API 详解(逐词逐句,零模糊)

我们可以通过两个成员函数来单独设置和获取左侧边距:

1. 获取左侧边距:int leftMargin () const

函数原型:

复制代码
int QGridLayout::leftMargin() const;

逐词逐句底层解析:

  • int:返回值类型,返回左侧边距的数值,单位是像素;
  • QGridLayout:::说明这个函数是 QGridLayout 类的成员函数,只能用 QGridLayout 对象调用;
  • leftMargin():函数名,很直观,就是 "获取左侧边距" 的意思;
  • const:常成员函数,说明这个函数不会修改布局管理器的状态,只是读取信息,所以可以用 const 的 QGridLayout 对象调用。

返回值说明:

  • 返回 int 类型的整数;
  • 单位是像素;
  • 返回当前布局管理器的左侧边距。
2. 设置左侧边距:void setLeftMargin (int margin)

函数原型:

复制代码
void QGridLayout::setLeftMargin(int margin);

逐词逐句底层解析:

  • void:无返回值,说明这个函数只是执行设置操作,不返回任何结果;
  • QGridLayout:::成员函数;
  • setLeftMargin():函数名,"设置左侧边距" 的意思,Qt 里设置属性的函数通常都以 set 开头,后面跟属性名(首字母大写);
  • int margin:入参,要设置的左侧边距数值,单位是像素。

参数说明:

  • margin:要设置的左侧边距,int 类型;
    • 单位是像素;
    • 可以是 0(整个网格布局紧贴父 Widget 左边界);
    • 不建议是负数(可能导致最左列的控件超出父 Widget 左边界,显示不全)。
2.1.3 使用示例
复制代码
#include <QGridLayout>
#include <QPushButton>
#include <QWidget>
#include <QDebug>

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:单独设置左侧边距(仅作演示,推荐批量设置)
QGridLayout* layout = new QGridLayout();

// 添加一个按钮到 0 行 0 列(最左列)
layout->addWidget(new QPushButton("最左列按钮"), 0, 0);

// 【单独设置】左侧边距为 30 像素
// 效果:最左列的"最左列按钮"离窗口左边界 30 像素
layout->setLeftMargin(30);

// 获取当前左侧边距并打印
int currentLeftMargin = layout->leftMargin();
qDebug() << "当前左侧边距:" << currentLeftMargin << "像素"; // 输出:30

// 将布局设置给窗口
this->setLayout(layout);
2.1.4 关键注意事项(必知!)
  1. 单独设置易导致样式不一致!(超级重要!说三遍!) :
    • 如果你只设置左侧边距,不设置右侧、上方、下方边距;
    • 界面可能会看起来 "一边宽一边窄",视觉上不平衡;
    • 强烈推荐使用 setContentsMargins() 批量设置四边距(后面会讲);
  2. 单位是像素!(超级重要!) :
    • 所有边距的单位都是像素;
    • 不是厘米、不是英寸,是像素;
  3. 不建议设为负数!(超级重要!) :
    • 如果你把边距设为负数;
    • 布局内的控件可能会超出父 Widget 的边界;
    • 导致控件显示不全,甚至被父 Widget 裁剪掉;
    • 非常不推荐!
  4. 默认值由系统样式决定! :
    • 不同操作系统的默认边距可能不一样;
    • Windows、macOS、Linux 的系统样式不同,默认边距也不同;
    • 如果你想让界面在所有系统上看起来都一样,建议显式设置边距,不要用默认值。

2.2 属性二:layoutRightMargin------ 布局管理器右侧与父 Widget 边缘的内边距

2.2.1 属性的核心定义

layoutRightMargin 是 QGridLayout 用于控制整个网格布局最右侧与父 Widget 右边界距离 的样式属性 ------ 在网格布局中,它具体控制的是 "最右列的最右侧" 与父 Widget 右边界的距离,它和 layoutLeftMargin 配合,控制布局水平方向的内边距,默认值同样由系统样式决定(通常为 9 像素左右)。

通俗理解:layoutRightMargin 就像 "Excel 表格和右边墙之间的距离"------ 距离越大,表格最右边的那一列离右边墙越远;距离越小,表格最右边的那一列离右边墙越近。

这里的规则和 layoutLeftMargin 几乎一样,我就不重复讲了,重点讲关联 API。

2.2.2 关联 API 详解(逐词逐句,零模糊)
1. 获取右侧边距:int rightMargin () const

函数原型:

复制代码
int QGridLayout::rightMargin() const;

逐词逐句底层解析:

  • int:返回值类型,返回右侧边距的数值,单位是像素;
  • QGridLayout:::成员函数;
  • rightMargin():函数名,"获取右侧边距" 的意思;
  • const:常成员函数。

返回值说明:

  • 返回 int 类型的整数,单位是像素;
  • 返回当前布局管理器的右侧边距。
2. 设置右侧边距:void setRightMargin (int margin)

函数原型:

复制代码
void QGridLayout::setRightMargin(int margin);

逐词逐句底层解析:

  • void:无返回值;
  • QGridLayout:::成员函数;
  • setRightMargin():函数名,"设置右侧边距" 的意思;
  • int margin:入参,要设置的右侧边距数值,单位是像素。

参数说明:

  • margin:要设置的右侧边距,int 类型;
    • 单位是像素;
    • 可以是 0(整个网格布局紧贴父 Widget 右边界);
    • 不建议是负数。
2.2.3 使用示例
复制代码
#include <QGridLayout>
#include <QPushButton>
#include <QWidget>
#include <QDebug>

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:单独设置右侧边距(仅作演示,推荐批量设置)
QGridLayout* layout = new QGridLayout();

// 添加一个按钮到 0 行 2 列(假设是最右列)
layout->addWidget(new QPushButton("最右列按钮"), 0, 2);

// 【单独设置】右侧边距为 30 像素
// 效果:最右列的"最右列按钮"离窗口右边界 30 像素
layout->setRightMargin(30);

// 获取当前右侧边距并打印
int currentRightMargin = layout->rightMargin();
qDebug() << "当前右侧边距:" << currentRightMargin << "像素"; // 输出:30

this->setLayout(layout);
2.2.4 关键注意事项(必知!)

和 layoutLeftMargin 的注意事项完全一样,我再简单重复一遍,加深记忆:

  1. 单独设置易导致样式不一致! :推荐用 setContentsMargins() 批量设置;
  2. 单位是像素!;
  3. 不建议设为负数!;
  4. 默认值由系统样式决定!。

2.3 属性三:layoutTopMargin------ 布局管理器上方与父 Widget 边缘的内边距

2.3.1 属性的核心定义

layoutTopMargin 是 QGridLayout 用于控制整个网格布局最上方与父 Widget 上边界距离的样式属性 ------ 在网格布局中,它具体控制的是 "最上行的最上方" 与父 Widget 上边界的距离,默认值由系统样式决定(通常为 9 像素左右)。

通俗理解:layoutTopMargin 就像 "Excel 表格和天花板之间的距离"------ 距离越大,表格最上面的那一行离天花板越远;距离越小,表格最上面的那一行离天花板越近。

2.3.2 关联 API 详解(逐词逐句,零模糊)
1. 获取上方边距:int topMargin () const

函数原型:

复制代码
int QGridLayout::topMargin() const;

逐词逐句底层解析:

  • int:返回值类型,返回上方边距的数值,单位是像素;
  • QGridLayout:::成员函数;
  • topMargin():函数名,"获取上方边距" 的意思;
  • const:常成员函数。

返回值说明:

  • 返回 int 类型的整数,单位是像素;
  • 返回当前布局管理器的上方边距。
2. 设置上方边距:void setTopMargin (int margin)

函数原型:

复制代码
void QGridLayout::setTopMargin(int margin);

逐词逐句底层解析:

  • void:无返回值;
  • QGridLayout:::成员函数;
  • setTopMargin():函数名,"设置上方边距" 的意思;
  • int margin:入参,要设置的上方边距数值,单位是像素。

参数说明:

  • margin:要设置的上方边距,int 类型;
    • 单位是像素;
    • 可以是 0(整个网格布局紧贴父 Widget 上边界);
    • 不建议是负数。
2.3.3 使用示例
复制代码
#include <QGridLayout>
#include <QPushButton>
#include <QWidget>
#include <QDebug>

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:单独设置上方边距(仅作演示,推荐批量设置)
QGridLayout* layout = new QGridLayout();

// 添加一个按钮到 0 行 0 列(最上行)
layout->addWidget(new QPushButton("最上行按钮"), 0, 0);

// 【单独设置】上方边距为 20 像素
// 效果:最上行的"最上行按钮"离窗口上边界 20 像素
layout->setTopMargin(20);

// 获取当前上方边距并打印
int currentTopMargin = layout->topMargin();
qDebug() << "当前上方边距:" << currentTopMargin << "像素"; // 输出:20

this->setLayout(layout);
2.3.4 关键注意事项(必知!)

和之前的注意事项完全一样:

  1. 单独设置易导致样式不一致! :推荐用 setContentsMargins() 批量设置;
  2. 单位是像素!;
  3. 不建议设为负数!;
  4. 默认值由系统样式决定!。

2.4 属性四:layoutBottomMargin------ 布局管理器下方与父 Widget 边缘的内边距

2.4.1 属性的核心定义

layoutBottomMargin 是 QGridLayout 用于控制整个网格布局最下方与父 Widget 下边界距离 的样式属性 ------ 在网格布局中,它具体控制的是 "最下行的最下方" 与父 Widget 下边界的距离,它和 layoutTopMargin 配合,控制布局垂直方向的内边距,默认值由系统样式决定(通常为 9 像素左右)。

通俗理解:layoutBottomMargin 就像 "Excel 表格和地面之间的距离"------ 距离越大,表格最下面的那一行离地面越远;距离越小,表格最下面的那一行离地面越近。

2.4.2 关联 API 详解(逐词逐句,零模糊)
1. 获取下方边距:int bottomMargin () const

函数原型:

复制代码
int QGridLayout::bottomMargin() const;

逐词逐句底层解析:

  • int:返回值类型,返回下方边距的数值,单位是像素;
  • QGridLayout:::成员函数;
  • bottomMargin():函数名,"获取下方边距" 的意思;
  • const:常成员函数。

返回值说明:

  • 返回 int 类型的整数,单位是像素;
  • 返回当前布局管理器的下方边距。
2. 设置下方边距:void setBottomMargin (int margin)

函数原型:

复制代码
void QGridLayout::setBottomMargin(int margin);

逐词逐句底层解析:

  • void:无返回值;
  • QGridLayout:::成员函数;
  • setBottomMargin():函数名,"设置下方边距" 的意思;
  • int margin:入参,要设置的下方边距数值,单位是像素。

参数说明:

  • margin:要设置的下方边距,int 类型;
    • 单位是像素;
    • 可以是 0(整个网格布局紧贴父 Widget 下边界);
    • 不建议是负数。
2.4.3 使用示例
复制代码
#include <QGridLayout>
#include <QPushButton>
#include <QWidget>
#include <QDebug>

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:单独设置下方边距(仅作演示,推荐批量设置)
QGridLayout* layout = new QGridLayout();

// 添加一个按钮到 2 行 0 列(假设是最下行)
layout->addWidget(new QPushButton("最下行按钮"), 2, 0);

// 【单独设置】下方边距为 20 像素
// 效果:最下行的"最下行按钮"离窗口下边界 20 像素
layout->setBottomMargin(20);

// 获取当前下方边距并打印
int currentBottomMargin = layout->bottomMargin();
qDebug() << "当前下方边距:" << currentBottomMargin << "像素"; // 输出:20

this->setLayout(layout);
2.4.4 关键注意事项(必知!)

和之前的注意事项完全一样:

  1. 单独设置易导致样式不一致! :推荐用 setContentsMargins() 批量设置;
  2. 单位是像素!;
  3. 不建议设为负数!;
  4. 默认值由系统样式决定!。

2.5 属性五:layoutHorizontalSpacing------ 网格中列与列之间的水平间距

2.5.1 属性的核心定义

layoutHorizontalSpacing 是 QGridLayout 用于控制网格中 "列与列之间" 水平距离 的样式属性 ------ 这是它和 QVBoxLayout/QHBoxLayout 最大的不同之一:QVBoxLayout/QHBoxLayout 只有一个单一的 spacing,而 QGridLayout 可以独立控制水平间距和垂直间距。

在网格布局中,layoutHorizontalSpacing 具体控制的是 "左右相邻两列控件" 之间的水平距离,默认值由系统样式决定(通常为 6 像素左右),你可以自定义调整,让界面看起来更宽松或更紧凑。

通俗理解:layoutHorizontalSpacing 就像 "Excel 表格中列与列之间的空隙"------ 空隙越大,左右相邻的两列离得越远;空隙越小,左右相邻的两列离得越近。

这里有几个超级重要的规则,必须牢记:

  1. 全局生效:设置后对布局内所有相邻列生效,无法单独设置某两列的间距;
  2. 默认值由系统决定:不同操作系统的默认值可能不一样;
  3. 独立于垂直间距:水平间距和垂直间距是分开设置的,互不影响。
2.5.2 关联 API 详解(逐词逐句,零模糊)

通过两个成员函数设置和获取:

1. 获取列与列之间的水平间距:int horizontalSpacing () const

函数原型:

复制代码
int QGridLayout::horizontalSpacing() const;

逐词逐句底层解析:

  • int:返回值类型,返回水平间距的数值,单位是像素;
  • QGridLayout:::成员函数;
  • horizontalSpacing():函数名,"获取水平间距" 的意思,"Horizontal" 是 "水平的" 意思;
  • const:常成员函数。

返回值说明:

  • 返回 int 类型的整数,单位是像素;
  • 返回当前布局管理器内列与列之间的水平间距。
2. 设置列与列之间的水平间距:void setHorizontalSpacing (int spacing)

函数原型:

复制代码
void QGridLayout::setHorizontalSpacing(int spacing);

逐词逐句底层解析:

  • void:无返回值;
  • QGridLayout:::成员函数;
  • setHorizontalSpacing():函数名,"设置水平间距" 的意思;
  • int spacing:入参,要设置的水平间距数值,单位是像素。

参数说明:

  • spacing:要设置的水平间距,int 类型;
    • 单位是像素;
    • 可以是 0(左右相邻列紧贴在一起);
    • 不建议是负数(可能导致左右相邻列的控件重叠);
    • 推荐值:5-20 像素,根据界面风格调整。
2.5.3 使用示例
复制代码
#include <QGridLayout>
#include <QPushButton>
#include <QWidget>
#include <QDebug>

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:设置列与列之间的水平间距
QGridLayout* layout = new QGridLayout();

// 添加三个按钮到 0 行 0 列、0 行 1 列、0 行 2 列
layout->addWidget(new QPushButton("列0"), 0, 0);
layout->addWidget(new QPushButton("列1"), 0, 1); // 与列0的水平间距默认
layout->addWidget(new QPushButton("列2"), 0, 2); // 与列1的水平间距默认

// 【关键!】设置所有左右相邻列之间的水平间距为 20 像素
layout->setHorizontalSpacing(20);

// 获取当前水平间距并打印
int currentHSpacing = layout->horizontalSpacing();
qDebug() << "当前列与列之间的水平间距:" << currentHSpacing << "像素"; // 输出:20

this->setLayout(layout);
2.5.4 关键注意事项(必知!)
  1. 全局生效!(超级重要!说三遍!) :
    • setHorizontalSpacing() 是针对布局内所有左右相邻列的!
    • 要么所有列之间的水平间距都一样,要么都不一样(不行,必须一样);
    • 无法单独设置 "列 0 和列 1 间距 10px,列 1 和列 2 间距 20px";
  2. 独立于垂直间距!(超级重要!) :
    • 水平间距和垂直间距是分开设置的!
    • 你可以设置水平间距 20px,垂直间距 10px;
    • 互不影响,非常灵活;
  3. 单位是像素!(超级重要!);
  4. 不建议设为负数!(超级重要!) :
    • 如果你把水平间距设为负数;
    • 左右相邻列的控件可能会重叠在一起;
    • 导致界面混乱,非常不推荐;
  5. 默认值由系统样式决定!;
  6. 推荐值!(经验之谈) :
    • 通常情况下,水平间距设为 5-20 像素比较合适;
    • 界面风格比较紧凑的话,设为 5-10 像素;
    • 界面风格比较宽松的话,设为 10-20 像素;
    • 可以根据实际情况调整。

2.6 属性六:layoutVerticalSpacing------ 网格中行与行之间的垂直间距

2.6.1 属性的核心定义

layoutVerticalSpacing 是 QGridLayout 用于控制网格中 "行与行之间" 垂直距离 的样式属性 ------ 它和 layoutHorizontalSpacing 配合,分别控制垂直和水平方向的间距,默认值由系统样式决定(通常为 6 像素左右)。

在网格布局中,layoutVerticalSpacing 具体控制的是 "上下相邻两行控件" 之间的垂直距离,你可以自定义调整,让界面看起来更宽松或更紧凑。

通俗理解:layoutVerticalSpacing 就像 "Excel 表格中行与行之间的空隙"------ 空隙越大,上下相邻的两行离得越远;空隙越小,上下相邻的两行离得越近。

2.6.2 关联 API 详解(逐词逐句,零模糊)

通过两个成员函数设置和获取:

1. 获取行与行之间的垂直间距:int verticalSpacing () const

函数原型:

复制代码
int QGridLayout::verticalSpacing() const;

逐词逐句底层解析:

  • int:返回值类型,返回垂直间距的数值,单位是像素;
  • QGridLayout:::成员函数;
  • verticalSpacing():函数名,"获取垂直间距" 的意思,"Vertical" 是 "垂直的" 意思;
  • const:常成员函数。

返回值说明:

  • 返回 int 类型的整数,单位是像素;
  • 返回当前布局管理器内行与行之间的垂直间距。
2. 设置行与行之间的垂直间距:void setVerticalSpacing (int spacing)

函数原型:

复制代码
void QGridLayout::setVerticalSpacing(int spacing);

逐词逐句底层解析:

  • void:无返回值;
  • QGridLayout:::成员函数;
  • setVerticalSpacing():函数名,"设置垂直间距" 的意思;
  • int spacing:入参,要设置的垂直间距数值,单位是像素。

参数说明:

  • spacing:要设置的垂直间距,int 类型;
    • 单位是像素;
    • 可以是 0(上下相邻行紧贴在一起);
    • 不建议是负数(可能导致上下相邻行的控件重叠);
    • 推荐值:5-20 像素,根据界面风格调整。
2.6.3 使用示例
复制代码
#include <QGridLayout>
#include <QPushButton>
#include <QWidget>
#include <QDebug>

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:设置行与行之间的垂直间距
QGridLayout* layout = new QGridLayout();

// 添加三个按钮到 0 行 0 列、1 行 0 列、2 行 0 列
layout->addWidget(new QPushButton("行0"), 0, 0);
layout->addWidget(new QPushButton("行1"), 1, 0); // 与行0的垂直间距默认
layout->addWidget(new QPushButton("行2"), 2, 0); // 与行1的垂直间距默认

// 【关键!】设置所有上下相邻行之间的垂直间距为 20 像素
layout->setVerticalSpacing(20);

// 获取当前垂直间距并打印
int currentVSpacing = layout->verticalSpacing();
qDebug() << "当前行与行之间的垂直间距:" << currentVSpacing << "像素"; // 输出:20

this->setLayout(layout);
2.6.4 关键注意事项(必知!)

和 layoutHorizontalSpacing 的注意事项几乎一样,我再简单重复一遍,加深记忆:

  1. 全局生效!(超级重要!) :
    • setVerticalSpacing() 是针对布局内所有上下相邻行的!
    • 无法单独设置某两行的垂直间距;
  2. 独立于水平间距!(超级重要!) :
    • 垂直间距和水平间距是分开设置的,互不影响;
  3. 单位是像素!;
  4. 不建议设为负数!;
  5. 默认值由系统样式决定!;
  6. 推荐值!(经验之谈) :
    • 通常情况下,垂直间距设为 5-20 像素比较合适;
    • 可以和水平间距一样,也可以不一样,根据实际情况调整。

2.7 属性七:layoutRowStretch------ 行方向的拉伸系数

2.7.1 属性的核心定义

layoutRowStretch 是 QGridLayout 用于控制窗口缩放时,不同行的高度分配比例的样式属性 ------ 它的核心作用是告诉布局管理器:"窗口变高时,额外的垂直空间按什么比例分给不同的行"。

通俗理解:layoutRowStretch 就像 "分蛋糕"------ 蛋糕就是 "窗口变高时多出来的垂直空间",不同的行就是 "分蛋糕的人",拉伸系数就是 "每个人分蛋糕的比例":

  • 系数为 0:这个人不要蛋糕(行高度固定,不参与拉伸);
  • 系数为 1:这个人分 1 份蛋糕;
  • 系数为 3:这个人分 3 份蛋糕(是系数 1 的人的 3 倍)。

这里有几个超级重要的规则,必须牢记,刻在脑子里:

  1. 系数为 0 表示固定高度:行的拉伸系数为 0 时,该行高度固定,不管窗口怎么变,高度都不变;
  2. 系数比例决定高度分配 :系数越大,行分配到的额外空间越多,重点看比例,不是绝对值(比如 1:3 和 2:6 效果一样);
  3. 效果前提!(超级重要!说三遍!) :
    • 仅仅设置行拉伸系数是不够的!
    • 必须把控件的 ** 垂直 QSizePolicy(尺寸策略)** 设为 QSizePolicy::Expanding(或其他可扩张的策略)!
    • 否则控件高度固定,即使设了行拉伸系数,也看不到行变高的效果!
    • 这是 90% 的新手都会踩的坑!后面我会单独用一章讲 QSizePolicy!
2.7.2 关联 API 详解(逐词逐句,零模糊)

通过一个成员函数设置(获取的 API 不常用,重点讲设置):

设置指定行的拉伸系数:void setRowStretch (int row, int stretch)

函数原型:

复制代码
void QGridLayout::setRowStretch(int row, int stretch);

逐词逐句底层解析:

  • void:无返回值;
  • QGridLayout:::成员函数;
  • setRowStretch():函数名,"设置行拉伸系数" 的意思,"Row" 是 "行","Stretch" 是 "拉伸";
  • int row:入参,要设置的行索引(从 0 开始!);
  • int stretch:入参,该行的拉伸系数(≥0)。

参数说明:

  • row:要设置的行索引,int 类型;
    • 从 0 开始!第 1 行对应 row=0,第 2 行对应 row=1;
  • stretch:该行的拉伸系数,int 类型;
    • ≥0;
    • 0:该行高度固定,不参与拉伸;
    • >0:该行按系数比例分配额外的垂直空间。
2.7.3 使用示例(注意:仅作演示,必须配合 QSizePolicy 才有效!)
复制代码
#include <QGridLayout>
#include <QPushButton>
#include <QWidget>
#include <QSizePolicy> // 必须包含这个头文件!

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:设置行拉伸系数(⚠️ 必须配合 QSizePolicy 才有效!)
QGridLayout* layout = new QGridLayout();

// 创建三个按钮
QPushButton* btn0 = new QPushButton("行0(系数1)");
QPushButton* btn1 = new QPushButton("行1(系数0,固定)");
QPushButton* btn2 = new QPushButton("行2(系数3)");

// ⚠️ 关键避坑点:必须设置按钮的垂直 QSizePolicy 为 Expanding!
// 否则按钮高度固定,即使设了行拉伸系数,也看不到效果!
QSizePolicy policy = btn0->sizePolicy();
policy.setVerticalPolicy(QSizePolicy::Expanding); // 允许垂直扩张
btn0->setSizePolicy(policy);
btn1->setSizePolicy(policy);
btn2->setSizePolicy(policy);

// 添加按钮到 0 行 0 列、1 行 0 列、2 行 0 列
layout->addWidget(btn0, 0, 0);
layout->addWidget(btn1, 1, 0);
layout->addWidget(btn2, 2, 0);

// 【关键!】设置行拉伸系数
layout->setRowStretch(0, 1); // 行0:系数1(窗口变高时,分1份额外空间)
layout->setRowStretch(1, 0); // 行1:系数0(固定高度,不分额外空间)
layout->setRowStretch(2, 3); // 行2:系数3(窗口变高时,分3份额外空间,是行0的3倍)

// 设置间距和边距
layout->setVerticalSpacing(10);
layout->setContentsMargins(20, 20, 20, 20);

this->setLayout(layout);
2.7.4 关键注意事项(必知!90% 新手栽在这里!)
  1. 必须配合 QSizePolicy!(超级重要!说三遍!) :
    • 这是 QGridLayout 最容易踩的坑,没有之一!
    • 仅仅设置 setRowStretch() 是完全不够的!
    • 按钮、标签等控件默认 "垂直高度固定"(QSizePolicy 为 Preferred 或 Fixed);
    • 即使你设了行拉伸系数,控件高度不变,你也看不到行变高的效果!
    • 必须把控件的垂直 QSizePolicy 设为 QSizePolicy::Expanding(或其他可扩张的策略)!
    • 后面我会单独用一章详细讲 QSizePolicy,这里先记住这个结论!
  2. 系数为 0 表示固定高度!(超级重要!) :
    • 行的拉伸系数为 0 时,该行高度固定;
    • 不管窗口怎么变高,该行的高度都不变;
    • 非常适合用来放 "固定高度的控件",比如标题、按钮栏等;
  3. 系数比例决定高度分配!(超级重要!) :
    • 重点看比例,不是绝对值!
    • 比如行 0 系数 1,行 2 系数 3 → 1:3 分配;
    • 行 0 系数 2,行 2 系数 6 → 2:6 分配,和 1:3 效果完全一样!
  4. 所有系数为 0!(超级重要!) :
    • 如果所有行的拉伸系数都是 0;
    • 窗口变高时,所有行高度都不变;
    • 控件会居中显示,不会变大;
  5. 行索引从 0 开始!(超级重要!) :
    • 第 1 行对应 row=0,不是 row=1!
    • 千万不要搞反!

2.8 属性八:layoutColumnStretch------ 列方向的拉伸系数

2.8.1 属性的核心定义

layoutColumnStretch 是 QGridLayout 用于控制窗口缩放时,不同列的宽度分配比例 的样式属性 ------ 它和 layoutRowStretch 是一对 "双胞胎",唯一的区别是:layoutRowStretch 控制 "行的高度分配",layoutColumnStretch 控制 "列的宽度分配"。

它的核心作用是告诉布局管理器:"窗口变宽时,额外的水平空间按什么比例分给不同的列"。

通俗理解:layoutColumnStretch 也是 "分蛋糕"------ 只不过蛋糕是 "窗口变宽时多出来的水平空间",不同的列是 "分蛋糕的人",拉伸系数是 "分蛋糕的比例"。

这里有几个超级重要的规则,必须牢记:

  1. 系数为 0 表示固定宽度:列的拉伸系数为 0 时,该列宽度固定,不管窗口怎么变,宽度都不变;
  2. 系数比例决定宽度分配 :系数越大,列分配到的额外空间越多,重点看比例,不是绝对值;
  3. 效果前提!(比行拉伸友好一点) :
    • 列拉伸通常不需要额外设置 QSizePolicy!
    • 因为大多数控件默认 "水平方向可扩张"(比如 QPushButton、QLineEdit 等);
    • 所以设置列拉伸系数后,通常直接就能看到效果!
2.8.2 关联 API 详解(逐词逐句,零模糊)

通过一个成员函数设置:

设置指定列的拉伸系数:void setColumnStretch (int column, int stretch)

函数原型:

复制代码
void QGridLayout::setColumnStretch(int column, int stretch);

逐词逐句底层解析:

  • void:无返回值;
  • QGridLayout:::成员函数;
  • setColumnStretch():函数名,"设置列拉伸系数" 的意思,"Column" 是 "列";
  • int column:入参,要设置的列索引(从 0 开始!);
  • int stretch:入参,该列的拉伸系数(≥0)。

参数说明:

  • column:要设置的列索引,int 类型;
    • 从 0 开始!第 1 列对应 column=0,第 2 列对应 column=1;
  • stretch:该列的拉伸系数,int 类型;
    • ≥0;
    • 0:该列宽度固定,不参与拉伸;
    • >0:该列按系数比例分配额外的水平空间。
2.8.3 使用示例
复制代码
#include <QGridLayout>
#include <QPushButton>
#include <QWidget>
#include <QDebug>

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:设置列拉伸系数(通常直接有效,无需额外设置 QSizePolicy)
QGridLayout* layout = new QGridLayout();

// 创建三个按钮
QPushButton* btn0 = new QPushButton("列0(系数1)");
QPushButton* btn1 = new QPushButton("列1(系数0,固定)");
QPushButton* btn2 = new QPushButton("列2(系数3)");

// 添加按钮到 0 行 0 列、0 行 1 列、0 行 2 列
layout->addWidget(btn0, 0, 0);
layout->addWidget(btn1, 0, 1);
layout->addWidget(btn2, 0, 2);

// 【关键!】设置列拉伸系数
layout->setColumnStretch(0, 1); // 列0:系数1(窗口变宽时,分1份额外空间)
layout->setColumnStretch(1, 0); // 列1:系数0(固定宽度,不分额外空间)
layout->setColumnStretch(2, 3); // 列2:系数3(窗口变宽时,分3份额外空间,是列0的3倍)

// 设置间距和边距
layout->setHorizontalSpacing(10);
layout->setContentsMargins(20, 20, 20, 20);

this->setLayout(layout);
2.8.4 关键注意事项(必知!)
  1. 系数为 0 表示固定宽度!(超级重要!) :
    • 列的拉伸系数为 0 时,该列宽度固定;
    • 不管窗口怎么变宽,该列的宽度都不变;
    • 非常适合用来放 "固定宽度的控件",比如标签、图标等;
  2. 系数比例决定宽度分配!(超级重要!) :
    • 重点看比例,不是绝对值!
    • 比如列 0 系数 1,列 2 系数 3 → 1:3 分配;
    • 列 0 系数 2,列 2 系数 6 → 2:6 分配,和 1:3 效果完全一样!
  3. 通常无需额外设置 QSizePolicy!(超级重要!) :
    • 这点比行拉伸友好很多!
    • 大多数控件(比如 QPushButton、QLineEdit、QTextEdit 等)默认 "水平方向可扩张";
    • 所以设置列拉伸系数后,通常直接就能看到列变宽的效果!
    • 不需要像行拉伸那样额外设置 QSizePolicy!
  4. 所有系数为 0!(超级重要!) :
    • 如果所有列的拉伸系数都是 0;
    • 窗口变宽时,所有列宽度都不变;
    • 控件会居中显示,不会变大;
  5. 列索引从 0 开始!(超级重要!) :
    • 第 1 列对应 column=0,不是 column=1!
    • 千万不要搞反!

2.9 【推荐】批量设置四边距:setContentsMargins ()

讲完了单独设置四侧边距的 API,我们来讲一个超级推荐、日常开发最常用 的方法:setContentsMargins()------ 它可以一次性批量设置布局的左、上、右、下四周边距,避免单独设置导致的样式不一致,非常方便!

这个方法和 QVBoxLayout、QHBoxLayout 里的 setContentsMargins() 完全一样,我再简单讲一遍,加深记忆。

2.9.1 函数原型(逐词逐句,零模糊)
复制代码
void QGridLayout::setContentsMargins(int left, int top, int right, int bottom);

逐词逐句底层解析:

  • void:无返回值;
  • QGridLayout:::成员函数;
  • setContentsMargins():函数名,"设置内容边距" 的意思,"Contents" 指的是布局内的所有内容(控件 + 嵌套布局);
  • int left:入参,左侧边距,单位是像素;
  • int top:入参,上方边距,单位是像素;
  • int right:入参,右侧边距,单位是像素;
  • int bottom:入参,下方边距,单位是像素。
2.9.2 参数说明
  • left:左侧边距,int 类型,单位是像素;
  • top:上方边距,int 类型,单位是像素;
  • right:右侧边距,int 类型,单位是像素;
  • bottom:下方边距,int 类型,单位是像素;
  • 所有参数都可以是 0(紧贴对应边界),不建议是负数。
2.9.3 使用示例
复制代码
#include <QGridLayout>
#include <QPushButton>
#include <QWidget>
#include <QDebug>

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:【推荐】批量设置四边距
QGridLayout* layout = new QGridLayout();
layout->addWidget(new QPushButton("按钮1"), 0, 0);
layout->addWidget(new QPushButton("按钮2"), 0, 1);
layout->addWidget(new QPushButton("按钮3"), 1, 0);
layout->addWidget(new QPushButton("按钮4"), 1, 1);

// 【超级推荐!】批量设置四边距:左 20px,上 10px,右 20px,下 10px
// 左右对称,上下对称,视觉平衡
layout->setContentsMargins(20, 10, 20, 10);

// 同时设置水平和垂直间距
layout->setHorizontalSpacing(15);
layout->setVerticalSpacing(10);

this->setLayout(layout);
2.9.4 关键注意事项(必知!)
  1. 优先使用批量设置!(超级重要!说三遍!) :
    • 日常开发中,99% 的情况下我们都应该用 setContentsMargins() 批量设置四边距;
    • 不要单独调用 setLeftMargin()、setTopMargin() 等;
    • 批量设置可以保证界面视觉平衡,避免一边宽一边窄;
  2. 建议对称设置!(经验之谈) :
    • 通常情况下,建议左右边距相等,上下边距相等;
    • 比如左 20px、右 20px,上 10px、下 10px;
    • 这样界面看起来更整齐、更平衡;
  3. 单位是像素!;
  4. 不建议设为负数!。

示例代码:

复制代码
#include "widget.h"
#include "ui_widget.h"

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    //OK大家,接下来我们来学习QGridLayout,这个布局管理器其实是比较简单的
    //因为它其实就是相当于一个二维数组,即把QH~QV这两个结合起来了而言
    //我们可以通过指定行数和列数(注意从0开始计数哦~),去再将控件加入到该管理器中指定的位置~~~

    /**
     * @class QGridLayout
     * @brief Qt中网格布局管理器,支持将子控件按M×N的网格形式排列(行+列二维布局)
     * @details QGridLayout是比QVBoxLayout/QHBoxLayout更灵活的线性布局扩展,核心优势:
     *          1. 支持控件精准定位到指定行/列,突破单一方向排列的限制;
     *          2. 可独立设置水平/垂直方向的间距,以及行/列的拉伸系数,精细化控制控件尺寸比例;
     *          3. 兼容垂直/水平布局的效果(所有控件放同一行=QHBoxLayout,同一列=QVBoxLayout);
     *          布局自动适配窗口缩放,无需手动计算控件坐标/尺寸。
     *
     * 【核心优势对比】
     * | 布局类型       | 排列方式       | 灵活性               | 适用场景               |
     * |----------------|----------------|----------------------|------------------------|
     * | QVBoxLayout    | 单一垂直方向   | 低                   | 单列控件排列           |
     * | QHBoxLayout    | 单一水平方向   | 低                   | 单行控件排列           |
     * | QGridLayout    | 二维网格(行+列)| 高                   | 复杂多行多列控件排列   |
     */

    // ============================== 核心属性详解 ==============================

    /**
     * @property QGridLayout::layoutLeftMargin
     * @brief 布局管理器左侧与父Widget边缘的内边距(控制网格最左列与窗口左边界的距离)
     * @关联API:int leftMargin() const / void setLeftMargin(int margin)
     */

    /**
     * @property QGridLayout::layoutRightMargin
     * @brief 布局管理器右侧与父Widget边缘的内边距(控制网格最右列与窗口右边界的距离)
     * @关联API:int rightMargin() const / void setRightMargin(int margin)
     */

    /**
     * @property QGridLayout::layoutTopMargin
     * @brief 布局管理器上方与父Widget边缘的内边距(控制网格最上行与窗口上边界的距离)
     * @关联API:int topMargin() const / void setTopMargin(int margin)
     */

    /**
     * @property QGridLayout::layoutBottomMargin
     * @brief 布局管理器下方与父Widget边缘的内边距(控制网格最下行与窗口下边界的距离)
     * @关联API:int bottomMargin() const / void setBottomMargin(int margin)
     */

    /**
     * @property QGridLayout::layoutHorizontalSpacing
     * @brief 网格中**列与列之间**的水平间距(相邻列控件的水平距离)
     * @details 区别于QVBoxLayout/QHBoxLayout的单一spacing,QGridLayout可独立控制水平/垂直间距
     * @关联API:int horizontalSpacing() const / void setHorizontalSpacing(int spacing)
     */

    /**
     * @property QGridLayout::layoutVerticalSpacing
     * @brief 网格中**行与行之间**的垂直间距(相邻行控件的垂直距离)
     * @关联API:int verticalSpacing() const / void setVerticalSpacing(int spacing)
     */

    /**
     * @property QGridLayout::layoutRowStretch
     * @brief 行方向的拉伸系数(控制窗口缩放时,不同行的高度分配比例)
     * @details 系数为0表示行高度固定(不参与拉伸),系数越大,行分配到的空间越多
     * @关联API:void setRowStretch(int row, int stretch)
     */

    /**
     * @property QGridLayout::layoutColumnStretch
     * @brief 列方向的拉伸系数(控制窗口缩放时,不同列的宽度分配比例)
     * @details 系数为0表示列宽度固定,系数越大,列分配到的空间越多(核心用于控制列宽比例)
     * @关联API:void setColumnStretch(int column, int stretch)
     */

    // ============================== 核心方法详解 ==============================

    /**
     * @fn void QGridLayout::addWidget(QWidget *w, int row, int column, int rowSpan = 1, int columnSpan = 1)
     * @brief 【核心】将控件添加到网格的指定行/列(支持跨行列)
     * @details 网格的行/列索引从0开始,是QGridLayout最核心的布局方法。
     * @参数 w - 要添加的QWidget子类对象(按钮、标签等)
     * @参数 row - 目标行索引(0开始)
     * @参数 column - 目标列索引(0开始)
     * @参数 rowSpan - 跨行数(默认1,即仅占1行)
     * @参数 columnSpan - 跨列数(默认1,即仅占1列)
     * @示例:layout->addWidget(btn1, 0, 0); // 按钮1放在第0行第0列
     * @关键注意:
     * 1. 稀疏行列不占位:若设置的行/列索引远大于现有行列(如第10行),但中间无元素,控件会紧挨上一个元素,不会留空白;
     * 2. 跨行列:可通过rowSpan/columnSpan实现控件占多行/多列(如layout->addWidget(btn, 0, 0, 2, 3)表示占2行3列)。
     */

    /**
     * @fn void QGridLayout::setColumnStretch(int column, int stretch)
     * @brief 【列宽控制】设置指定列的拉伸系数,控制窗口缩放时的列宽比例
     * @参数 column - 列索引(0开始)
     * @参数 stretch - 拉伸系数(0=固定宽度,>0=按比例分配空间)
     * @示例:
     * layout->setColumnStretch(0, 1);  // 第0列拉伸系数1
     * layout->setColumnStretch(2, 3);  // 第2列拉伸系数3 → 宽度是第0列的3倍
     * @关键:系数比例决定宽度分配,与系数绝对值无关(如1:3和2:6效果一致)。
     */

    /**
     * @fn void QGridLayout::setRowStretch(int row, int stretch)
     * @brief 【行高控制】设置指定行的拉伸系数,控制窗口缩放时的行高比例
     * @参数 row - 行索引(0开始)
     * @参数 stretch - 拉伸系数(0=固定高度,>0=按比例分配空间)
     * @关键注意:
     * 1. 效果前提:需将控件的垂直sizePolicy设为QSizePolicy::Expanding(否则控件高度固定,拉伸无效果);
     * 2. 示例:btn->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
     */

    /**
     * @fn void QGridLayout::setHorizontalSpacing(int spacing)
     * @brief 设置列与列之间的水平间距(像素)
     * @示例:layout->setHorizontalSpacing(15); // 列间距15px
     */

    /**
     * @fn void QGridLayout::setVerticalSpacing(int spacing)
     * @brief 设置行与行之间的垂直间距(像素)
     * @示例:layout->setVerticalSpacing(10); // 行间距10px
     */

    /**
     * @fn void QGridLayout::setContentsMargins(int left, int top, int right, int bottom)
     * @brief 批量设置布局与父Widget的四周边距(替代单独设置单侧边距)
     * @示例:layout->setContentsMargins(20, 10, 20, 10); // 左右20px,上下10px
     */

    // ============================== 核心代码示例解析 ==============================

    /**
     * @brief 基础用法1:2×2网格布局(核心演示行/列定位)
     */
    /*
    Widget::Widget(QWidget *parent)
        : QWidget(parent)
        , ui(new Ui::Widget)
    {
        ui->setupUi(this);

        // 1. 创建控件
        QPushButton* btn1 = new QPushButton("按钮1");
        QPushButton* btn2 = new QPushButton("按钮2");
        QPushButton* btn3 = new QPushButton("按钮3");
        QPushButton* btn4 = new QPushButton("按钮4");

        // 2. 创建网格布局
        QGridLayout* layout = new QGridLayout();
        // 3. 控件定位到指定行/列(0行0列、0行1列、1行0列、1行1列)
        layout->addWidget(btn1, 0, 0);
        layout->addWidget(btn2, 0, 1);
        layout->addWidget(btn3, 1, 0);
        layout->addWidget(btn4, 1, 1);

        // 4. 设置为窗口顶层布局
        this->setLayout(layout);
    }
    */
    /**
     * @brief 基础用法1解析
     * 效果:4个按钮按2行2列排列,窗口缩放时,按钮尺寸均匀适配;
     * 核心:行/列索引从0开始,addWidget的后两个参数是核心定位依据。
     */

    /**
     * @brief 基础用法2:模拟QHBoxLayout(所有控件放同一行)
     */
    /*
    QGridLayout* layout = new QGridLayout();
    layout->addWidget(btn1, 0, 0);
    layout->addWidget(btn2, 0, 1);
    layout->addWidget(btn3, 0, 2);
    layout->addWidget(btn4, 0, 3); // 所有控件放第0行,不同列 → 等效水平布局
    */

    /**
     * @brief 基础用法3:模拟QVBoxLayout(所有控件放同一列)
     */
    /*
    QGridLayout* layout = new QGridLayout();
    layout->addWidget(btn1, 1, 0);
    layout->addWidget(btn2, 2, 0);
    layout->addWidget(btn3, 3, 0);
    layout->addWidget(btn4, 4, 0); // 所有控件放第0列,不同行 → 等效垂直布局
    */

    /**
     * @brief 基础用法4:稀疏行列(大索引不占位)
     */
    /*
    QGridLayout* layout = new QGridLayout();
    layout->addWidget(btn1, 0, 0);
    layout->addWidget(btn2, 1, 0);
    layout->addWidget(btn3, 2, 0);
    layout->addWidget(btn4, 10, 0); // 第10行无中间元素 → btn4紧挨btn3下方,无空白
    */

    /**
     * @brief 进阶用法:设置列拉伸系数(控制列宽比例)
     */
    /*
    Widget::Widget(QWidget *parent)
        : QWidget(parent)
        , ui(new Ui::Widget)
    {
        ui->setupUi(this);

        // 1. 创建6个按钮(2行3列)
        QPushButton* btn1 = new QPushButton("按钮1");
        QPushButton* btn2 = new QPushButton("按钮2");
        QPushButton* btn3 = new QPushButton("按钮3");
        QPushButton* btn4 = new QPushButton("按钮4");
        QPushButton* btn5 = new QPushButton("按钮5");
        QPushButton* btn6 = new QPushButton("按钮6");

        // 2. 创建网格布局并添加控件
        QGridLayout* layout = new QGridLayout();
        layout->addWidget(btn1, 0, 0);
        layout->addWidget(btn2, 0, 1);
        layout->addWidget(btn3, 0, 2);
        layout->addWidget(btn4, 1, 0);
        layout->addWidget(btn5, 1, 1);
        layout->addWidget(btn6, 1, 2);

        // 3. 设置列拉伸系数(核心)
        layout->setColumnStretch(0, 1);  // 第0列:拉伸系数1(自适应宽度)
        layout->setColumnStretch(1, 0);  // 第1列:系数0(固定宽度)
        layout->setColumnStretch(2, 3);  // 第2列:系数3(宽度是第0列的3倍)

        this->setLayout(layout);
    }
    */
    /**
     * @brief 进阶用法解析
     * 效果:窗口缩放时,第0列宽度:第2列宽度=1:3,第1列宽度固定;
     * 行拉伸注意:若要设置行高比例,需先设置按钮的sizePolicy:
     * btn1->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
     * 再调用layout->setRowStretch(0, 2); layout->setRowStretch(1, 1);
     */

    // ============================== 核心总结 ==============================
    /**
     * @brief QGridLayout关键要点回顾
     * 1. 核心定位:二维网格布局,通过addWidget(row, column)精准定位控件,兼容水平/垂直布局效果;
     * 2. 间距控制:独立设置horizontalSpacing(列间距)和verticalSpacing(行间距),精细化布局;
     * 3. 拉伸系数:setColumnStretch/setRowStretch控制行列尺寸比例,行拉伸需配合控件sizePolicy;
     * 4. 稀疏行列:大索引行列无中间元素时,控件不会留空白,紧挨上一个元素;
     * 5. 灵活性:支持跨行列布局(rowSpan/columnSpan),是复杂界面布局的首选。
     */

}

Widget::~Widget()
{
    delete ui;
}

第三章 QGridLayout 核心方法详解

讲完了所有核心属性,我们接下来讲 QGridLayout 的核心方法------ 这些方法是日常开发最常用的,覆盖 "精准定位控件、合并单元格、嵌套布局、设置拉伸因子、调整间距边距" 五大核心需求。

按照最常用的顺序,我们讲:addWidget(基础定位与跨行列)、addLayout(嵌套布局)、setColumnStretch/setRowStretch(拉伸因子,刚才讲属性的时候已经提过了,这里再结合方法讲一遍,加深记忆)、setSpacing/setContentsMargins(间距边距)。


3.1 方法一:addWidget (QWidget *w, int row, int column)------ 【基础定位】把控件放到指定单元格

3.1.1 函数原型(逐词逐句,零模糊)
复制代码
void QGridLayout::addWidget(QWidget *w, int row, int column);

逐词逐句底层解析:

  • void:无返回值;
  • QGridLayout:::成员函数;
  • addWidget():函数名,"添加控件" 的意思,非常直观;
  • QWidget *w:入参,要添加的 QWidget 子类对象的指针;
    • QWidget *:指针类型,指向一个 QWidget 对象;
    • w:参数名,代表要添加的控件;
  • int row:入参,目标行索引(从 0 开始!);
  • int column:入参,目标列索引(从 0 开始!)。
3.1.2 参数说明(新手重点看!)
  • w:要添加的控件,QWidget* 类型;
    • 可以是任何 QWidget 的子类,比如 QPushButton、QLabel、QLineEdit、QComboBox 等等;
    • 必须是指针类型,不能是对象本身;
    • 不需要手动设置父对象(添加到布局后,布局会自动设置);
  • row:目标行索引,int 类型;
    • 从 0 开始!从 0 开始!从 0 开始!重要的事说三遍!;
    • 第 1 行对应 row=0,第 2 行对应 row=1,以此类推;
  • column:目标列索引,int 类型;
    • 从 0 开始!从 0 开始!从 0 开始!重要的事说三遍!;
    • 第 1 列对应 column=0,第 2 列对应 column=1,以此类推。
3.1.3 返回值说明
  • 无返回值(void)。
3.1.4 核心作用(通俗理解,必知!)

这个方法是 QGridLayout 最基础、最常用的方法 ------ 它的作用是把控件精准地放到网格的 "指定单元格" 里,就像在 Excel 里把内容填到 "第 N 行第 M 列" 一样。

控件默认占 1 行 1 列(即一个单元格),无需手动计算控件的 x/y 坐标和宽高,布局会自动分配空间,窗口缩放时控件也会跟着自适应。

通俗理解:addWidget(w, row, column) 就像 "在 Excel 表格的第 (row+1) 行第 (column+1) 列单元格里填内容"------row=0 就是第 1 行,column=0 就是第 1 列。

3.1.5 使用示例(一看就懂)
复制代码
#include <QGridLayout>
#include <QPushButton>
#include <QLabel>
#include <QLineEdit>
#include <QWidget>

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:【基础定位】2×2 网格布局(核心演示行/列定位)
QGridLayout* layout = new QGridLayout();

// 1. 创建控件
QLabel* nameLabel = new QLabel("姓名:");
QLineEdit* nameEdit = new QLineEdit();
QLabel* emailLabel = new QLabel("邮箱:");
QLineEdit* emailEdit = new QLineEdit();

// 2. 【核心!】控件定位到指定行/列(索引从 0 开始!)
layout->addWidget(nameLabel,  0, 0); // 姓名标签 → 第 1 行第 1 列(0行0列)
layout->addWidget(nameEdit,   0, 1); // 姓名输入框 → 第 1 行第 2 列(0行1列)
layout->addWidget(emailLabel, 1, 0); // 邮箱标签 → 第 2 行第 1 列(1行0列)
layout->addWidget(emailEdit,  1, 1); // 邮箱输入框 → 第 2 行第 2 列(1行1列)

// 3. 设置列拉伸系数(让输入框列占更多空间)
layout->setColumnStretch(0, 0); // 标签列:固定宽度
layout->setColumnStretch(1, 1); // 输入框列:自适应宽度

// 4. 设置间距和边距
layout->setHorizontalSpacing(10);
layout->setVerticalSpacing(15);
layout->setContentsMargins(30, 30, 30, 30);

// 5. 将布局设置给窗口
this->setLayout(layout);
3.1.6 新手避坑点(必看!)
  1. 索引从 0 开始!(超级重要!说三遍!) :
    • 这是 QGridLayout 最最最容易踩的坑,没有之一!
    • 如果你写成 addWidget(btn, 1, 1),按钮会出现在 "第 2 行第 2 列",不是第 1 行第 1 列!
    • 千万千万千万不要搞反!
    • 建议在写代码之前,先在纸上画一个 Excel 表格草稿,标好每个控件的行 / 列索引(从 0 开始),再写代码!
  2. 稀疏行列不占位!(超级重要!说三遍!) :
    • 如果你把控件设到 row=10, column=0,但 0-9 行没有任何控件;
    • 按钮不会跑到第 11 行(row=10)!
    • 而是会紧挨上一个控件(比如 0 行 0 列的按钮下方)!
    • 中间的 1-9 行(row=1 到 row=9)因为没有元素,不会留任何空白!
    • 这点和 Excel 表格不一样,Excel 表格空行是空的,但 QGridLayout 空行不占位!
  3. 自动适配空间!(超级重要!) :
    • 控件添加到布局后,不需要手动设置 geometry() 或 resize();
    • 布局会自动为控件分配位置和尺寸;
    • 窗口缩放时,控件尺寸也会自动调整(如果设置了拉伸因子);
  4. 必须是指针类型!(超级重要!) :
    • addWidget() 的参数必须是 QWidget*(指针);
    • 不能是 QWidget(对象本身);
    • 推荐先创建指针变量,再 addWidget()。

3.2 方法二:addWidget (QWidget *w, int row, int column, int rowSpan, int columnSpan)------ 【合并单元格】把控件放到指定位置并跨行列

3.2.1 函数原型(逐词逐句,零模糊)
复制代码
void QGridLayout::addWidget(QWidget *w, int row, int column, int rowSpan, int columnSpan);

逐词逐句底层解析:

  • void:无返回值;
  • QGridLayout:::成员函数;
  • addWidget():函数名,"添加控件" 的意思;
  • QWidget *w:入参,要添加的控件指针;
  • int row:入参,起始行索引(控件左上角所在的行,从 0 开始!);
  • int column:入参,起始列索引(控件左上角所在的列,从 0 开始!);
  • int rowSpan:入参,跨行数(控件要占几行,默认 1);
  • int columnSpan:入参,跨列数(控件要占几列,默认 1)。
3.2.2 参数说明(通俗解释,新手重点看!)
  • w:要添加的控件,QWidget* 类型(和基础版一样);
  • row:起始行索引 ,int 类型;
    • 控件 "左上角" 所在的行;
    • 从 0 开始!;
  • column:起始列索引 ,int 类型;
    • 控件 "左上角" 所在的列;
    • 从 0 开始!;
  • rowSpan:跨行数 ,int 类型;
    • 控件要往下占几行;
    • 默认是 1(仅占 1 行,不跨行);
    • 必须 ≥1(不能设 0,设 0 会无效);
  • columnSpan:跨列数 ,int 类型;
    • 控件要往右占几列;
    • 默认是 1(仅占 1 列,不跨列);
    • 必须 ≥1(不能设 0,设 0 会无效)。
3.2.3 返回值说明
  • 无返回值(void)。
3.2.4 核心作用(通俗理解,必知!)

这个方法是 QGridLayout 非常实用的进阶方法 ------ 它的作用是把控件放到指定位置,并让它 "合并单元格",占多行多列,就像在 Excel 里选中几个单元格,点击 "合并单元格" 一样。

通俗理解:addWidget(w, row, col, rowSpan, colSpan) 就像 "在 Excel 表格里,从第 (row+1) 行第 (col+1) 列开始,选中往下 rowSpan 行、往右 colSpan 列的单元格,合并成一个大单元格,然后把内容填进去"。

3.2.5 使用示例(场景化理解,一看就懂)
复制代码
#include <QGridLayout>
#include <QLabel>
#include <QLineEdit>
#include <QTextEdit>
#include <QPushButton>
#include <QWidget>

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:【合并单元格】标题跨2列,备注跨2行
QGridLayout* layout = new QGridLayout();

// --- 场景1:标题标签横跨2列(占0行0列到0行1列,合并2列) ---
QLabel* titleLabel = new QLabel("📝 用户信息登记表");
titleLabel->setAlignment(Qt::AlignCenter);
// 核心方法:起始行0,起始列0,跨1行,跨2列
layout->addWidget(titleLabel, 0, 0, 1, 2);

// --- 场景2:姓名标签和输入框(各占1行1列) ---
layout->addWidget(new QLabel("姓名:"), 1, 0);
layout->addWidget(new QLineEdit(), 1, 1);

// --- 场景3:备注标签和文本框(文本框竖跨2行,占2行1列到3行1列,合并2行) ---
QLabel* noteLabel = new QLabel("备注:");
noteLabel->setAlignment(Qt::AlignTop); // 文字靠上
layout->addWidget(noteLabel, 2, 0);

QTextEdit* noteEdit = new QTextEdit();
noteEdit->setPlaceholderText("请输入详细备注...");
// 核心方法:起始行2,起始列1,跨2行,跨1列
layout->addWidget(noteEdit, 2, 1, 2, 1);

// --- 场景4:提交按钮(占3行0列,因为备注跨了2行,所以下一行是3行) ---
layout->addWidget(new QPushButton("提交"), 3, 0);

// 设置拉伸因子
layout->setColumnStretch(1, 1); // 输入框列自适应宽度
layout->setRowStretch(2, 1);    // 备注行自适应高度

// 设置间距和边距
layout->setHorizontalSpacing(10);
layout->setVerticalSpacing(15);
layout->setContentsMargins(30, 30, 30, 30);

this->setLayout(layout);
3.2.6 新手避坑点(必看!)
  1. 合并范围不能重叠!(超级重要!说三遍!) :
    • 如果一个控件占了 0 行 0 列到 0 行 1 列(跨 2 列);
    • 就不能再往这两个单元格(0 行 0 列、0 行 1 列)放其他控件!
    • 否则布局会混乱,控件可能会重叠或显示异常!
  2. 跨行列数≥1!(超级重要!) :
    • rowSpan 和 columnSpan 最小是 1!
    • 不能设 0!设 0 会无效!
    • 默认就是 1,所以如果不跨行不跨列,用基础版的 addWidget(w, row, column) 就行;
  3. 跨行列后仍自适应!(超级重要!) :
    • 合并后的控件会占满所有合并单元格的空间;
    • 窗口缩放时,合并区域整体变大 / 变小;
    • 如果设置了行 / 列拉伸因子,合并区域也会按比例拉伸;
  4. 起始行列是左上角!(超级重要!) :
    • row 和 column 是控件 "左上角" 所在的行和列!
    • 不是中间,也不是右下角!
    • 这点一定要搞清楚!

3.3 方法三:addLayout (QLayout *l, int row, int column) /addLayout (QLayout *l, int row, int column, int rowSpan, int columnSpan)------ 【嵌套布局】在网格的单元格里嵌入另一个布局

3.3.1 函数原型(逐词逐句,零模糊)

QGridLayout 提供了两个版本的 addLayout,一个是基础版(不跨行列),一个是进阶版(跨行列):

复制代码
// 基础版:不跨行列,占1行1列
void QGridLayout::addLayout(QLayout *l, int row, int column);

// 进阶版:跨行列,占 rowSpan 行 columnSpan 列
void QGridLayout::addLayout(QLayout *l, int row, int column, int rowSpan, int columnSpan);

逐词逐句底层解析(以进阶版为例):

  • void:无返回值;
  • QGridLayout:::成员函数;
  • addLayout():函数名,"添加布局" 的意思;
  • QLayout *l:入参,要嵌套的布局对象的指针;
    • QLayout *:指针类型,指向一个 QLayout 对象(可以是 QVBoxLayout、QHBoxLayout、QGridLayout 等);
    • l:参数名,代表要嵌套的布局;
  • int row:入参,起始行索引(从 0 开始!);
  • int column:入参,起始列索引(从 0 开始!);
  • int rowSpan:入参,跨行数(默认 1);
  • int columnSpan:入参,跨列数(默认 1)。
3.3.2 参数说明(通俗解释)
  • l:要嵌套的布局,QLayout* 类型;
    • 可以是任何 QLayout 的子类,比如 QVBoxLayout(垂直布局)、QHBoxLayout(水平布局)、QGridLayout(网格布局)等;
    • 必须是指针类型;
    • 嵌套层级无限制(可以多层嵌套,满足复杂界面布局);
  • row:起始行索引,int 类型(从 0 开始!);
  • column:起始列索引,int 类型(从 0 开始!);
  • rowSpan:跨行数,int 类型(默认 1,≥1);
  • columnSpan:跨列数,int 类型(默认 1,≥1)。
3.3.3 返回值说明
  • 无返回值(void)。
3.3.4 核心作用(通俗理解,必知!)

这个方法是 QGridLayout 实现复杂界面的核心技巧 ------ 网格布局的单个单元格默认只能放一个控件,但如果需要在一个格子里放多个控件(比如一行放两个按钮:"确定" 和 "取消"),就可以先创建一个水平 / 垂直布局,把多个控件放进去,再把这个布局嵌入到网格的单元格里。

通俗理解:addLayout(l, row, col) 就像 "在 Excel 表格的某个单元格里,再放一个小表格"------ 大表格是 QGridLayout,小表格是嵌套的 QVBoxLayout 或 QHBoxLayout,小表格里可以放多个东西。

3.3.5 使用示例(场景化理解:一个格子里放两个按钮)
复制代码
#include <QGridLayout>
#include <QHBoxLayout>
#include <QLabel>
#include <QLineEdit>
#include <QPushButton>
#include <QWidget>

// 假设在 Widget 类的构造函数中,this 是父窗口
// 示例:【嵌套布局】在网格的一个格子里放两个按钮(确定+取消)
QGridLayout* mainLayout = new QGridLayout(this); // 直接指定父对象为 this

// --- 第0行:标题(跨2列) ---
QLabel* titleLabel = new QLabel("用户登录");
titleLabel->setAlignment(Qt::AlignCenter);
mainLayout->addWidget(titleLabel, 0, 0, 1, 2);

// --- 第1行:用户名 ---
mainLayout->addWidget(new QLabel("用户名:"), 1, 0);
mainLayout->addWidget(new QLineEdit(), 1, 1);

// --- 第2行:密码 ---
mainLayout->addWidget(new QLabel("密码:"), 2, 0);
mainLayout->addWidget(new QLineEdit(), 2, 1);

// --- 第3行:【嵌套】水平布局放两个按钮(确定+取消) ---
// 1. 创建水平布局(子布局,用来放两个按钮)
QHBoxLayout* btnLayout = new QHBoxLayout();
// 2. 创建两个按钮
QPushButton* okBtn = new QPushButton("确定");
QPushButton* cancelBtn = new QPushButton("取消");
// 3. 把按钮添加到水平布局
btnLayout->addWidget(okBtn);
btnLayout->addWidget(cancelBtn);
// 4. 【核心!】添加弹簧:在所有控件之前,占据左侧所有空间,把按钮挤到右侧
btnLayout->addStretch();
// 5. 设置子布局的间距
btnLayout->setSpacing(15);

// 6. 【核心!】把水平布局嵌入到网格的3行0列,跨1行2列
mainLayout->addLayout(btnLayout, 3, 0, 1, 2);

// 设置拉伸因子
mainLayout->setColumnStretch(1, 1); // 输入框列自适应宽度

// 设置间距和边距
mainLayout->setHorizontalSpacing(10);
mainLayout->setVerticalSpacing(15);
mainLayout->setContentsMargins(30, 30, 30, 30);
3.3.6 新手避坑点(必看!)
  1. 嵌套布局继承网格规则!(超级重要!) :
    • 嵌套的布局会跟着所在单元格的拉伸规则走!
    • 比如单元格列拉伸因子是 3,嵌套布局也会跟着变宽;
    • 比如单元格行拉伸因子是 1,嵌套布局也会跟着变高(如果嵌套布局里的控件设置了 QSizePolicy);
  2. 嵌套层级无限制!(超级重要!) :
    • 你可以多层嵌套布局;
    • 比如网格→水平→垂直、网格→网格→水平等等;
    • 理论上嵌套层级没有限制,可以满足任何复杂的界面布局;
    • 但实际开发中,建议嵌套层级不要太深(一般不超过 3-4 层),否则会影响性能,也不利于维护;
  3. 无需给嵌套布局设父对象!(超级重要!) :
    • 嵌入到网格后,布局会自动关联到窗口;
    • 无需手动给嵌套布局 setParent;
    • 也无需给嵌套布局里的控件 setParent;
  4. 可以跨行列嵌套!(超级重要!) :
    • 和 addWidget 一样,addLayout 也可以跨行列!
    • 你可以让嵌套布局占多行多列,就像合并单元格一样!

3.4 方法四:setColumnStretch (int column, int stretch) /setRowStretch (int row, int stretch)------ 【拉伸因子】设置列 / 行的空间分配比例

这两个方法刚才讲核心属性的时候已经详细讲过了,这里再简单回顾一下,加深记忆:

  • setColumnStretch(int column, int stretch):设置指定列的拉伸系数,控制窗口变宽时的列宽分配;
    • 通常无需额外设置 QSizePolicy,直接有效;
  • setRowStretch(int row, int stretch):设置指定行的拉伸系数,控制窗口变高时的行高分配;
    • 必须配合控件的垂直 QSizePolicy 设为 Expanding 才有效!(90% 新手栽在这里!)。

具体的参数说明、使用示例、避坑点,请参考第二章的 2.7 和 2.8 节,这里就不重复写了,节省篇幅。


3.5 方法五:setSpacing (int spacing) /setHorizontalSpacing (int spacing) /setVerticalSpacing (int spacing) /setContentsMargins (int left, int top, int right, int bottom)------ 【间距 / 边距】调整控件之间的空隙和布局离窗口的距离

这些方法刚才讲核心属性的时候也已经详细讲过了,这里再简单回顾一下:

  • setSpacing(int spacing):同时设置水平间距和垂直间距为同一个值;
  • setHorizontalSpacing(int spacing):单独设置列与列之间的水平间距;
  • setVerticalSpacing(int spacing):单独设置行与行之间的垂直间距;
  • setContentsMargins(int left, int top, int right, int bottom):批量设置布局与父 Widget 的四周边距(优先使用!)。

具体的参数说明、使用示例、避坑点,请参考第二章的 2.5、2.6、2.9 节,这里也不重复写了。

示例代码:

复制代码
#include "widget.h"       // 你的主窗口类定义
#include "ui_widget.h"    // Qt Designer 生成的 UI 类

// --- Qt 布局管理类 ---
#include <QGridLayout>    // 网格布局 (核心)
#include <QHBoxLayout>    // 水平布局 (用于嵌套)
#include <QVBoxLayout>    // 垂直布局 (备用)

// --- Qt 基础控件类 ---
#include <QWidget>        // 所有控件的基类
#include <QLabel>         // 标签
#include <QLineEdit>      // 单行输入框
#include <QTextEdit>      // 多行文本框
#include <QPushButton>    // 按钮
#include <QCheckBox>      // 复选框

// --- Qt 高级功能类 ---
#include <QFont>          // 字体设置
#include <QSizePolicy>    // 尺寸策略 (行拉伸必用!)
#include <Qt>             // 包含 Qt::Alignment 等枚举值 (通常 QWidgets 会自动包含,但显式包含更稳妥)

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    //OK,本文件我们就来学习QGridLayout的核心方法
    //那么其实大部分方法是和我们前面学习的QHV啥的差不多
    //唯一有区别的也就是这个可以设置说指定行、指定列的比例就是了~~~

    /**
     * @class QGridLayout
     * @brief Qt网格布局管理器的5个核心方法(新手必掌握,覆盖99%网格布局场景)
     * @details QGridLayout是Qt中最灵活的布局管理器,核心是通过"行+列"的二维坐标定位控件,以下5个方法是日常开发的核心,
     *          解释全部采用新手易懂的口语化逻辑,结合"比喻+示例+避坑点",彻底搞懂网格布局的核心用法,无需记忆复杂参数。
     *
     * 【核心逻辑比喻】
     * 把QGridLayout想象成Excel表格:
     * - 每一行、每一列就是表格的行和列,索引从0开始(第1行对应索引0,新手最易踩坑!);
     * - 每个控件就是Excel里的"单元格内容",可占1个单元格,也可跨多行/多列(合并单元格);
     * - 拉伸因子就是"窗口变大时,额外空间分给哪一列/行",因子越大,分的空间越多;
     * - 间距/边距就是"单元格之间的空隙"和"表格离页面边框的距离"。
     */

    // ============================== 核心方法详解(新手友好版) ==============================

    /**
     * @fn void QGridLayout::addWidget(QWidget *w, int row, int col)
     * @brief 【基础定位】把单个控件放到网格的"指定单元格"(默认占1行1列,最常用!)
     * @details 这是网格布局最基础的用法,核心是给控件指定"行坐标+列坐标",就像在Excel里把内容填到第N行第M列,
     *          无需手动计算控件的x/y坐标和宽高,布局会自动分配空间,窗口缩放时控件也会跟着自适应。
     *
     * @参数说明(新手重点看!):
     * @param w      - 要放入网格的控件(比如按钮、标签、输入框等QWidget子类,如QPushButton、QLabel);
     * @param row    - 目标行索引(从0开始!从0开始!从0开始!重要的事说三遍,第1行对应row=0,第2行对应row=1);
     * @param col    - 目标列索引(同理,第1列对应col=0,第2列对应col=1)。
     *
     * @使用示例(一看就懂):
     * // 1. 创建一个按钮控件
     * QPushButton* btn = new QPushButton("我是按钮");
     * // 2. 创建网格布局
     * QGridLayout* layout = new QGridLayout();
     * // 3. 把按钮放到"第1行第1列"(对应row=0, col=0)
     * layout->addWidget(btn, 0, 0);
     * // 4. 把布局设置到窗口,按钮就会显示在网格的0行0列位置
     * this->setLayout(layout);
     *
     * @新手避坑点(必看):
     * 1. 索引从0开始:如果写成addWidget(btn, 1, 1),按钮会出现在"第2行第2列",不是第1行第1列;
     * 2. 稀疏行列不占位:如果把控件设到row=10, col=0,但0-9行没有任何控件,按钮不会跑到第10行,而是紧挨上一个控件(比如0行0列的按钮下方),不会留空白;
     * 3. 自动适配空间:控件默认占满所在单元格的空间,窗口变大,单元格变大,控件也会跟着变大。
     */

    /**
     * @fn void QGridLayout::addWidget(QWidget *w, int row, int col, int rowSpan, int colSpan)
     * @brief 【合并单元格】把控件放到指定位置,并跨越多行/多列(像Excel合并单元格,超实用!)
     * @details 当需要一个控件占多个单元格时用这个方法,比如一个标题标签要横跨整个网格的所有列,
     *          或者一个输入框要占2行1列,核心是通过rowSpan(跨行数)和colSpan(跨列数)控制合并范围。
     *
     * @参数说明(通俗解释):
     * @param w        - 要放入网格的控件(和基础版一样);
     * @param row      - 起始行索引(控件左上角所在的行);
     * @param col      - 起始列索引(控件左上角所在的列);
     * @param rowSpan  - 跨行数(控件要占几行,比如2表示从起始行开始往下占2行);
     * @param colSpan  - 跨列数(控件要占几列,比如3表示从起始列开始往右占3列)。
     *
     * @使用示例(场景化理解):
     * // 场景1:标题标签横跨2列(占0行0列到0行1列,合并2列)
     * QLabel* titleLabel = new QLabel("用户信息(横跨2列)");
     * layout->addWidget(titleLabel, 0, 0, 1, 2); // row=0, col=0, 跨1行2列
     *
     * // 场景2:输入框竖跨2行(占1行0列到2行0列,合并2行)
     * QLineEdit* inputEdit = new QLineEdit("竖跨2行的输入框");
     * layout->addWidget(inputEdit, 1, 0, 2, 1); // row=1, col=0, 跨2行1列
     *
     * // 场景3:按钮占2行3列(从0行0列开始,占2行3列)
     * QPushButton* bigBtn = new QPushButton("大按钮(2行3列)");
     * layout->addWidget(bigBtn, 0, 0, 2, 3);
     *
     * @新手避坑点(必看):
     * 1. 合并范围不能重叠:如果一个控件占了0行0列到0行1列,就不能再往这两个单元格放其他控件,否则布局会混乱;
     * 2. 跨行列后仍自适应:合并后的控件会占满所有合并单元格的空间,窗口缩放时,合并区域整体变大/变小;
     * 3. 跨行列数≥1:rowSpan和colSpan最小是1,不能设0(设0会无效)。
     */

    /**
     * @fn void QGridLayout::addLayout(QLayout *l, int row, int col)
     * @fn void QGridLayout::addLayout(QLayout *l, int row, int col, int rowSpan, int colSpan)
     * @brief 【嵌套布局】在网格的某个单元格(或合并单元格)里嵌入另一个布局(解决"一个格子放多个控件"的问题)
     * @details 网格布局的单个单元格默认只能放一个控件,但如果需要在一个格子里放多个控件(比如一行放两个按钮),
     *          就可以先创建一个水平/垂直布局,把多个控件放进去,再把这个布局嵌入到网格的单元格里,这是复杂界面的核心技巧。
     *
     * @参数说明(通俗解释):
     * @param l        - 要嵌套的布局(比如QHBoxLayout、QVBoxLayout,也可以是另一个QGridLayout);
     * @param row      - 起始行索引(嵌套布局左上角所在的行);
     * @param col      - 起始列索引(嵌套布局左上角所在的列);
     * @param rowSpan  - 可选,跨行数(默认1,嵌套布局占几行);
     * @param colSpan  - 可选,跨列数(默认1,嵌套布局占几列)。
     *
     * @使用示例(场景化理解:一个格子里放两个按钮):
     * // 1. 创建网格布局(父布局)
     * QGridLayout* gridLayout = new QGridLayout();
     *
     * // 2. 创建水平布局(子布局,用来放两个按钮)
     * QHBoxLayout* hBox = new QHBoxLayout();
     * hBox->addWidget(new QPushButton("确定")); // 水平布局里放第一个按钮
     * hBox->addWidget(new QPushButton("取消")); // 水平布局里放第二个按钮
     *
     * // 3. 把水平布局嵌入到网格的1行0列,跨1行2列(占1行0列到1行1列)
     * gridLayout->addLayout(hBox, 1, 0, 1, 2);
     *
     * // 4. 再往网格的0行0列放一个标题标签
     * gridLayout->addWidget(new QLabel("操作按钮(嵌套水平布局)"), 0, 0, 1, 2);
     *
     * // 5. 设置到窗口
     * this->setLayout(gridLayout);
     *
     * @新手避坑点(必看):
     * 1. 嵌套布局继承网格规则:嵌套的布局会跟着所在单元格的拉伸规则走(比如单元格列拉伸因子是3,嵌套布局也会跟着变宽);
     * 2. 嵌套层级无限制:可以在嵌套布局里再嵌套布局(比如网格→水平→垂直),满足任意复杂界面;
     * 3. 无需给嵌套布局设父对象:嵌入到网格后,布局会自动关联到窗口,无需手动setParent。
     */

    /**
     * @fn void QGridLayout::setColumnStretch(int column, int stretch)
     * @fn void QGridLayout::setRowStretch(int row, int stretch)
     * @brief 【拉伸因子】设置列/行的"空间分配比例"(决定窗口变大时,哪一列/行跟着变宽/变高)
     * @details 这是网格布局"自适应窗口"的核心方法,拉伸因子可以理解为"窗口变大时,额外空间的分配权重":
     *          - 因子=0:列/行尺寸固定,不管窗口怎么变,宽度/高度都不变;
     *          - 因子>0:列/行会按因子比例分配额外空间(比如列0因子=1,列1因子=3,窗口变宽100px,列0分25px,列1分75px);
     *          新手最易踩坑:行拉伸需要配合控件的sizePolicy,否则看不到效果!
     *
     * @参数说明(通俗解释):
     * @param column/row - 要设置的列/行索引(从0开始);
     * @param stretch    - 拉伸因子(≥0,0=固定尺寸,>0=按比例分配空间)。
     *
     * @使用示例(列拉伸+行拉伸,新手重点看行拉伸的避坑点):
     * // 1. 创建网格布局和6个按钮(2行3列)
     * QGridLayout* layout = new QGridLayout();
     * QPushButton* btn1 = new QPushButton("列0");
     * QPushButton* btn2 = new QPushButton("列1(固定)");
     * QPushButton* btn3 = new QPushButton("列2(3倍宽)");
     * QPushButton* btn4 = new QPushButton("行1(2倍高)");
     * QPushButton* btn5 = new QPushButton("行1(固定)");
     * QPushButton* btn6 = new QPushButton("行1(3倍高)");
     *
     * // 2. 添加按钮到网格(2行3列)
     * layout->addWidget(btn1, 0, 0); layout->addWidget(btn2, 0, 1); layout->addWidget(btn3, 0, 2);
     * layout->addWidget(btn4, 1, 0); layout->addWidget(btn5, 1, 1); layout->addWidget(btn6, 1, 2);
     *
     * // 3. 设置列拉伸因子(核心:控制列宽)
     * layout->setColumnStretch(0, 1);  // 列0:因子1(窗口变宽时,分1份空间)
     * layout->setColumnStretch(1, 0);  // 列1:因子0(固定宽度,不变)
     * layout->setColumnStretch(2, 3);  // 列2:因子3(窗口变宽时,分3份空间,宽度是列0的3倍)
     *
     * // 4. 设置行拉伸因子(核心:控制行高,新手必看避坑!)
     * layout->setRowStretch(0, 2);  // 行0:因子2(窗口变高时,分2份空间)
     * layout->setRowStretch(1, 3);  // 行1:因子3(窗口变高时,分3份空间)
     *
     * // 5. 行拉伸避坑:按钮默认高度固定,要设置sizePolicy才能看到行拉伸效果!
     * btn1->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
     * btn2->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
     * btn3->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
     * btn4->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
     * btn5->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
     * btn6->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
     *
     * // 6. 设置到窗口
     * this->setLayout(layout);
     *
     * @新手避坑点(必看,90%新手栽在这里):
     * 1. 行拉伸需设置sizePolicy:按钮、标签等控件默认"垂直高度固定",即使设了行拉伸因子,也看不到行变高,必须把控件的垂直sizePolicy设为QSizePolicy::Expanding(表示"尽可能占满空间");
     * 2. 拉伸因子是比例不是绝对值:因子1和3,和因子2和6效果一样(都是1:3),重点看比例,不是数值大小;
     * 3. 所有因子为0:窗口变大时,列/行尺寸不变,控件会居中显示,不会变大。
     */

    /**
     * @fn void QGridLayout::setSpacing(int px)
     * @fn void QGridLayout::setContentsMargins(int left, int top, int right, int bottom)
     * @brief 【间距/边距】设置"单元格之间的空隙"和"布局离窗口边框的距离"(提升界面美观度的核心)
     * @details 这两个方法和QVBoxLayout/QHBoxLayout用法一致,但新手容易混淆"间距"和"边距",用通俗的话区分:
     *          - setSpacing:单元格之间的空隙(比如按钮和按钮之间的距离),默认是系统样式的6px;
     *          - setContentsMargins:整个网格布局离窗口上下左右边框的距离(比如布局左边离窗口左边10px),默认是9px。
     *
     * @参数说明(通俗解释):
     * @param px        - setSpacing的参数,所有单元格之间的水平+垂直间距(单位:像素);
     * @param left      - 布局左边离窗口左边的距离(像素);
     * @param top       - 布局上边离窗口上边的距离(像素);
     * @param right     - 布局右边离窗口右边的距离(像素);
     * @param bottom    - 布局下边离窗口下边的距离(像素)。
     *
     * @使用示例(美观的间距设置):
     * // 1. 创建网格布局
     * QGridLayout* layout = new QGridLayout();
     *
     * // 2. 设置单元格之间的间距(水平+垂直都是10px)
     * layout->setSpacing(10); // 按钮和按钮之间的空隙是10px,不挤也不空
     *
     * // 3. 设置布局离窗口边框的边距(左右15px,上下10px,视觉更平衡)
     * layout->setContentsMargins(15, 10, 15, 10);
     *
     * // 4. 添加控件(示例:2行2列按钮)
     * layout->addWidget(new QPushButton("按钮1"), 0, 0);
     * layout->addWidget(new QPushButton("按钮2"), 0, 1);
     * layout->addWidget(new QPushButton("按钮3"), 1, 0);
     * layout->addWidget(new QPushButton("按钮4"), 1, 1);
     *
     * // 5. 设置到窗口
     * this->setLayout(layout);
     *
     * @新手进阶技巧(必看):
     * 1. 单独设置水平/垂直间距:如果想让单元格水平间距10px,垂直间距15px,不用setSpacing,改用:
     *    layout->setHorizontalSpacing(10); // 水平间距(列之间)
     *    layout->setVerticalSpacing(15);   // 垂直间距(行之间)
     * 2. 边距对称设置:建议左右边距相等,上下边距相等(比如15,10,15,10),界面更美观;
     * 3. 间距不要太大/太小:推荐5-20px,太小控件挤在一起,太大界面松散。
     */

    // ============================== 核心总结 ==============================
    /**
     * @brief QGridLayout 5个核心方法关键点(通俗易懂版)
     * 1. addWidget(w, row, col):给控件定"座位"(行+列),索引从0开始,稀疏行列不留空白;
     * 2. addWidget(w, row, col, rowSpan, colSpan):合并单元格,像Excel一样让控件占多个格子;
     * 3. addLayout(l, row, col):一个格子放多个控件,嵌套水平/垂直布局即可;
     * 4. setColumnStretch/setRowStretch:窗口变大时,按比例分配空间(行拉伸要设sizePolicy!);
     * 5. setSpacing/setContentsMargins:调"控件之间的空隙"和"布局离窗口的距离",界面更美观。
     *
     * 【新手终极技巧】:先画Excel表格草稿,确定每个控件的行/列/跨行列,再用这5个方法实现,复杂界面也能轻松搞定!
     */

    // 设置窗口标题和初始大小,方便观察拉伸效果
    this->setWindowTitle("QGridLayout 核心方法实战演示");
    this->resize(600, 400);

    // ================= 1. 创建网格布局 =================
    QGridLayout *gridLayout = new QGridLayout(this);

    // ================= 2. 设置间距与边距 (美观度核心) =================
    // 单元格之间空隙 15px
    gridLayout->setSpacing(15);
    // 布局距离窗口边缘:左20, 上20, 右20, 下20
    gridLayout->setContentsMargins(20, 20, 20, 20);

    // ================= 3. 添加控件 (基础定位 & 合并单元格) =================

    // --- 第0行:标题 (跨2列) ---
    QLabel *labelTitle = new QLabel("📝 用户注册信息表");
    labelTitle->setFont(QFont("Microsoft YaHei", 16, QFont::Bold));
    labelTitle->setAlignment(Qt::AlignCenter);
    // 核心方法:addWidget(控件, 行, 列, 跨行, 跨列)
    gridLayout->addWidget(labelTitle, 0, 0, 1, 2);

    // --- 第1行:姓名标签 & 输入框 ---
    gridLayout->addWidget(new QLabel("姓 名:"), 1, 0); // 基础定位 (1, 0)

    QLineEdit *editName = new QLineEdit();
    editName->setPlaceholderText("请输入您的姓名");
    gridLayout->addWidget(editName, 1, 1); // 基础定位 (1, 1)

    // --- 第2行:邮箱标签 & 输入框 ---
    gridLayout->addWidget(new QLabel("邮 箱:"), 2, 0);

    QLineEdit *editEmail = new QLineEdit();
    editEmail->setPlaceholderText("example@qq.com");
    gridLayout->addWidget(editEmail, 2, 1);

    // --- 第3行:备注 (标签占1行,文本框跨2行 - 模拟大输入区) ---
    QLabel *labelNote = new QLabel("备 注:");
    labelNote->setAlignment(Qt::AlignTop); // 文字靠上
    gridLayout->addWidget(labelNote, 3, 0);

    QTextEdit *editNote = new QTextEdit();
    editNote->setPlaceholderText("请输入详细备注...");
    editNote->setMinimumHeight(80); // 给个最小高度
    // 核心方法:让文本框占据第3行和第4行 (跨2行)
    gridLayout->addWidget(editNote, 3, 1, 2, 1);

    // --- 第4行:(被上面的 editNote 占据了,跳过) ---

    // --- 第5行:协议勾选 (使用嵌套布局在一个格子里放多个控件) ---
    // 创建一个水平布局作为"子容器"
    QHBoxLayout *hLayoutCheck = new QHBoxLayout();
    hLayoutCheck->setSpacing(5); // 子布局内部间距
    hLayoutCheck->setContentsMargins(0,0,0,0);

    QCheckBox *checkAgree = new QCheckBox("我已阅读并同意《用户协议》");
    // 为了演示嵌套,再强行塞个链接按钮进去
    QPushButton *btnLink = new QPushButton("查看协议");
    btnLink->setFixedSize(60, 20);
    btnLink->setFlat(true);
    btnLink->setStyleSheet("color: blue; text-decoration: underline;");

    hLayoutCheck->addWidget(checkAgree);
    hLayoutCheck->addStretch(1); // 弹簧把按钮挤到右边
    hLayoutCheck->addWidget(btnLink);

    // 核心方法:addLayout(子布局, 行, 列, 跨行, 跨列)
    gridLayout->addLayout(hLayoutCheck, 5, 0, 1, 2);

    // --- 第6行:底部按钮 (取消 & 确定) ---
    QHBoxLayout *hLayoutBtns = new QHBoxLayout();
    QPushButton *btnCancel = new QPushButton("取 消");
    QPushButton *btnSubmit = new QPushButton("提 交");
    btnSubmit->setStyleSheet("background-color: #4CAF50; color: white; font-weight: bold; min-height: 30px;");

    hLayoutBtns->addStretch(1); // 左边弹簧
    hLayoutBtns->addWidget(btnCancel);
    hLayoutBtns->addWidget(btnSubmit);

    gridLayout->addLayout(hLayoutBtns, 6, 0, 1, 2);

    // ================= 4. 设置拉伸因子 (自适应核心) =================

    // 【列拉伸】
    // 第0列 (标签列):因子 0 -> 固定宽度,只容纳文字,不随窗口变宽
    gridLayout->setColumnStretch(0, 0);
    // 第1列 (输入列):因子 1 -> 占用所有剩余空间,窗口变宽时它跟着变宽
    gridLayout->setColumnStretch(1, 1);

    // 【行拉伸】(新手最容易在这里踩坑!)
    // 第3行 (备注行):因子 1 -> 我们希望备注框随窗口变高而变大
    gridLayout->setRowStretch(3, 1);

    // ⚠️ 关键避坑点:
    // 仅仅设置 RowStretch 是不够的!如果控件本身的 SizePolicy 是固定的(如 QPushButton 默认),它不会变高。
    // 必须告诉 QTextEdit:"你可以垂直无限扩张"。
    QSizePolicy policy = editNote->sizePolicy();
    policy.setVerticalPolicy(QSizePolicy::Expanding); // 允许垂直扩张
    policy.setHorizontalPolicy(QSizePolicy::Expanding); // 允许水平扩张
    editNote->setSizePolicy(policy);

    // 其他行保持默认 (因子0),这样窗口变高时,只有"备注"区域会拉长,其他部分保持紧凑
}

Widget::~Widget()
{
    delete ui;
}

第四章 重中之重:QSizePolicy(尺寸策略)详解

在讲 QGridLayout 的行拉伸系数(layoutRowStretch)时,我反复强调了一个点:仅仅设置行拉伸系数是不够的,必须把控件的垂直 QSizePolicy 设为 QSizePolicy::Expanding,否则看不到行变高的效果!

这是 90% 的新手都会踩的坑,也是 QGridLayout 学习中最难理解、但又必须掌握的知识点。所以,我单独用一章来讲 QSizePolicy(尺寸策略),把它讲得明明白白、透透彻彻。

4.1 QSizePolicy 是什么?为什么要用它?

QSizePolicy 是 Qt 中用于 ** 控制控件在布局管理器中 "如何调整自己尺寸"** 的策略类 ------ 它告诉布局管理器:"当有额外空间时,我(控件)要不要扩张?当空间不足时,我(控件)要不要缩小?我的理想尺寸是多少?"

通俗理解:QSizePolicy 就像 "控件的'性格'"------ 有的控件是 "能吃的胖子"(给多少空间占多少空间),有的控件是 "普通人"(有自己的理想尺寸,空间够了就保持理想,不够了就缩小一点),有的控件是 "固执的人"(不管空间多少,我就保持固定尺寸)。

在 QGridLayout 中,QSizePolicy 最重要的作用就是配合行拉伸系数,让控件在垂直方向上扩张------ 因为大多数控件默认 "垂直方向是普通人或固执的人",不会主动扩张,所以即使设了行拉伸系数,行也不会变高;只有把控件的垂直 QSizePolicy 设为 "能吃的胖子"(Expanding),控件才会主动占据额外的垂直空间,行才会变高。

4.2 QSizePolicy 的核心枚举值(新手必掌握,大白话解释)

QSizePolicy 有几个核心的枚举值,用来描述控件在水平和垂直方向的 "尺寸策略"。我会用最通俗的大白话,把每个枚举值都讲清楚,并且说明它们在 QGridLayout 中的实际效果。

注意:QSizePolicy 是分别控制水平方向和垂直方向的 ------ 你可以设置控件的 "水平尺寸策略" 和 "垂直尺寸策略" 不一样,比如水平方向是 Expanding,垂直方向是 Fixed。

为了方便理解,我把重点放在垂直方向(因为这是 QGridLayout 行拉伸的关键),水平方向同理。

4.2.1 QSizePolicy::Fixed------ 固定尺寸(固执的人)

大白话解释:

  • 不管布局管理器给多少空间,我(控件)就保持我的固定尺寸!
  • 空间多了,我也不扩张;
  • 空间少了,我也不缩小(可能会被裁剪)。

QGridLayout 中的效果(垂直方向):

  • 即使设了行拉伸系数,控件高度也不变;
  • 行高度固定,看不到行变高的效果;
  • 非常不适合用来配合行拉伸系数。
4.2.2 QSizePolicy::Minimum------ 最小尺寸(不能再小的人)

大白话解释:

  • 我的最小尺寸是固定的,不能比这个更小了!
  • 空间多了,我可以扩张(但通常扩张得不多);
  • 空间少了,我就保持最小尺寸(可能会被裁剪)。

QGridLayout 中的效果(垂直方向):

  • 设了行拉伸系数后,控件可能会稍微扩张一点,但效果不明显;
  • 不是配合行拉伸系数的最佳选择。
4.2.3 QSizePolicy::Maximum------ 最大尺寸(不能再大的人)

大白话解释:

  • 我的最大尺寸是固定的,不能比这个更大了!
  • 空间多了,我也不扩张(超过最大尺寸后);
  • 空间少了,我可以缩小。

QGridLayout 中的效果(垂直方向):

  • 设了行拉伸系数后,控件扩张到最大尺寸就停了;
  • 不是配合行拉伸系数的最佳选择。
4.2.4 QSizePolicy::Preferred------ 理想尺寸(普通人,默认值!)

大白话解释:

  • 我有一个理想尺寸(比如按钮的理想高度是 25px 左右);
  • 空间够了,我就保持理想尺寸,不扩张;
  • 空间少了,我可以缩小一点,适应空间;
  • 这是大多数控件的默认值!(比如 QPushButton、QLabel 等)。

QGridLayout 中的效果(垂直方向):

  • 这就是为什么 90% 新手设了行拉伸系数但看不到效果!;
  • 因为大多数控件默认垂直 QSizePolicy 是 Preferred!;
  • 空间够了,控件就保持理想高度,不扩张!;
  • 即使设了行拉伸系数,控件高度也不变!;
  • 行高度也不变!;
  • 必须改成 Expanding!。
4.2.5 QSizePolicy::Expanding------ 可扩张(能吃的胖子,配合行拉伸的最佳选择!)

大白话解释:

  • 我没有固定尺寸,给多少空间我就占多少空间!
  • 空间多了,我主动扩张,占据所有额外空间;
  • 空间少了,我可以缩小;
  • 这是配合 QGridLayout 行拉伸系数的最佳选择!。

QGridLayout 中的效果(垂直方向):

  • 终于能看到行变高的效果了!;
  • 设了行拉伸系数后,控件会主动占据额外的垂直空间;
  • 行高度会按拉伸系数比例变高!;
  • 完美!。
4.2.6 QSizePolicy::Ignored------ 忽略尺寸(超级能吃的胖子)

大白话解释:

  • 我完全忽略自己的理想尺寸,给多少空间我就占多少空间!
  • 比 Expanding 更激进,完全不管自己的理想尺寸;
  • 用得比较少,Expanding 通常就够了。

4.3 如何设置 QSizePolicy?(代码示例,一看就懂)

设置 QSizePolicy 的步骤通常是:

  1. 获取控件当前的 QSizePolicy(用 sizePolicy() 方法);
  2. 修改水平或垂直方向的策略(用 setHorizontalPolicy() 或 setVerticalPolicy() 方法);
  3. 把修改后的 QSizePolicy 重新设置给控件(用 setSizePolicy() 方法)。

当然,你也可以直接创建一个新的 QSizePolicy 对象,设置好策略,再设置给控件。

4.3.1 代码示例 1:修改单个控件的垂直 QSizePolicy 为 Expanding
复制代码
#include <QPushButton>
#include <QSizePolicy>

// 假设 btn 是一个 QPushButton 指针
QPushButton* btn = new QPushButton("我是按钮");

// 1. 获取控件当前的 QSizePolicy
QSizePolicy policy = btn->sizePolicy();

// 2. 修改垂直方向的策略为 Expanding(能吃的胖子)
policy.setVerticalPolicy(QSizePolicy::Expanding);

// 3. 把修改后的 QSizePolicy 重新设置给控件
btn->setSizePolicy(policy);
4.3.2 代码示例 2:修改多个控件的垂直 QSizePolicy 为 Expanding(QGridLayout 行拉伸常用)
复制代码
#include <QGridLayout>
#include <QPushButton>
#include <QSizePolicy>
#include <QWidget>

// 假设在 Widget 类的构造函数中,this 是父窗口
QGridLayout* layout = new QGridLayout();

// 创建三个按钮
QPushButton* btn0 = new QPushButton("行0");
QPushButton* btn1 = new QPushButton("行1");
QPushButton* btn2 = new QPushButton("行2");

// ⚠️ 关键步骤:批量修改所有按钮的垂直 QSizePolicy 为 Expanding
// 写一个循环,或者逐个修改
QSizePolicy policy = btn0->sizePolicy();
policy.setVerticalPolicy(QSizePolicy::Expanding); // 允许垂直扩张
// 同时也可以修改水平策略,不过通常不需要
// policy.setHorizontalPolicy(QSizePolicy::Expanding);

btn0->setSizePolicy(policy);
btn1->setSizePolicy(policy);
btn2->setSizePolicy(policy);

// 添加按钮到网格
layout->addWidget(btn0, 0, 0);
layout->addWidget(btn1, 1, 0);
layout->addWidget(btn2, 2, 0);

// 设置行拉伸系数
layout->setRowStretch(0, 1);
layout->setRowStretch(1, 2);
layout->setRowStretch(2, 3);

// 设置间距和边距
layout->setVerticalSpacing(10);
layout->setContentsMargins(20, 20, 20, 20);

this->setLayout(layout);

4.4 QSizePolicy 新手避坑点(必看!)

  1. QGridLayout 行拉伸必须配合垂直 QSizePolicy::Expanding!(超级重要!说三遍!) :
    • 这是本章的核心,也是 QGridLayout 最容易踩的坑!
    • 仅仅设置 setRowStretch() 是完全不够的!
    • 必须把控件的垂直 QSizePolicy 设为 QSizePolicy::Expanding!
    • 否则控件高度不变,行高度也不变!
  2. QSizePolicy 分别控制水平和垂直方向!(超级重要!) :
    • QSizePolicy 是分开控制水平方向和垂直方向的!
    • 你可以设置:
      • 水平:Preferred,垂直:Expanding;
      • 水平:Expanding,垂直:Fixed;
      • 等等;
    • 互不影响,非常灵活;
  3. 大多数控件默认垂直 QSizePolicy 是 Preferred!(超级重要!) :
    • 比如 QPushButton、QLabel、QLineEdit 等;
    • Preferred 是 "普通人",空间够了就保持理想尺寸,不扩张;
    • 所以必须改成 Expanding!
  4. 列拉伸通常不需要额外设置 QSizePolicy!(超级重要!) :
    • 大多数控件默认水平 QSizePolicy 是 Expanding 或 Preferred(但 Preferred 在水平方向通常也会扩张);
    • 所以设置列拉伸系数后,通常直接就能看到效果!
    • 不需要像行拉伸那样额外设置!

第五章 综合示例:用户注册表单

讲完了所有核心属性、核心方法和 QSizePolicy,我们最后来做一个实用的综合示例------ 用户注册表单,把我们今天讲过的所有内容都用到:

  • QGridLayout 网格布局;
  • addWidget 基础定位(行 / 列索引从 0 开始);
  • addWidget 跨行列(标题跨 2 列,备注跨 2 行);
  • addLayout 嵌套布局(底部嵌套水平布局放 "注册" 和 "取消" 按钮);
  • setColumnStretch 设置列拉伸系数(输入框列自适应宽度);
  • setRowStretch 设置行拉伸系数(备注行自适应高度);
  • QSizePolicy 设置备注文本框的垂直尺寸策略为 Expanding;
  • setHorizontalSpacing/setVerticalSpacing 设置水平 / 垂直间距;
  • setContentsMargins 批量设置四边距。

5.1 界面需求

我们要做一个实用的用户注册表单,包含:

  1. 标题:"用户注册",横跨 2 列,居中显示;
  2. 用户名:标签 + 输入框,各占 1 行 1 列;
  3. 密码:标签 + 输入框,各占 1 行 1 列;
  4. 确认密码:标签 + 输入框,各占 1 行 1 列;
  5. 备注:标签 + 多行文本框,文本框竖跨 2 行;
  6. 底部按钮:"注册" 和 "取消" 按钮,嵌套在水平布局里,水平布局嵌入网格底部,横跨 2 列,按钮挤到右侧;
  7. 拉伸因子:输入框列(第 1 列)自适应宽度,备注行(第 4 行)自适应高度;
  8. 界面美观:合适的间距和边距,自适应窗口缩放。

5.2 代码实现

复制代码
#include "widget.h"
#include "ui_widget.h"

// --- Qt 布局管理类 ---
#include <QGridLayout>
#include <QHBoxLayout>

// --- Qt 基础控件类 ---
#include <QLabel>
#include <QLineEdit>
#include <QTextEdit>
#include <QPushButton>

// --- Qt 高级功能类 ---
#include <QFont>
#include <QSizePolicy>
#include <Qt> // 包含 Qt::Alignment 等枚举值

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    // 设置窗口标题和初始大小,方便观察拉伸效果
    this->setWindowTitle("QGridLayout 综合实战:用户注册表单");
    this->resize(500, 450);

    // ================= 1. 创建网格布局(父布局) =================
    QGridLayout *mainLayout = new QGridLayout(this);

    // ================= 2. 设置间距与边距 (美观度核心) =================
    // 列与列之间的水平间距:15px
    mainLayout->setHorizontalSpacing(15);
    // 行与行之间的垂直间距:15px
    mainLayout->setVerticalSpacing(15);
    // 布局距离窗口边缘:左30, 上30, 右30, 下30
    mainLayout->setContentsMargins(30, 30, 30, 30);

    // ================= 3. 添加控件 (基础定位 & 合并单元格) =================

    // --- 第0行:标题 (跨2列) ---
    QLabel *labelTitle = new QLabel("📝 用户注册");
    // 设置标题字体:微软雅黑,18号,加粗
    QFont titleFont = labelTitle->font();
    titleFont.setFamily("Microsoft YaHei");
    titleFont.setPointSize(18);
    titleFont.setBold(true);
    labelTitle->setFont(titleFont);
    // 标题文字居中
    labelTitle->setAlignment(Qt::AlignCenter);
    // 核心方法:addWidget(控件, 行, 列, 跨行, 跨列)
    mainLayout->addWidget(labelTitle, 0, 0, 1, 2);

    // --- 第1行:用户名 ---
    mainLayout->addWidget(new QLabel("用户名:"), 1, 0);

    QLineEdit *editUser = new QLineEdit();
    editUser->setPlaceholderText("请输入 4-16 位用户名");
    mainLayout->addWidget(editUser, 1, 1);

    // --- 第2行:密码 ---
    mainLayout->addWidget(new QLabel("密  码:"), 2, 0);

    QLineEdit *editPass = new QLineEdit();
    editPass->setPlaceholderText("请输入 6-18 位密码");
    editPass->setEchoMode(QLineEdit::Password); // 密码模式,显示圆点
    mainLayout->addWidget(editPass, 2, 1);

    // --- 第3行:确认密码 ---
    mainLayout->addWidget(new QLabel("确认密码:"), 3, 0);

    QLineEdit *editConfirm = new QLineEdit();
    editConfirm->setPlaceholderText("请再次输入密码");
    editConfirm->setEchoMode(QLineEdit::Password);
    mainLayout->addWidget(editConfirm, 3, 1);

    // --- 第4行:备注 (标签占1行,文本框跨2行 - 模拟大输入区) ---
    QLabel *labelNote = new QLabel("备  注:");
    labelNote->setAlignment(Qt::AlignTop); // 文字靠上,不要居中
    mainLayout->addWidget(labelNote, 4, 0);

    QTextEdit *editNote = new QTextEdit();
    editNote->setPlaceholderText("请输入详细备注信息(选填)...");
    editNote->setMinimumHeight(80); // 给个最小高度,避免太矮

    // ⚠️ 关键避坑点:设置文本框的垂直 SizePolicy 为 Expanding!
    // 只有这样,下面的 setRowStretch 才会生效!
    QSizePolicy policy = editNote->sizePolicy();
    policy.setVerticalPolicy(QSizePolicy::Expanding); // 允许垂直无限扩张
    policy.setHorizontalPolicy(QSizePolicy::Expanding); // 水平也允许扩张(可选)
    editNote->setSizePolicy(policy);

    // 核心方法:让文本框占据第4行和第5行 (跨2行)
    mainLayout->addWidget(editNote, 4, 1, 2, 1);

    // --- 第5行:(被上面的 editNote 占据了,跳过) ---

    // --- 第6行:底部按钮 (使用嵌套布局在一个格子里放多个控件) ---
    // 创建一个水平布局作为"子容器"
    QHBoxLayout *hLayoutBtns = new QHBoxLayout();
    hLayoutBtns->setSpacing(15); // 子布局内部按钮间距
    hLayoutBtns->setContentsMargins(0,0,0,0); // 子布局内部边距设为0,避免双重边距

    QPushButton *btnCancel = new QPushButton("取 消");
    QPushButton *btnRegister = new QPushButton("注 册");
    // 给注册按钮加点样式,突出显示
    btnRegister->setStyleSheet("QPushButton { background-color: #4CAF50; color: white; font-weight: bold; border-radius: 4px; min-height: 30px; }");
    btnCancel->setStyleSheet("QPushButton { min-height: 30px; }");

    hLayoutBtns->addStretch(1); // 左边加弹簧,把按钮挤到右边
    hLayoutBtns->addWidget(btnCancel);
    hLayoutBtns->addWidget(btnRegister);

    // 核心方法:addLayout(子布局, 行, 列, 跨行, 跨列)
    mainLayout->addLayout(hLayoutBtns, 6, 0, 1, 2);

    // ================= 4. 设置拉伸因子 (自适应核心) =================

    // 【列拉伸】
    // 第0列 (标签列):因子 0 -> 固定宽度,只容纳文字,不随窗口变宽
    mainLayout->setColumnStretch(0, 0);
    // 第1列 (输入列):因子 1 -> 占用所有剩余空间,窗口变宽时它跟着变宽
    mainLayout->setColumnStretch(1, 1);

    // 【行拉伸】
    // 第4行 (备注行):因子 1 -> 我们希望备注框随窗口变高而变大
    // 注意:上面已经给 editNote 设置了 QSizePolicy::Expanding,这里才会生效!
    mainLayout->setRowStretch(4, 1);

    // 其他行保持默认 (因子0),这样窗口变高时,只有"备注"区域会拉长,其他部分保持紧凑
}

Widget::~Widget()
{
    delete ui;
}

第六章 全文总结与学习建议

恭喜你!终于看完了这篇QGridLayout 详细解析!

如果你跟着文章一步步敲了代码,做了练习,那么现在你已经完全掌握了 QGridLayout 的核心内容,以及 QSizePolicy 的关键用法:

  • 你知道了 QGridLayout 是网格布局管理器,就像 Excel 表格,支持精准二维定位、跨行列、独立设置水平 / 垂直间距、独立设置行 / 列拉伸系数;
  • 你知道了 QGridLayout 和 QVBoxLayout、QHBoxLayout 的核心区别;
  • 你会用 QGridLayout 的核心属性 ------ 四边距、水平 / 垂直间距、行 / 列拉伸系数;
  • 你会用 QGridLayout 的核心方法 ------addWidget 基础定位与跨行列、addLayout 嵌套布局、setColumnStretch/setRowStretch 拉伸因子、setSpacing/setContentsMargins 间距边距;
  • 你知道了 QSizePolicy 的核心枚举值 ------Fixed、Minimum、Maximum、Preferred、Expanding、Ignored;
  • 你知道了 QGridLayout 行拉伸必须配合垂直 QSizePolicy::Expanding 才有效!(这是 90% 新手都会踩的坑!);
  • 你做了一个综合示例 ------ 用户注册表单,用到了所有讲过的知识点。

毫不夸张地说,掌握了 QVBoxLayout、QHBoxLayout 和 QGridLayout,你就掌握了 Qt 布局开发的 95% 以上的需求!

6.1 核心要点回顾(最后再记一遍!)

在结束之前,我们最后再回顾一下这篇文章的核心要点,特别是那些最容易踩坑的地方:

  1. QGridLayout 核心定位!(超级重要!开篇就讲!) :
    • 二维网格布局,通过 "行索引 + 列索引" 精准定位控件;
    • 兼容 QVBoxLayout(所有控件放同一列)和 QHBoxLayout(所有控件放同一行);
  2. 布局管理器通用规则!(超级重要!开篇就讲!) :
    • 一个 QWidget 对象仅能设置一个顶层布局管理器!
    • 控件添加到布局后,不需要手动设置父对象!
    • 布局管理器仅负责界面布局,无任何用户交互相关的信号!
  3. 行 / 列索引从 0 开始!(超级重要!说三遍!) :
    • 第 1 行对应 row=0,第 1 列对应 column=0!
    • 千万不要搞反!
    • 建议先画 Excel 表格草稿,标好索引,再写代码!
  4. 稀疏行列不占位!(超级重要!说三遍!) :
    • 如果把控件设到 row=10, column=0,但 0-9 行没有元素;
    • 控件会紧挨上一个控件,中间不会留空白!
  5. 合并范围不能重叠!(超级重要!) :
    • 一个控件占了某些单元格,就不能再往这些单元格放其他控件!
  6. QSizePolicy 是行拉伸的关键!(超级重要!说三遍!) :
    • 仅仅设置 setRowStretch() 是完全不够的!
    • 必须把控件的垂直 QSizePolicy 设为 QSizePolicy::Expanding!
    • 否则控件高度不变,行高度也不变!
    • 列拉伸通常不需要额外设置 QSizePolicy!
  7. 拉伸系数是比例不是绝对值!(超级重要!) :
    • 重点看比例,不是绝对值!
    • 1:3 和 2:6 效果完全一样!
  8. 优先使用 setContentsMargins 批量设置四边距!(超级重要!) :
    • 不要单独设置单侧边距!
    • 建议对称设置,视觉更平衡!

6.2 最后的话

编程学习没有捷径,唯手熟尔。QGridLayout 的内容虽然不少,但细节很多,特别是 QSizePolicy 的部分,只要你多敲代码、多做练习、多踩坑、多排查,很快就能熟练掌握。

这篇文章虽然很长,但我相信,如果你认真看完了,跟着敲了代码,你一定会对 QGridLayout 有一个极其深刻的理解,再也不用为复杂的多行多列界面发愁。

感谢你阅读这篇文章,希望它能帮到你。我们下一篇 Qt 教程再见!

相关推荐
艾莉丝努力练剑23 分钟前
【AI大模型接入SDK】C++的SessionManager 线程安全
java·开发语言·前端·c++·人工智能·学习·安全
辰小忆43 分钟前
11 · RunCurveChart —— 实时运行曲线
c++·ui·duilib
利威尔xu1 小时前
Go Mutex 饥饿模式:正常模式等待者饿死,1ms 阈值自动切换崩溃
开发语言·后端·面试·golang·并发编程
乌暮2 小时前
少写重复 CRUD:用大白话搞懂 MyBatis-Plus
java·开发语言·spring boot·面试·mybatis
不绝1913 小时前
Lua基础语法入门:注释、变量类型与字符串操作
开发语言·lua
CoderYanger3 小时前
Java EE 进阶:9.MyBatis 操作数据库(进阶)(第四弹):图书管理系统(用户登录+添加图书)
java·数据库·spring boot·mysql·面试·java-ee·mybatis
Hhy_11073 小时前
《C++深度解构07》手撕 vector —— 从底层三指针架构到迭代器失效彻底吃透
c语言·开发语言·c++·学习·visual studio
nice_lcj5203 小时前
【从零理解计算机网络 · 05】TCP 四次挥手:为什么挥手要四次、TIME_WAIT 在等什么
后端·tcp/ip·计算机网络·面试·tcp·四次挥手·time_wait
Moment3 小时前
RSI 是怎样让 AI 改进自己的 ❓❓❓
前端·后端·面试