Qt开发：容器组控件的介绍和使用

一、Group Box（分组框）

  在 Qt 中，Group Box（分组框） 是一种常用的容器控件，由 QGroupBox 类提供，用于将多个相关的控件组合在一起，通常带有一个标题以标识这组控件的功能区域。

1.1 QGroupBox 简介

QGroupBox 的作用是组织界面布局、逻辑分区，使界面更清晰、有条理。
特点：

• 可添加标题；
• 可设置是否可勾选（启用/禁用整组控件）；
• 可与布局管理器配合使用，容纳任意数量的控件。

1.2 基本用法

QGroupBox *groupBox = new QGroupBox("网络设置");// 可选择添加 layout 管理子控件
QVBoxLayout *vbox = new QVBoxLayout;
vbox->addWidget(new QRadioButton("有线网络"));
vbox->addWidget(new QRadioButton("无线网络"));
groupBox->setLayout(vbox);

1.3 设置为可勾选（可启用/禁用子控件）

groupBox->setCheckable(true);         // 显示复选框
groupBox->setChecked(false);          // 初始是否启用

勾选时内部控件启用，取消勾选时内部控件会自动禁用。

1.4 信号与槽连接（监控勾选状态）

connect(groupBox, &QGroupBox::toggled, this, [](bool checked){qDebug() << "GroupBox 是否启用:" << checked;
});

1.5 布局示例（完整）

