QC++ / Qt 学习之路

布局管理

用布局代替写死坐标,掌握四种布局与伸缩策略

入门第 22 / 48 章第三篇 · Qt 入门

#为什么不能写死坐标

初学者最容易犯的错误,是像下面这样摆放控件:

Qt 四种常用布局管理器布局自动计算控件位置与尺寸,窗口缩放时自适应;均继承 QLayoutQWidgetQWidgetQWidgetQWidgetQHBoxLayout水平依次排列控件QVBoxLayout垂直依次排列控件QGridLayout行列网格,可跨格QFormLayout标签 + 输入框两列
四种布局管理器的排列效果
C++
// 反面教材:绝对坐标
auto *button = new QPushButton("确定", this);
button->setGeometry(50, 50, 80, 30);      // 写死位置与大小
auto *label = new QLabel("用户名", this);
label->setGeometry(10, 52, 40, 26);

这段代码在作者的机器上运行良好,然后就会遇到一连串问题:

  1. 窗口缩放后控件不动,右侧留一大片空白。
  2. 换个平台字体不一样,文字在按钮里被截断(macOS 的系统字体比 Windows 宽)。
  3. 翻译到其他语言(比如德语比英语长 40%),标签被压扁。
  4. 高 DPI 屏幕上(Qt 6 默认开启缩放),坐标被放大后错位。
  5. 系统字号调整(用户在 Windows 里把缩放调到 150%)后彻底乱套。

根本原因是:你把"布局"这个本该由程序计算的问题,在写代码时用常数固定了。

对比:这正是 Web 前端早已走过的路。早期网页用 <table> 和绝对定位排版,后来有了 Flexbox 与 CSS Grid——浏览器根据容器尺寸和元素的弹性规则自动计算位置。Qt 的 QBoxLayout / QGridLayout 与 Flexbox / Grid 是同一类思路:你声明"这几个控件水平排列、中间留空隙、右边这个占剩余空间",剩下的交给布局引擎。Java Swing 也有 LayoutManager(BorderLayout、GridBagLayout),但 GridBagLayout 的复杂程度劝退了无数人;Qt 的布局 API 设计得直观得多,而且可以嵌套,用简单的盒子组合出复杂界面。Tkinter 的 grid() / pack() 也类似,但 pack 的"剩余空间分配"规则相当难推理,Qt 的 addStretch 与 stretch factor 更直白。

#四种基本布局

#QHBoxLayout / QVBoxLayout:盒子布局

水平或垂直依次排列控件:

C++
auto *h = new QHBoxLayout;
h->addWidget(new QLabel("姓名"));
h->addWidget(new QLineEdit);
h->addWidget(new QPushButton("搜索"));
// 从左到右依次摆放

// ---- QGridLayout:按行列摆放,支持跨行跨列 ----
auto *grid = new QGridLayout;
grid->addWidget(new QLabel("用户:"), 0, 0);
grid->addWidget(m_userEdit,           0, 1);
grid->addWidget(new QLabel("密码:"), 1, 0);
grid->addWidget(m_pwdEdit,            1, 1);
grid->addWidget(m_loginBtn,           2, 0, 1, 2);   // 第2行第0列,占1行2列

// ---- QFormLayout:专用于"标签 + 输入框"的两列表单 ----
auto *form = new QFormLayout;
form->addRow(tr("姓名:"), m_nameEdit);
form->addRow(tr("邮箱:"), m_mailEdit);
form->addRow(tr("备注:"), m_noteEdit);   // 第二列可放任意控件或子布局

QGridLayout 的 addWidget(控件, 行, 列, 占几行, 占几列) 后两个参数省略时默认为 1 行 1 列。

QFormLayout 会自动处理标签对齐,并遵循各平台的标签位置约定(macOS 标签右对齐、Windows 左对齐),因此做设置对话框时优先用它,而不是手写两列 QGridLayout。

这三种之外还有 QStackedLayout(一次只显示一个页面,用于向导/标签页切换)。

#把布局装进窗口

关键一步:布局本身不是控件,它必须"安装"到一个 QWidget 上。一旦窗口有了布局,它的所有子控件的位置与大小就由布局接管,你再调用 setGeometry() / move() / resize() 都会失效(或者被下次布局计算覆盖)。

布局还可以嵌套——addLayout() 接受一个子布局,这是构建复杂界面的核心手法:把界面拆成若干水平/垂直的小盒子,再组合成整体。

C++
auto *window = new QWidget;
auto *layout = new QVBoxLayout(window);   // 方式一:构造时指定父窗口(推荐)
// 或
auto *layout2 = new QVBoxLayout;
window->setLayout(layout2);               // 方式二:显式设置(等价)

