在 Qt GUI 开发的世界里,按钮控件是构建交互界面的 "基石"。无论是简单的点击触发、多选一的选项选择,还是多选项的批量勾选,都离不开 QPushButton、QRadioButton 和 QCheckBox 这三大核心按钮控件。今天这篇文章,我们就以 QPushButton 为核心,串联起单选按钮和复选按钮的用法,通过大量实战案例,带大家从 "会用" 到 "精通",真正掌握 Qt 按钮控件的精髓!下面就让我们正式开始吧!

QPushButton 作为 Qt 中最基础也最常用的按钮控件,继承自 QAbstractButton 抽象类 —— 这意味着它和 QRadioButton、QCheckBox 共享着相同的核心属性和信号,但又有着自己独特的交互逻辑。从功能上看,QPushButton 就像一个 "万能开关",既可以触发一次性操作(比如提交表单、关闭窗口),也能实现复杂的状态切换(比如开关按钮、连发按钮),几乎所有带交互的 Qt 界面都能看到它的身影。
从底层实现来看,QPushButton 的核心是事件响应 + 信号发射:当用户通过鼠标点击、键盘快捷键等方式触发按钮时,它会自动发射clicked()信号,我们只需要将这个信号与自定义的槽函数绑定,就能实现 "点击按钮做某事" 的核心逻辑。这种 "信号槽" 机制,也是 Qt 界面开发的灵魂所在。
在动手写代码前,我们先梳理 QPushButton 的核心属性和方法 —— 这些是后续所有实战的基础,务必牢记!
类别 | 属性 / 方法 | 作用说明 |
|---|---|---|
文本控制 | text() / setText(const QString& text) | 获取 / 设置按钮显示的文本(如 "提交"" 取消 ") |
图标控制 | icon() / setIcon(const QIcon& icon) | 获取 / 设置按钮图标(需搭配 QIcon 使用) |
iconSize() / setIconSize(const QSize& size) | 设置图标尺寸(默认 16x16,可根据按钮大小调整) | |
状态控制 | isEnabled() / setEnabled(bool enabled) | 获取 / 设置按钮是否可用(禁用时按钮变灰,无法响应操作) |
isCheckable() / setCheckable(bool checkable) | 设置按钮是否支持 "勾选状态"(开启后点击可保持按下样式) | |
isChecked() / setChecked(bool checked) | 获取 / 设置按钮的勾选状态(仅checkable=true时生效) | |
交互控制 | setShortcut(const QKeySequence& key) | 为按钮设置快捷键(如 Ctrl+S、Enter 键等) |
setAutoRepeat(bool enable) | 开启 / 关闭 "连发模式"(按住按钮持续触发点击事件) | |
setAutoRepeatDelay(int delay) | 设置连发延迟(按住按钮后,延迟多少毫秒开始连发,默认 300ms) | |
setAutoRepeatInterval(int interval) | 设置连发间隔(连发状态下,每隔多少毫秒触发一次,默认 100ms) | |
样式控制 | setStyleSheet(const QString& styleSheet) | 通过 QSS(Qt 样式表)自定义按钮外观(颜色、边框、圆角等) |
我们先从最基础的案例开始 —— 用纯 C++ 代码创建一个 QPushButton,实现 "点击按钮打印日志" 的功能。这个案例虽然简单,但能帮我们理解 QPushButton 的创建流程和信号槽绑定逻辑。
打开 Qt Creator,新建 "Qt Widgets Application" 项目,基类选择QWidget。
修改widget.cpp文件,代码如下:
#include "widget.h"
#include <QPushButton>
#include <QDebug>
#include <QFont>
Widget::Widget(QWidget *parent)
: QWidget(parent)
{
// 1. 创建QPushButton对象,指定父控件为当前Widget
// 父控件设置的好处:自动管理内存,避免内存泄漏;按钮随父控件移动而移动
QPushButton *btn = new QPushButton("点击我打印日志", this);
// 2. 设置按钮的位置和尺寸(x坐标、y坐标、宽度、高度)
// Qt坐标系:父控件左上角为原点(0,0),向右x增加,向下y增加
btn->setGeometry(60, 50, 220, 60);
// 3. 美化按钮:设置字体
QFont btnFont;
btnFont.setFamily("微软雅黑"); // 字体家族
btnFont.setPointSize(14); // 字体大小
btnFont.setBold(true); // 字体加粗
btn->setFont(btnFont);
// 4. 绑定信号槽:按钮点击时触发自定义逻辑
// 信号:QPushButton::clicked()(按钮被点击时发射)
// 槽函数:使用lambda表达式(Qt 5.4+支持,简洁高效)
connect(btn, &QPushButton::clicked, this, []() {
qDebug() << "✅ QPushButton被点击!这是第一个按钮案例~";
});
// 5. 设置窗口属性
this->setFixedSize(350, 180); // 固定窗口大小
this->setWindowTitle("QPushButton基础案例"); // 窗口标题
}
Widget::~Widget()
{
}运行效果
启动程序后,界面上会出现一个带有加粗字体的按钮,点击按钮后,Qt Creator 的 "应用程序输出" 面板会打印出调试信息。