#ifndef MAINWINDOW_H
#define MAINWINDOW_H#include <QWidget>
#include <QGroupBox>
#include <QRadioButton>
#include <QCheckBox>
#include <QVBoxLayout>
#include <QGridLayout>class MainWindow : public QWidget
{Q_OBJECTpublic:MainWindow(QWidget *parent = nullptr) : QWidget(parent) {// 组合框1：gpb_1QGroupBox *gpb_1 = new QGroupBox("单选按钮组1", this);QRadioButton *rbtn_1 = new QRadioButton("QRadioButton1", this);QRadioButton *rbtn_2 = new QRadioButton("QRadioButton2", this);QRadioButton *rbtn_3 = new QRadioButton("QRadioButton3", this);QVBoxLayout *vbly1 = new QVBoxLayout(this);vbly1->addWidget(rbtn_1);vbly1->addWidget(rbtn_2);vbly1->addWidget(rbtn_3);gpb_1->setLayout(vbly1);// 组合框2：gpb_2QGroupBox *gpb_2 = new QGroupBox("复选按钮组2", this);QCheckBox *cbx1 = new QCheckBox("CheckBox_1", this);QCheckBox *cbx2 = new QCheckBox("CheckBox_2", this);QCheckBox *cbx3 = new QCheckBox("CheckBox_3", this);cbx2->setTristate(true); // 设置是否支持半选状态，默认不支持半选状态QVBoxLayout *vbly2 = new QVBoxLayout(this);vbly2->addWidget(cbx1);vbly2->addWidget(cbx2);vbly2->addWidget(cbx3);gpb_2->setLayout(vbly2);// 组合框3：gpb_3QGroupBox *gpb_3 = new QGroupBox("单选按钮和复选按钮组3", this);gpb_3->setCheckable(true);QRadioButton *rbtn_31 = new QRadioButton("QRadioButton31", this);QRadioButton *rbtn_32 = new QRadioButton("QRadioButton32", this);QRadioButton *rbtn_33 = new QRadioButton("QRadioButton33", this);QCheckBox *cbx4 = new QCheckBox("CheckBox4");QVBoxLayout *vbly3 = new QVBoxLayout(this);vbly3->addWidget(rbtn_31);vbly3->addWidget(rbtn_32);vbly3->addWidget(rbtn_33);vbly3->addWidget(cbx4);gpb_3->setLayout(vbly3);// 组合框4：gpb_4QGroupBox *gpb_4 = new QGroupBox("综合按钮4", this);gpb_4->setCheckable(true);gpb_4->setChecked(true);QRadioButton *rbtn_4 = new QRadioButton("QRadioButton4", this);QRadioButton *rbtn_5= new QRadioButton("QRadioButton5", this);rbtn_5->setCheckable(true);rbtn_5->setChecked(true);QVBoxLayout *vbly4 = new QVBoxLayout(this);vbly4->addWidget(rbtn_4);vbly4->addWidget(rbtn_5);gpb_4->setLayout(vbly4);QGridLayout *gdlayout = new QGridLayout(this);gdlayout->addWidget(gpb_1, 0, 0, 1, 1);gdlayout->addWidget(gpb_2, 0, 1, 1, 1);gdlayout->addWidget(gpb_3, 1, 0, 1, 1);gdlayout->addWidget(gpb_4, 1, 1, 1, 1);this->setLayout(gdlayout);}~MainWindow() {}
};
#endif // MAINWINDOW_H

输出结果：

二、Scroll Area（滚动区域控件）

  在 Qt 中，滚动区域控件（Scroll Area） 是用于在内容超出显示区域时提供滚动功能的控件，由 QScrollArea 类实现。它允许你将一个大的 QWidget 放入其中，并在内容超出时自动显示滚动条。

2.1 QScrollArea 简介

QScrollArea 是一个滚动容器，通常用于嵌套显示：

• 大量控件（如表单、设置项）；
• 尺寸较大的图像、图形界面等；
• 动态生成的控件列表等。

它只支持一个子 widget，但该 widget 可以是带布局的容器。

2.2 基本使用方式

QScrollArea *scrollArea = new QScrollArea(this);QWidget *container = new QWidget;
QVBoxLayout *layout = new QVBoxLayout(container);for (int i = 0; i < 20; ++i) {layout->addWidget(new QLabel(QString("Label %1").arg(i + 1)));
}scrollArea->setWidget(container);
scrollArea->setWidgetResizable(true);  // 自动适应窗口大小

2.3 常用设置

例如：

scrollArea->setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
scrollArea->setVerticalScrollBarPolicy(Qt::ScrollBarAsNeeded);

2.4 实际场景示例：图片查看器

#ifndef MAINWINDOW_H
#define MAINWINDOW_H#include <QWidget>
#include <QScrollArea>
#include <QVBoxLayout>
#include <QLabel>
#include <QPixmap>class MainWindow : public QWidget
{Q_OBJECTpublic:MainWindow(QWidget *parent = nullptr) : QWidget(parent) {this->resize(400, 300);this->setWindowTitle("图片滚动浏览示例");// 创建滚动区域QScrollArea *scrollArea = new QScrollArea(this);scrollArea->setFixedSize(400, 300);//scrollArea->setAlignment(Qt::AlignCenter); // 居中显示scrollArea->setWidgetResizable(true);// 创建内容容器QWidget *container = new QWidget;QVBoxLayout *layout = new QVBoxLayout(container);// 加载图像（演示用，多次重复加载同一张）QPixmap pixmap("./MultiTexture/BrushStroke_Coloured_Variant_C.png");  // 替换为你自己的图片路径if (!pixmap.isNull()) {for (int i = 0; i < 10; ++i) {QLabel *imgLabel = new QLabel;imgLabel->setPixmap(pixmap.scaled(300, 200, Qt::KeepAspectRatio, Qt::SmoothTransformation));layout->addWidget(imgLabel);}} else {QLabel *err = new QLabel("图片加载失败！");layout->addWidget(err);}scrollArea->setWidget(container);}~MainWindow() {}
};
#endif // MAINWINDOW_H

输出结果：

2.5 九宫格图片布局的版本（即横向+纵向滚动）

#ifndef MAINWINDOW_H
#define MAINWINDOW_H#include <QWidget>
#include <QScrollArea>
#include <QVBoxLayout>
#include <QLabel>
#include <QPixmap>class MainWindow : public QWidget
{Q_OBJECTpublic:MainWindow(QWidget *parent = nullptr) : QWidget(parent) {this->resize(600, 400);this->setWindowTitle("九宫格图片浏览");QScrollArea *scrollArea = new QScrollArea(this);scrollArea->setFixedSize(600, 400);//scrollArea->setWidgetResizable(true);// 创建容器和网格布局QWidget *container = new QWidget(this);QGridLayout *grid = new QGridLayout(container);//grid->setSpacing(10);QPixmap pixmap("./MultiTexture/BrushStroke_Coloured_Variant_C.png"); // 替换为实际图片路径int cols = 5;int index = 0;if (!pixmap.isNull()) {for (int i = 0; i < 40; ++i) {  // 加载 40 张图QLabel *label = new QLabel;label->setPixmap(pixmap.scaled(150, 100, Qt::KeepAspectRatio, Qt::SmoothTransformation));label->setAlignment(Qt::AlignCenter);grid->addWidget(label, index / cols, index % cols);++index;}} else {QLabel *err = new QLabel("图片加载失败！");grid->addWidget(err, 0, 0);}scrollArea->setWidget(container);scrollArea->setHorizontalScrollBarPolicy(Qt::ScrollBarAsNeeded);scrollArea->setVerticalScrollBarPolicy(Qt::ScrollBarAsNeeded);}~MainWindow() {}
};
#endif // MAINWINDOW_H

输出结果：

三、Tab Widget（标签页控件）

  在 Qt 中，Tab Widget（标签页控件） 是一种常用的容器控件，可以将多个页面组织在同一个窗口内，以标签的形式切换，提供良好的模块化用户体验。对应的类为 QTabWidget。

3.1 QTabWidget 简介

  QTabWidget 提供一组可以切换的页面，每个页面都有一个对应的标签页（Tab）。常见于设置窗口、工具属性窗口、选项配置面板等。

3.2 常用函数

3.3 基本使用示例

QTabWidget *tabWidget = new QTabWidget(this);// 创建页面
QWidget *page1 = new QWidget;
QWidget *page2 = new QWidget;// 给页面添加布局和控件
page1->setLayout(new QVBoxLayout);
page1->layout()->addWidget(new QLabel("这是第一页"));page2->setLayout(new QVBoxLayout);
page2->layout()->addWidget(new QLabel("这是第二页"));// 添加页面到标签控件
tabWidget->addTab(page1, "第一页");
tabWidget->addTab(page2, "第二页");

3.4 切换响应（信号）

connect(tabWidget, &QTabWidget::currentChanged, this, [](int index){qDebug() << "当前切换到第" << index << "个标签页";
});

3.5 设置标签位置

tabWidget->setTabPosition(QTabWidget::North); // 默认
tabWidget->setTabPosition(QTabWidget::South); // 下方
tabWidget->setTabPosition(QTabWidget::West);  // 左侧
tabWidget->setTabPosition(QTabWidget::East);  // 右侧

3.6 QTabWidget 创建一个包含多个标签页

#ifndef MAINWINDOW_H
#define MAINWINDOW_H#include <QWidget>
#include <QTabWidget>
#include <QVBoxLayout>
#include <QFormLayout>
#include <QLabel>
#include <QLineEdit>
#include <QComboBox>
#include <QCheckBox>
#include <QTextEdit>
#include <QPushButton>class MainWindow : public QWidget
{Q_OBJECTpublic:MainWindow(QWidget *parent = nullptr) : QWidget(parent) {this->resize(400, 250);this->setWindowTitle("系统设置");QTabWidget *tabWidget = new QTabWidget(this);tabWidget->setFixedSize(400, 250);// 通用设置页QWidget *generalPage = new QWidget;QFormLayout *generalLayout = new QFormLayout(generalPage);generalLayout->addRow("用户名:", new QLineEdit);generalLayout->addRow("语言:", new QComboBox);generalLayout->addRow("自动启动:", new QCheckBox);// 网络设置页QWidget *networkPage = new QWidget;QFormLayout *networkLayout = new QFormLayout(networkPage);networkLayout->addRow("IP地址:", new QLineEdit("192.168.1.1"));networkLayout->addRow("端口:", new QLineEdit("8080"));networkLayout->addRow("启用代理:", new QCheckBox);// 关于页QWidget *aboutPage = new QWidget;QVBoxLayout *aboutLayout = new QVBoxLayout(aboutPage);QLabel *aboutText = new QLabel("智能安检系统 v1.0\n© 2025 安检科技有限公司");aboutText->setAlignment(Qt::AlignCenter);aboutLayout->addWidget(aboutText);// 添加页面到TabWidgettabWidget->addTab(generalPage, "通用设置");tabWidget->addTab(networkPage, "网络设置");tabWidget->addTab(aboutPage, "关于");}~MainWindow() {}
};
#endif // MAINWINDOW_H

输出结果：

四、Frame （框架）

  在 Qt 中，QFrame 是一个非常基础而灵活的控件，常用于作为视觉上的边框、分隔线或容器，能够帮助美化 UI 和组织布局。

4.1 QFrame 简介

• QFrame 是 QWidget 的子类；
• 可显示边框、分割线或用作面板容器；
• 可以设置线条样式（凹陷、凸起、平面等）；
• 常用于 UI 界面分组、视觉分隔。

4.2 常用设置项说明

常用的 QFrame::Shape 值：

常用的 QFrame::Shadow 值：

4.3 基本用法示例

QFrame *frame = new QFrame(this);
frame->setFrameShape(QFrame::Box);             // 边框形状
frame->setFrameShadow(QFrame::Raised);         // 阴影样式
frame->setLineWidth(2);                        // 边框宽度
frame->setFixedSize(200, 100);                 // 尺寸

4.4 分隔线示例（水平/垂直线）

QFrame *line = new QFrame(this);
line->setFrameShape(QFrame::HLine);
line->setFrameShadow(QFrame::Sunken);
line->setLineWidth(1);

4.5 作为容器嵌套其他控件

QFrame *groupFrame = new QFrame(this);
groupFrame->setFrameShape(QFrame::Box);
groupFrame->setLayout(new QVBoxLayout);
groupFrame->layout()->addWidget(new QLabel("内容"));

4.6 使用 QFrame 创建一个典型的三分区主窗口布局

#ifndef MAINWINDOW_H
#define MAINWINDOW_H#include <QWidget>
#include <QHBoxLayout>
#include <QVBoxLayout>
#include <QFrame>
#include <QLabel>class MainWindow : public QWidget
{Q_OBJECTpublic:MainWindow(QWidget *parent = nullptr) : QWidget(parent) {this->resize(800, 500);this->setWindowTitle("QFrame 三分区布局示例");QHBoxLayout *mainLayout = new QHBoxLayout(this);mainLayout->setSpacing(10);mainLayout->setContentsMargins(10, 10, 10, 10);// 左侧导航区QFrame *leftFrame = new QFrame(this);leftFrame->setFrameShape(QFrame::StyledPanel);leftFrame->setFixedWidth(150);QVBoxLayout *leftLayout = new QVBoxLayout(leftFrame);leftLayout->addWidget(new QLabel("导航1"));leftLayout->addWidget(new QLabel("导航2"));leftLayout->addStretch();// 中间主内容区QFrame *centerFrame = new QFrame(this);centerFrame->setFrameShape(QFrame::StyledPanel);QVBoxLayout *centerLayout = new QVBoxLayout(centerFrame);centerLayout->addWidget(new QLabel("这里是主内容区"));centerLayout->addStretch();// 右侧辅助区QFrame *rightFrame = new QFrame(this);rightFrame->setFrameShape(QFrame::StyledPanel);rightFrame->setFixedWidth(200);QVBoxLayout *rightLayout = new QVBoxLayout(rightFrame);rightLayout->addWidget(new QLabel("辅助信息"));rightLayout->addStretch();// 添加到主布局mainLayout->addWidget(leftFrame);mainLayout->addWidget(centerFrame, 1);  // 主区弹性拉伸mainLayout->addWidget(rightFrame);}~MainWindow() {}
};
#endif // MAINWINDOW_H

五、ToolBox（工具箱）

  在 Qt 中，QToolBox 是一个用于折叠式分组显示内容的容器控件，它的外观类似于“抽屉式”控件，非常适合用于显示工具栏、设置分组、帮助信息等场景。

5.1 QToolBox 简介

• QToolBox 是一个容器控件，可以容纳多个“页面”；
• 每一页都有一个标签（标题），用户可以点击切换展开；
• 同一时间只能展开一个页面，其它页面会自动折叠；
• 类似于 Qt Designer 左侧的属性分类区域，或 IDE 的工具抽屉。

5.2 常用方法

5.3 基本用法示例

QToolBox *toolBox = new QToolBox(this);// 第一个页面
QWidget *page1 = new QWidget;
QVBoxLayout *layout1 = new QVBoxLayout(page1);
layout1->addWidget(new QLabel("工具1"));
layout1->addWidget(new QPushButton("按钮A"));// 第二个页面
QWidget *page2 = new QWidget;
QVBoxLayout *layout2 = new QVBoxLayout(page2);
layout2->addWidget(new QLabel("设置项1"));
layout2->addWidget(new QCheckBox("启用功能"));// 添加到工具箱
toolBox->addItem(page1, "工具集");
toolBox->addItem(page2, "设置面板");

5.4 信号槽

// 当当前展开页改变时触发
connect(toolBox, &QToolBox::currentChanged, [](int index){qDebug() << "切换到第" << index << "页";
});

5.5 完整窗口应用 QToolBox

#ifndef MAINWINDOW_H
#define MAINWINDOW_H#include <QWidget>
#include <QToolBox>
#include <QVBoxLayout>
#include <QLabel>
#include <QPushButton>
#include <QCheckBox>class MainWindow : public QWidget
{Q_OBJECTpublic:MainWindow(QWidget *parent = nullptr) : QWidget(parent) {this->resize(300, 250);this->setWindowTitle("QToolBox 示例");QToolBox *toolBox = new QToolBox(this);toolBox->setFixedSize(300, 250);// 页面1QWidget *page1 = new QWidget(this);QVBoxLayout *l1 = new QVBoxLayout(page1);l1->addWidget(new QPushButton("工具按钮1"));l1->addWidget(new QPushButton("工具按钮2"));// 页面2QWidget *page2 = new QWidget(this);QVBoxLayout *l2 = new QVBoxLayout(page2);l2->addWidget(new QCheckBox("启用功能A"));l2->addWidget(new QCheckBox("启用功能B"));toolBox->addItem(page1, "工具集");toolBox->addItem(page2, "功能设置");}~MainWindow() {}
};
#endif // MAINWINDOW_H

输出结果：