// ---- 嵌套布局:把界面拆成小盒子再组合 ----
auto *main = new QVBoxLayout(this);       // 整体垂直

auto *top = new QHBoxLayout;              // 顶部一行水平
top->addWidget(m_searchEdit);
top->addWidget(m_searchBtn);

auto *bottom = new QHBoxLayout;           // 底部一行水平
bottom->addWidget(m_statusLabel);
bottom->addStretch();                     // 见下文
bottom->addWidget(m_okBtn);
bottom->addWidget(m_cancelBtn);

main->addLayout(top);
main->addWidget(m_listWidget);            // 中间列表占据剩余空间
main->addLayout(bottom);

#addStretch 与伸缩因子

addStretch(int stretch = 0) 向布局里插入一段可伸缩的空白(QSpacerItem)。它吸收多余的空间,从而把其他控件"推"到一侧:

C++
auto *h = new QHBoxLayout;
h->addWidget(new QLabel("状态:正常"));
h->addStretch();                 // 吃掉中间所有剩余空间
h->addWidget(okBtn);             // 于是按钮被推到最右边
h->addWidget(cancelBtn);

// ---- 伸缩因子:控制多余空间按什么比例分配 ----
auto *p = new QHBoxLayout;
p->addWidget(leftPanel,  1);     // 占 1 份
p->addWidget(rightPanel, 2);     // 占 2 份 → 右面板宽度是左面板的两倍
p->addWidget(thirdPanel, 0);     // 0 表示"保持自身合适大小,不参与伸缩"

// 在两个 stretch 中间夹一个控件 → 永远居中
auto *c = new QHBoxLayout;
c->addStretch(1);
c->addWidget(centerWidget);
c->addStretch(1);                // 左右各 1 份

addStretch(1) + addStretch(1) 中间夹一个控件,是让控件水平居中的标准写法。addWidget(w, 0) 里的 0 表示"不参与伸缩",常用于让某个按钮保持自然宽度而不被拉长。

对比:这几乎就是 CSS Flexbox 的 flex-grow。addWidget(w, 2) 等价于 flex: 2;addStretch() 等价于一个空的 <div style="flex:1">(或者说 justify-content: space-between 的效果)。如果你有前端经验,把 QHBoxLayout 想成 display:flex; flex-direction:row,QVBoxLayout 想成 column,剩下的概念基本都能对上。

#sizePolicy:控件的"性格"

布局分配空间时会参考每个控件的 sizePolicy,它回答"这个控件想要多大、能伸缩多少"。它由两个方向(QSizePolicy::Policy)组成:

策略含义典型控件
Fixed大小完全固定,用 sizeHint() 的值小图标按钮
Minimum不能小于 sizeHint,可以变大多数按钮
Maximum不能大于 sizeHint,可以变小—
Preferred理想大小是 sizeHint,可大可小(默认)QLabel、QLineEdit
Expanding强烈希望获得更多空间QTextEdit、QListWidget
MinimumExpanding有最小尺寸,且希望扩张QSlider
Ignored忽略 sizeHint,尽可能大/小—
C++
// 让两个控件按 1:3 分配宽度,但都不小于各自 sizeHint
m_list->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
m_edit->setSizePolicy(QSizePolicy::Preferred, QSizePolicy::Fixed);

getSizePolicy() 之外,sizeHint() 是控件的"理想大小"(QLabel::sizeHint() 会按文字长度算),minimumSizeHint() 是"最小可接受大小"。自定义控件时应重写 sizeHint()。

还有一个常用属性:QLineEdit::setMinimumWidth(200)、setFixedWidth(80)、setMaximumHeight(120)——布局会尊重这些约束。

#边距与间距

C++
auto *layout = new QVBoxLayout(this);
layout->setContentsMargins(16, 16, 16, 16);  // 布局四周与窗口边缘的距离(左 上 右 下)
layout->setSpacing(8);                        // 控件之间的间距
layout->addSpacing(20);                       // 在插入点额外加 20px 空隙
layout->addStretch();

Qt 6 里 setContentsMargins 默认值跟随系统风格(通常是 9 或 11),如果你想要紧凑界面或贴合现代设计规范(如 Material 的 16dp 间距),显式设置它。

关于像素单位:Qt 的布局数值默认单位是逻辑像素,Qt 6 默认开启高 DPI 缩放,因此你在 Retina 屏上写 16 会自动换算成合适的物理像素,不要自己乘 devicePixelRatio。

Qt 5 提示:Qt 5 需要手动 QApplication::setAttribute(Qt::AA_EnableHighDpiScaling) 才启用高 DPI,且 setContentsMargins 的行为一致。另外 Qt 5 里 QBoxLayout::setMargin() 是旧 API,Qt 6 已移除,统一用 setContentsMargins。