纯文字按钮难免单调,给按钮添加图标能让界面更直观。Qt 中通过QIcon类加载图标资源,再配合setIcon()和setIconSize()方法,就能实现带图标的按钮效果。
resources文件夹,放入一张图标图片(如anno.png);resource.qrc;resource.qrc,点击 "添加前缀",将前缀改为/;resources/anno.png,保存资源文件(资源文件会被编译到程序中,避免路径问题)。
修改widget.cpp,代码如下:
#include "widget.h"
#include "ui_widget.h"
Widget::Widget(QWidget *parent)
: QWidget(parent)
, ui(new Ui::Widget)
{
ui->setupUi(this);
//创建图标对象
QIcon icon(":/anno.png");
//设置图标
ui->pushButton->setIcon(icon);
//设置图标尺寸
ui->pushButton->setIconSize(QSize(50, 50));
}
Widget::~Widget()
{
delete ui;
}运行结果如下:

:开头,后面跟前缀和文件名,例如:/anno.png; 在实际开发中,为常用按钮设置快捷键能大幅提升操作效率。QPushButton 通过setShortcut()方法支持快捷键,既可以用字符串形式(如 "Ctrl+S"),也可以用 Qt 预定义的枚举常量(如Qt::CTRL + Qt::Key_S)。
#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(":/anno.png"));
ui->pushButton_target->setIconSize(QSize(160, 160));
ui->pushButton_up->setIcon(QIcon(":/UP.png"));
ui->pushButton_up->setIconSize(QSize(50, 50));
ui->pushButton_down->setIcon(QIcon(":/Down.png"));
ui->pushButton_down->setIconSize(QSize(50, 50));
ui->pushButton_right->setIcon(QIcon(":/Right.png"));
ui->pushButton_right->setIconSize(QSize(50, 50));
ui->pushButton_left->setIcon(QIcon(":/Left.png"));
ui->pushButton_left->setIconSize(QSize(50, 50));
//直接通过按键名字来设置
// ui->pushButton_up->setShortcut(QKeySequence("w"));
// ui->pushButton_down->setShortcut(QKeySequence("s"));
// ui->pushButton_right->setShortcut(QKeySequence("d"));
// ui->pushButton_left->setShortcut(QKeySequence("a"));
//通过按键的枚举来设置
ui->pushButton_up->setShortcut(QKeySequence(Qt::Key_W));
ui->pushButton_down->setShortcut(QKeySequence(Qt::Key_S));
ui->pushButton_right->setShortcut(QKeySequence(Qt::Key_D));
ui->pushButton_left->setShortcut(QKeySequence(Qt::Key_A));
//开启鼠标点击连发功能
ui->pushButton_up->setAutoRepeat(true);
ui->pushButton_down->setAutoRepeat(true);
ui->pushButton_right->setAutoRepeat(true);
ui->pushButton_left->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());
}
运行代码后,点击键盘上的“W”、“A”、“S”、“D”或者用鼠标点击对应的按键,都能使上方的图片向对应方向移动,并且支持长按连点。需要注意的是,我们在开发时,需要获取图标资源,可以去阿里巴巴的官方矢量图标库免费获取,链接如下:https://www.iconfont.cn/

在实际开发中,经常遇到 "多选一" 的场景(如性别选择、支付方式选择),这时 QRadioButton 就派上用场了。QRadioButton 同样继承自 QAbstractButton,但其核心特性是自动排他性—— 同一组中的 QRadioButton 只能有一个被选中。
核心属性 / 方法 | 作用说明 |
|---|---|
isChecked() / setChecked(bool checked) | 获取 / 设置单选按钮的选中状态(默认未选中) |
setAutoExclusive(bool exclusive) | 设置是否自动排他(默认 true,同一组中只能选一个) |
toggled(bool checked) | 信号:当单选按钮的选中状态变化时发射(参数为当前是否选中) |
需要注意的是,QRadioButton 的 "排他性" 仅针对同一父控件或同一 QButtonGroup中的按钮。如果需要多组单选按钮共存,必须将它们放在不同的父控件(如 QGroupBox)或 QButtonGroup 中。
我们首先通过.ui文件编辑一下界面:

通过编辑QRadioButtonn的槽函数,最终代码如下:
#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()
{
//把label的内容更新
ui->label->setText("您选择的性别为:男");
}
void Widget::on_radioButton_female_clicked()
{
//把label的内容更新
ui->label->setText("您选择的性别为:女");
}
void Widget::on_radioButton_other_clicked()
{
//把label的内容更新
ui->label->setText("您选择的性别为:其他");
}界面上有一个 "性别选择" 分组框,里面包含三个单选按钮,默认选中 "男"。点击不同的单选按钮,控制台会实时打印状态变化,并且会打印最终选中的性别。

clicked信号更适合单选按钮,因为它能直接获取当前选中状态,避免手动判断;setChecked(true)设置默认选中项,提升用户体验。如果需要更灵活地管理单选按钮(如动态添加 / 删除按钮、批量处理信号),可以使用 QButtonGroup 类。QButtonGroup 不具备可视化功能,仅用于逻辑分组,通常与 QGroupBox 配合使用。
先编辑.ui文件如下:

编辑代码如下:
#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;
}运行结果如下:

与 QRadioButton 的 "多选一" 不同,QCheckBox 适用于 "多选多" 的场景(如兴趣爱好选择、权限设置)。它同样继承自 QAbstractButton,但没有排他性,支持多个按钮同时选中,还支持 "三态"(可选,默认两态:选中 / 未选中)。
核心属性 / 方法 | 作用说明 |
|---|---|
isChecked() / setChecked(bool checked) | 获取 / 设置复选按钮的选中状态 |
setTristate(bool tristate) | 设置是否支持三态(默认 false,两态;true 时支持 "部分选中" 状态) |
checkState() / setCheckState(Qt::CheckState state) | 获取 / 设置三态下的状态(Qt::Unchecked:未选中,Qt::PartiallyChecked:部分选中,Qt::Checked:选中) |
toggled(bool checked) | 信号:当复选按钮的选中状态变化时发射(参数为当前是否选中,仅两态有效) |
stateChanged(int state) | 信号:当复选按钮的状态变化时发射(参数为状态值,三态下推荐使用) |
先编辑ui文件:

编辑代码:
#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);
}
控件类型 | 核心用途 | 关键特性 | 视觉样式 | 信号推荐 |
|---|---|---|---|---|
QPushButton | 触发一次性操作(提交、关闭、保存) | 点击后立即弹起;支持图标、快捷键、连发;无排他性 | 矩形按钮(可自定义样式) | clicked() |
QRadioButton | 多选一场景(性别、支付方式) | 自动排他(同一组仅一个选中);支持默认选中 | 圆形单选框 + 文本 | toggled(bool) |
QCheckBox | 多选多场景(兴趣爱好、权限) | 无排他性;支持两态 / 三态;可批量选中 | 方形复选框 + 文本 | stateChanged(int)(三态)、toggled(bool)(两态) |
setEnabled(false))、按钮被其他控件遮挡、按钮没有父控件且未添加到布局。connect(btn, &QPushButton::clicked, this, &Widget::slotFunc)),编译器会检查签名;调试时打印btn->isEnabled()和btn->isVisible()确认状态;始终给按钮指定父控件或添加到布局。:/前缀/文件名;通过setIconSize()设置图标尺寸;重新构建项目(Ctrl+B)确保资源文件被编译。Ctrl+Alt+Del);测试时确保程序在前台;使用QKeySequence::toString()验证快捷键是否正确。setExclusive(true)(默认开启)。checkedButton()方法,或按钮未添加到 QButtonGroup。checkedButton()获取选中按钮,注意强制转换为 QRadioButton*。setTristate(true)),或使用setChecked()而非setCheckState()。setTristate(true),再通过setCheckState(Qt::PartiallyChecked)设置部分选中状态。Qt 的按钮控件虽然基础,但却是构建交互界面的关键。只有熟练掌握这些基础控件的用法,才能在复杂项目中灵活运用,开发出高效、美观、易用的 Qt 应用程序。希望本文能成为你 Qt 学习路上的垫脚石,祝你在 Qt 开发的道路上越走越远!