Qt 常用 UI 控件详解：从QPushButton到QLabel 核心用法解析

🔥个人主页：Cx330🌸

❄️个人专栏：《C语言》《LeetCode刷题集》《数据结构-初阶》《C++知识分享》

《优选算法指南-必刷经典100题》《Linux操作系统》:从入门到入魔

《Git深度解析》:版本管理实战全解《Qt 极境架构》MySQL 核心技术与实战

🌟心向往之行必能

🎥Cx330🌸的简介：

前言：

[一、按钮类控件：交互逻辑的核心载体](#一、按钮类控件：交互逻辑的核心载体)

[1.1 PushButton：最常用的普通按钮](#1.1 PushButton：最常用的普通按钮)

[1.2 RadioButton：单选按钮（互斥选择）](#1.2 RadioButton：单选按钮（互斥选择）)

[1.3 CheckBox：复选按钮（多选选择）](#1.3 CheckBox：复选按钮（多选选择）)

[1.4 按钮类控件关键区别与选型](#1.4 按钮类控件关键区别与选型)

[二. 显示类核心控件：Label（文本与图片展示）](#二. 显示类核心控件：Label（文本与图片展示）)

[三、总结对比](#三、总结对比)

前言：

在 Qt 的 GUI 开发中，掌握基础 UI 控件的特性与使用场景是构建良好用户交互界面的关键。本文基于课堂板书笔记，全面梳理 QRadioButton 、QCheckBox 、QLineEdit 以及 QLabel 的核心功能、继承体系与实战技巧。

一、按钮类控件：交互逻辑的核心载体

按钮类控件继承自QAbstractButton，共享文本、图标、快捷键等基础属性，同时各自具备独特交互逻辑，适用于不同选择场景。

1.1 PushButton：最常用的普通按钮

QPushButton是 Qt 中最基础的交互按钮，支持文本、图标、快捷键、重复触发等功能，是界面中 "确认""提交""取消" 等操作的首选。

核心属性与 API（继承 + 独有）：

基础属性 ：text（按钮文本）、icon（图标）、iconSize（图标尺寸）、shortcut（快捷键）；
交互属性 ：autoRepeat（长按重复触发）、autoRepeatDelay（重复触发延时）、autoRepeatInterval（重复触发周期）；
核心 API ：
- setText(const QString& text)：设置按钮文本；
- setIcon(const QIcon& icon)：设置按钮图标；
- setShortcut(const QKeySequence& key)：设置快捷键（支持单个键或组合键）；
- setAutoRepeat(bool flag)：开启 / 关闭长按重复触发。

实战示例 1：带图标 + 快捷键的按钮

新增 qrc资源文件，添加图标（如claw.png），前缀设为**/**；
代码中设置按钮图标、尺寸和快捷键：

#include "widget.h"
#include "ui_widget.h"
#include

Widget::Widget(QWidget *parent)
: QWidget(parent)
, ui(new Ui::Widget)
{
ui->setupUi(this);
// 设置图标（从qrc资源读取）
QIcon icon(":/claw.png");
ui->pushButton->setIcon(icon);
ui->pushButton->setIconSize(QSize(50, 50)); // 图标尺寸50x50
// 设置快捷键（支持"w"单个键或"Ctrl+C"组合键）
ui->pushButton->setShortcut(QKeySequence("w"));
// 开启长按重复触发（类似游戏连发效果）
ui->pushButton->setAutoRepeat(true);
ui->pushButton->setAutoRepeatDelay(300); // 长按300ms后开始重复
ui->pushButton->setAutoRepeatInterval(100); // 每100ms触发一次
}

// 按钮点击槽函数
void Widget::on_pushButton_clicked()
{
qDebug() << "按钮被触发";
}

效果：按钮显示图标 + 文本，按w键或点击按钮均可触发，长按后会连续输出日志。

实战示例 2：控制目标按钮移动(带图片)

用四个方向 PushButton 控制目标按钮移动，结合geometry属性实现位置调整：

复制代码

#include "widget.h"
#include "ui_widget.h"

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

    // 设置这些按钮的图标
    ui->pushButton_target->setIcon(QIcon(":/claw.png"));
    ui->pushButton_target->setIconSize(QSize(50,50));

    ui->pushButton_up->setIcon(QIcon(":/up.png"));
    ui->pushButton_down->setIcon(QIcon(":/down.png"));
    ui->pushButton_left->setIcon(QIcon(":/left.png"));
    ui->pushButton_right->setIcon(QIcon(":/right.png"));

    // 设置快捷键------直接通过按键的名字来设置虽然简单，但是很容易先写错
//    ui->pushButton_up->setShortcut(QKeySequence("ctrl + w"));
//    ui->pushButton_down->setShortcut(QKeySequence("s"));
//    ui->pushButton_left->setShortcut(QKeySequence("a"));
//    ui->pushButton_right->setShortcut(QKeySequence("d"));

    // 还可以通过按键的枚举来设置按键快捷键
//    ui->pushButton_up->setShortcut(QKeySequence(Qt::CTRL + Qt::Key_W));
    ui->pushButton_up->setShortcut(QKeySequence(Qt::Key_W));
    ui->pushButton_down->setShortcut(QKeySequence(Qt::Key_S));
    ui->pushButton_left->setShortcut(QKeySequence(Qt::Key_A));
    ui->pushButton_right->setShortcut(QKeySequence(Qt::Key_D));

    // 开启鼠标点击的连发功能（键盘连发默认是支持的）
    ui->pushButton_up->setAutoRepeat(true);
    ui->pushButton_down->setAutoRepeat(true);
    ui->pushButton_left->setAutoRepeat(true);
    ui->pushButton_right->setAutoRepeat(true);

}

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


void Widget::on_pushButton_up_clicked()
{
    // 获取 target 的位置
    QRect rect = ui->pushButton_target->geometry();
    // 基于上次的位置设置新的位置
    ui->pushButton_target->setGeometry(rect.x(),rect.y()-5,rect.width(),rect.height());
}

void Widget::on_pushButton_down_clicked()
{
    // 获取 target 的位置
    QRect rect = ui->pushButton_target->geometry();
    // 基于上次的位置设置新的位置
    ui->pushButton_target->setGeometry(rect.x(),rect.y()+5,rect.width(),rect.height());
}

void Widget::on_pushButton_left_clicked()
{
    // 获取 target 的位置
    QRect rect = ui->pushButton_target->geometry();
    // 基于上次的位置设置新的位置
    ui->pushButton_target->setGeometry(rect.x()-5,rect.y(),rect.width(),rect.height());
}

void Widget::on_pushButton_right_clicked()
{
    // 获取 target 的位置
    QRect rect = ui->pushButton_target->geometry();
    // 基于上次的位置设置新的位置
    ui->pushButton_target->setGeometry(rect.x()+5,rect.y(),rect.width(),rect.height());
}

1.2 RadioButton：单选按钮（互斥选择）

QRadioButton适用于 "多选一" 场景（如性别选择、选项切换），默认具备互斥性(排他性) （选中一个会取消其他），可通过QButtonGroup分组实现多组单选。

核心属性与 API：

关键属性 ：checkable（是否可选中，默认 true）、checked（是否已选中）、autoExclusive（是否互斥，默认 true）；
核心 API ：
- setChecked(bool flag)：设置默认选中状态；
- isChecked()：判断是否被选中；
- setAutoExclusive(bool flag)：开启 / 关闭互斥（关闭后可多选，不推荐）。

实战示例：性别选择（基础单选）

拖放 3 个 RadioButton（男 / 女 / 其他）和 1 个 Label；
编写槽函数实现选择联动：

#include "widget.h"
#include "ui_widget.h"

Widget::Widget(QWidget *parent)
: QWidget(parent)
, ui(new Ui::Widget)
{
ui->setupUi(this);
复制代码
```
 // 初始一个默认选择的按钮
 // 设置默认选中"男"
 ui->radioButton_male->setChecked(true);
 ui->label->setText("您的性别是: 男");

 // 禁用一个按钮
 // 但这样点了之后文本还是会显示，只是不能被选中了而已
 // ui->radioButton_other->setCheckable(false);
 ui->radioButton_other->setEnabled(false);
```
}

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

void Widget::on_radioButton_male_clicked()
{
ui->label->setText("您的性别是: 男");
}

void Widget::on_radioButton_female_clicked()
{
ui->label->setText("您的性别是: 女");
}

void Widget::on_radioButton_other_clicked()
{
ui->label->setText("您的性别是: 其他");
}

效果：选中一个选项时，其他选项自动取消，并且默认是男，且其他选不了。Label 实时更新选择结果。

实战示例：click, press, release, toggled 的区别

clicked表示一次 "点击"
pressed表示鼠标 "按下"
released 表示鼠标 "释放"
toggled表示按钮状态切换.

#include "widget.h"
#include "ui_widget.h"
#include

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

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

void Widget::on_radioButton_clicked(bool checked)
{
// 此处的 checked 就表示当前 radioButton 的选中状态
qDebug()<<"clicked:"<<checked;
}

void Widget::on_radioButton_2_pressed()
{
qDebug()<<"pressed";
}

void Widget::on_radioButton_3_released()
{
qDebug()<<"released";
}

void Widget::on_radioButton_4_toggled(bool checked)
{
// checked 状态发生改变，就会触发这个信号
qDebug()<<"toggled:"<<checked;
}

运行程序, 可以看到
- clicked 是⼀次鼠标按下+鼠标释放触发的.
- pressed 是鼠标按下触发的.
- released 是鼠标释放触发的.
- toggled 是 checked 属性改变时触发的.(这个是比较适配 QRadioButton 的)

实战示例：单选框分组（多组互斥）

默认情况下，同一父控件下的 RadioButton 会全局互斥，用QButtonGroup可实现分组互斥（如点餐时的汉堡、小食、饮料分组）：

复制代码

#include "widget.h"
#include "ui_widget.h"
#include <QButtonGroup>

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

    // 使用 QButtonGroup 对单选按钮进行分组
    QButtonGroup* group1 = new QButtonGroup(this);
    QButtonGroup* group2 = new QButtonGroup(this);
    QButtonGroup* group3 = new QButtonGroup(this);

    // 把上述单选按钮，放到不同的组
    group1->addButton(ui->radioButton);
    group1->addButton(ui->radioButton_2);
    group1->addButton(ui->radioButton_3);

    group2->addButton(ui->radioButton_4);
    group2->addButton(ui->radioButton_5);
    group2->addButton(ui->radioButton_6);

    group3->addButton(ui->radioButton_7);
    group3->addButton(ui->radioButton_8);
}

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

效果：每组内部互斥，不同组之间可独立选择，符合真实点餐场景。

1.3 CheckBox：复选按钮（多选选择）

QCheckBox适用于 "多选多" 场景（如兴趣爱好、功能开启 / 关闭），支持多个选项同时选中，无默认互斥性。

核心属性与 API：

核心属性 ：checkable（默认 true）、checked（是否选中）；
核心 API ：
- isChecked()：判断是否被选中；
- setChecked(bool flag)：设置选中状态。

实战示例：获取多选结果

拖放 3 个 CheckBox（学习 / 打游戏 / 打工）和 1 个确认按钮；
点击确认按钮时，汇总选中的选项：

#include "widget.h"
#include "ui_widget.h"

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

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

void Widget::on_pushButton_clicked()
{
QString result = "今天你的安排是：";
if(ui->checkBox_study->isChecked())
{
result += ui->checkBox_study->text() + " ";
}
if(ui->checkBox_game->isChecked())
{
result += ui->checkBox_game->text() + " ";
}
if(ui->checkBox_work->isChecked())
{
result += ui->checkBox_work->text() + " ";
}
ui->label->setText(result);
}

效果：可同时选中多个选项，点击确认后汇总并显示结果。

1.4 按钮类控件关键区别与选型

还有一个 QToolButton没讲，他的功能大部分和 QPushButton一致。主要用于工具栏，菜单等场景，这里就先不介绍了。

控件类型	核心特性	适用场景
PushButton	单次触发、无选择状态	确认、提交、取消等操作
RadioButton	互斥选中、单选项	性别、单选选项切换
CheckBox	非互斥选中、多选项	兴趣爱好、功能开启 / 关闭

二. 显示类核心控件：Label（文本与图片展示）

QLabel是 Qt 中最常用的显示控件，支持纯文本、富文本、Markdown、图片等多种展示形式，还可设置对齐、换行、缩进等样式，是信息呈现的 "万能载体"。

核心属性与 API：

文本相关 ：text（显示文本）、textFormat（文本格式）、alignment（对齐方式）、wordWrap（自动换行）、indent（文本缩进）、margin（内边距）；
图片相关 ：pixmap（图片）、scaledContents（图片自适应填充）；
其他特性 ：buddy（关联伙伴控件）、openExternalLinks（打开外部链接）；
核心 API ：
- setText(const QString& text)：设置显示文本；
- setPixmap(const QPixmap& pixmap)：设置显示图片；
- setAlignment(Qt::Alignment alignment)：设置文本 / 图片对齐方式；
- setScaledContents(bool flag)：开启图片自适应 Label 尺寸；
- setBuddy(QWidget buddy)*：关联伙伴控件（点击 Label 激活伙伴）。

实战示例 1：显示不同格式文本

支持纯文本、富文本（HTML 标签）、Markdown 三种格式，满足不同排版需求：

复制代码

#include "widget.h"
#include "ui_widget.h"

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

    // 给第一个 label 设置成纯文本
    ui->label->setTextFormat(Qt::PlainText);
    // ui->label->setText("这是一段纯文本");
    // ui->label->setText("<b>这是一段纯文本</b>");
    ui->label->setText("# 这是一段纯文本");

    // 给第二个 label 设置成富文本
    ui->label_2->setTextFormat(Qt::RichText);
    ui->label_2->setText("<b>这是一段富文本</b>");

    // 给第三个 label 设置成 markdown
    ui->label_3->setTextFormat(Qt::MarkdownText);
    ui->label_3->setText("# 这是一段 Markdown");
}

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

实战示例 2：显示图片并自适应窗口

新增 qrc 资源文件，添加图片（如claw.png）；
代码中设置图片，并实现窗口大小改变时图片同步缩放(虚函数重写，看后面的图解)：

#include "widget.h"
#include "ui_widget.h"
#include
#include

Widget::Widget(QWidget *parent)
: QWidget(parent)
, ui(new Ui::Widget)
{
ui->setupUi(this);
复制代码
```
 // 先把 QLabel 设置和窗口一样大，并且把这个 QLabel 左上角设置到窗口的左上角
 // 让 QLabel 铺满整个窗口
 QRect windowrect = this->geometry(); // window 大小
 ui->label->setGeometry(0,0,windowrect.width(),windowrect.height());

 QPixmap pixmap(":/claw.png");
 ui->label->setPixmap(pixmap);
 // 启动自动拉伸，图片填满整个窗口
 ui->label->setScaledContents(true);
```
}

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

void Widget::resizeEvent(QResizeEvent *event)
{
qDebug()<size();
ui->label->setGeometry(0,0,event->size().width(),event->size().height());
}

效果：图片填充整个 Label，拖动窗口改变大小时，图片同步缩放。

实战示例 3：文本样式精细化设置（对齐、换行、缩进）

通过属性组合实现文本的多样化排版：

复制代码

#include "widget.h"
#include "ui_widget.h"

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);
    // 在构造函数中,给这几个 label 设置不同的属性

    // 设置对齐方式
    ui->label->setText("这是一段文本");
    ui->label->setAlignment(Qt::AlignHCenter | Qt::AlignVCenter);

    // 设置自动换行
    ui->label_2->setText("这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本");
    ui->label_2->setWordWrap(true);

    // 设置缩进
    ui->label_3->setText("这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本这是一段很长的文本");
    ui->label_3->setWordWrap(true);
    ui->label_3->setIndent(50);

    // 设置边距
    ui->label_4->setText("这是一段文本这是一段文本这是一段文本这是一段文本这是一段文本这是一段文本");
    ui->label_4->setWordWrap(true);
    ui->label_4->setMargin(50);
}

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

实战示例 4：关联伙伴控件（提升操作便捷性）

Label 可关联输入框、单选框等控件，点击 Label 即可激活伙伴（如聚焦输入框、选中单选框）：

复制代码

#include "widget.h"
#include "ui_widget.h"

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

    // 设置 label 和 radioButton 伙伴关系
    ui->label->setBuddy(ui->radioButton);
    ui->label_2->setBuddy(ui->radioButton_2);


}

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

效果：按下Alt+A选中 "选项 1"，Alt+B选中 "选项 2"，提升操作效率。

三、总结对比

|------------------|---------------------|----------------------------------------|--------------------|
| 控件名称 | 核心父类 | 核心属性/功能 | 典型应用场景 |
| QRadioButton | QAbstractButton | autoExclusive, QButtonGroup分组 | 单项选择（如性别、支付方式） |
| QCheckBox | QAbstractButton | isTristate, stateChanged() | 多项选择、同意协议、全选框 |
| QLineEdit | QWidget | EchoMode, InputMask, Validator | 用户名、密码、单行条件搜索 |
| QLabel | QFrame | alignment, pixmap, movie, setBuddy | 标签提示、图片/GIF展示、热键导航 |

掌握这些基础控件的特性和配合技巧，能大幅提高 Qt 界面开发的效率与用户体验。

涉及内容总结：

QRadioButton & QCheckBox ：详解了继承结构、互斥分组（QButtonGroup）与三态模式。
QLineEdit & 多行文本框 ：归纳了四种 EchoMode显示模式、输入限制校验与占位符。
QLabel 深入解析 ：总结了从 QObject->QWidget-> QFrame-> QLabel的继承树，按位或对齐方式、图片/GIF 渲染，以及伙伴机制（Buddy System）与快捷键绑定。

Qt 常用 UI 控件详解：从QPushButton到QLabel 核心用法解析

前言：

一、 按钮类控件：交互逻辑的核心载体

1.1 PushButton：最常用的普通按钮

1.2 RadioButton：单选按钮（互斥选择）

1.3 CheckBox：复选按钮（多选选择）

1.4 按钮类控件关键区别与选型

二. 显示类核心控件：Label（文本与图片展示）

三、 总结对比

一、按钮类控件：交互逻辑的核心载体

三、总结对比