#手写布局 vs Designer

Qt Creator 内置的 Designer 可以拖拽控件生成 .ui 文件(本质是 XML),编译时 uic 把它转成 ui_xxx.h。两种路线的取舍:

手写代码的优点:布局逻辑可读、可复用、可参数化(比如根据配置动态决定显示哪些控件)、代码审查友好、不会在 .ui 文件里产生难以 diff 的 XML 冲突。缺点:不直观,需要运行才能看到效果。

Designer 的优点:所见即所得,调整间距和嵌套关系非常快,适合静态的复杂界面。缺点:.ui 是二进制友好的但不是人友好的,多人协作 merge 冲突难解;动态逻辑仍要写代码。

实践建议:

  • 学习阶段全部手写(本系列就是如此),这能让你真正理解布局是如何工作的。
  • 实际项目中,复杂静态界面用 Designer,动态部分用代码;或者主窗口骨架用 Designer,动态填充的区域用代码。
  • 使用 Designer 时,常见做法是"提升窗口类":在 Designer 里放一个 QWidget,右键"提升为"你的自定义类。

如果使用 .ui 文件,C++ 代码里这样用:

C++
// mainwindow.h
#include <QMainWindow>
QT_BEGIN_NAMESPACE
namespace Ui { class MainWindow; }   // 前向声明,避免在头文件里包含 ui_xxx.h
QT_END_NAMESPACE

class MainWindow : public QMainWindow
{
    Q_OBJECT
public:
    explicit MainWindow(QWidget *parent = nullptr);
    ~MainWindow() override;
private:
    Ui::MainWindow *ui;              // 持有 ui 类的指针(Pimpl 风格)
};

// ---- mainwindow.cpp ----
#include "mainwindow.h"
#include "ui_mainwindow.h"           // uic 生成的头文件

MainWindow::MainWindow(QWidget *parent)
    : QMainWindow(parent), ui(new Ui::MainWindow)
{
    ui->setupUi(this);               // 创建所有控件并安装布局
    connect(ui->pushButton, &QPushButton::clicked, this, [](){ /* ... */ });
}

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

CMake 需要 set(CMAKE_AUTOUIC ON)(第 1 章已配置),并把 .ui 文件加入目标源。

#布局的所有权

一个重要细节:当控件被 addWidget() 加入布局后,它的 parent 会被自动设置为该布局所属的窗口。因此下面这段代码是安全的,无需手动 delete:

C++
auto *layout = new QVBoxLayout(this);
layout->addWidget(new QPushButton("OK"));    // 按钮的 parent 变成 this 或其容器

但如果布局尚未安装到任何窗口(new QHBoxLayout 没有父控件、也没 setLayout),此时 addWidget 不会转移所有权。你可以先创建布局、填控件、最后一次性 window->setLayout(layout),控件的所有权会在 setLayout 时一并转移。

另外,一个控件只能属于一个布局。把它加入第二个布局会自动从第一个里移除(Qt 打印警告)。切换布局时要先 removeWidget()。

#小结

  • 绝对坐标无法应对窗口缩放、字体差异、翻译变长与高 DPI,必须用布局。
  • 四种布局:QHBoxLayout/QVBoxLayout(盒子)、QGridLayout(网格,支持跨行列)、QFormLayout(表单,自动对齐)。
  • 布局通过 addLayout() 嵌套组合;addStretch() 吸收剩余空间,addWidget(w, n) 的伸缩因子按 n 份分配多余空间。
  • sizePolicy 决定控件"想要多大、能否伸缩",配合 setMinimumWidth / setFixedWidth 使用。
  • 控件加入布局后所有权自动转移给窗口;学习阶段建议手写布局,复杂静态界面再用 Designer。

#练习

  1. 用纯嵌套布局实现一个登录窗口:上方居中的标题(用 addStretch 上下撑开)、中间 QFormLayout 表单、底部"登录/取消"按钮靠右。要求窗口从 300×200 拉到 800×600 时各控件位置始终正确。
  2. 实现左右分栏:左侧列表占 1 份、右侧编辑区占 3 份,中间加一个可拖动的 QSplitter;对比 QSplitter 与"布局 + stretch 因子"在交互上的差异(提示:splitter 允许用户调整比例)。
  3. 写一个 3×3 的网格布局,其中某个控件跨 2 行 1 列(如左侧一列放一个大的头像标签);再加一个 QGridLayout::setColumnStretch(1, 1) 观察列宽变化。
  4. 用 Designer 画出练习 1 的界面,导出 .ui 后在代码里加载它;比较两种方式产出的代码量与可读性,并写下你倾向的方案及理由。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。