Qt Widgets窗口部件

Qt中把没有嵌入到其他部件中的部件称为窗口，一般窗口都有边框和标题栏。QMainWindow和大量的QDialog子类是最一般的窗口类型。

窗口是没有父部件的部件，所以又称为顶级部件（top-level widget）。与其相对的是非窗口部件，又称为子部件（child widget）。在Qt中大部分部件被用作子部件，嵌入在别的窗口中。

基础窗口部件QWidget

QWidget类是所有用户界面类的基类，被称为基础窗口部件

QWidget(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

• parent就是指父窗口部件，默认值为nullptr，表明没有父窗口
• f参数是Qt::WindowFlags类型的，它是Qt::WindowType枚举类型值的按位或组合。
  • Qt::WindowType枚举类型用来为部件指定各种窗口系统属性
  • 窗口标志Qt::WindowFlags可以是多个窗口类型枚举值进行按位或操作
• QWidget中还有一个setWindowState()函数用来设置窗口的状态，其参数由Qt::WindowStates指定，是Qt::WindowState枚举类型值的按位或组合。Qt::WindowState包括：
  • 最大化Qt::WindowMaximized
  • 最小化Qt::WindowMinimized
  • 全屏显示Qt::WindowFullScreen
  • 活动窗口Qt::WindowActive
  • 默认值为正常状态Qt::WindowNoState

对于窗口的大小和位置，根据是否包含边框和标题栏两种情况，要用不同的函数来获取。这里的函数分为两类，一类是包含框架的，一类是不包含框架的：

• 包含框架：x()、y()、frameGeometry()、pos()和move()等函数；

• 不包含框架：geometry()、width()、height()、rect()和size()等函数。

QFrame类族

QFrame类是带有边框的部件的基类。它的子类包括：

• QLabel：标签部件

• QLCDNumber：数码管

• QSplitter：分割面板

• QStackedWidget：堆叠面板

• QToolBox：折叠面板

• QAbstractScrollArea：所有带有滚动区域的部件类的抽象基类。QAbstractScrollArea的子类中包含常用的文本编辑器QTextEdit类和各种项目视图类。

QFrame类的一项主要功能就是用来实现不同的边框效果，这主要是由边框形状（Shape）和边框阴影（Shadow）组合来形成的。

QFrame类中定义的主要边框形状包括：

• QFrame::NoFrame：不进行绘制
• QFrame::Box：在它的内容四周绘制一个边框
• QFrame::Panel：绘制一个面板，是内容表现为凸起或凹陷
• QFrame::StyledPanel：绘制一个矩形面板，其效果依赖于当前的GUI样式
• QFrame::HLine：绘制一条水平线，无任何框架
• QFrame::VLine：绘制一条垂直线，无任何框架
• QFrame::WinPanel：绘制一个类似于Windows 2000中的矩形面板，可以凸起或凹陷

边框阴影主要包括：

• QFrame::Plain

• QFrame::Raised

• QFrame::Sunken；

示例：

ui->frame->setFrameShape(QFrame::Box);
ui->frame->setFrameShadow(QFrame::Sunken);
ui->frame->setLineWidth(5);
ui->frame->setMidLineWidth(10);

Button部件

QAbstractButton类是按钮部件的抽象基类，提供了按钮的通用功能。它的子类包括：

• 复选框QCheckBox
• 标准按钮QPushButton
• 单选框按钮QRadioButton
• 工具按钮QToolButton

按钮最常见的应用就是通过单击或双击来实现一些功能，在Qt中，这种应用是通过信号和槽的机制来实现的。

QLineEdit部件

行编辑器QLineEdit部件是一个单行的文本编辑器，它允许用户输入和编辑单行的纯文本内容，而且提供了一系列有用的功能，包括撤销与恢复、剪切和拖放等操作。

QLineEdit有4种显示模式（echoMode），可以通过echoMode属性更改它们，分别是：

• Normal正常显示输入的信息
• NoEcho不显示任何输入，这样可以保证不泄露输入的字符位数
• Password显示为密码样式，就是以小黑点或星号之类的字符代替输入的字符
• PasswordEchoOnEdit在编辑时显示正常字符，其他情况下显示为密码样式。

QLineEdit提供了输入掩码（setInputMask()）来限制输入的内容。可以使用一些特殊的字符来设置输入的格式和内容，这些字符中有的起限制作用且必须要输入一个字符，有的只是起限制作用，但可以不输入字符而是以空格代替。

例如：“>AA-90-bb-!aa\#H;*”，它表示的含义为：
“>”号表明后面输入的字母自动转为大写；
“AA”表明开始必须输入两个字母，因为有前面的“>”号的作用，所以输入的这两个字母会自动变为大写；
“-”号为分隔符，直接显示，该位不可输入；“9”表示必须输入一个数字；
“0”表示输入一个数字，或者留空；
“bb”表示这两位可以留空，或者输入两个二进制字符，即0或1；
“！”表明停止大小写转换，就是在最开始的“>”号不再起作用；
“aa”表示可以留空，或者输入两个字母；
“\#”表示将“#”号作为分隔符，因为“#”号在这里有特殊含义，所以前面要加上“\”号；
“H”表明必须输入一个十六进制的字符；
“;*”表示用“*”号来填充空格。

在QLineEdit中可以使用验证器（validator）来对输入进行约束。还可以使用正则表达式来设置更强大的字符约束。

// 新建验证器，指定范围为100~999
QValidator *validator = new QIntValidator(100, 999, this);
// 在行编辑器中使用验证器
ui->lineEdit3->setValidator(validator);

//正则表达
QRegularExpression rx("-?\\d{1,3}");
//新建验证器
QValidator *validator = new QRegularExpressionValidator(rx, this);
// 在行编辑器中使用验证器
ui->lineEdit3->setValidator(validator);

QLineEdit中也提供了强大的自动补全功能，这是利用QCompleter类实现的。

QStringList wordList;
wordList << "Qt" << "Qt Creator" << tr("你好");
QCompleter *completer = new QCompleter(wordList, this);   // 新建自动完成器
completer->setCaseSensitivity(Qt::CaseInsensitive);       // 设置大小写不敏感
ui->lineEdit4->setCompleter(completer);

QAbstractSpinBox部件

QAbstractSpinBox类是一个抽象基类，提供了一个数值设定框和一个行编辑器来显示设定值。它有3个子类用来完成设定：

• 日期时间QDateTimeEdit

• 整数QSpinBox

• 浮点数QDoubleSpinBox

QDateTimeEdit类有两个子类QDateEdit和QTimeEdit：

• QtimeEdit用来设置时间，可以使用setDisplayFormat()来设置显示格式，例如“h:mm:ssA”，这样可以使用12小时制来进行显示
• QDateEdit使用setCalendarPopup(true)可以使用弹出的日历部件来设置日期。

示例：

// 设置时间为现在的系统时间
ui->dateTimeEdit->setDateTime(QDateTime::currentDateTime());
// 设置时间的显示格式
ui->dateTimeEdit->setDisplayFormat(tr("yyyy年MM月dd日ddd HH时mm分ss秒"));

QAbstractSlider部件

QAbstractSlider类用于提供区间内的一个整数值，它有一个滑块，可以定位到一个整数区间的任意值。该类是一个抽象基类，它有3个子类：

• QScrollBar：垂直 / 水平滚动条控件，一般用于QScrollArea类中实现滚动区域

• QSlider：分水平 / 垂直，用于直观调节数值（音量、透明度、缩放比例等）

• QDial：旋钮调节器

QAbstractSlider提供的属性：

• maximum属性用来设置最大值，minimum为最小值；
• singleStep属性是每步的步长，默认是1，就是按下方向键后其数值增加或者减少1；
• pageStep是每页的步长，默认是10，就是按下PageUp或者PageDown按键后，其数值增加或者减少10；
• value与sliderPosition是当前值；
• tracking是设置是否跟踪，默认为是，就是在拖动滑块时，每移动一个刻度，都会发射valueChanged()信号，如果选择否，则只有拖动滑块释放时才发射该信号；
• orientation是设置部件的方向，有水平和垂直两种选择；
• invertedAppearance属性是设置滑块所在的位置，选中后，滑块默认会在最右端。
• invertedControls是设置反向控制，比如默认是向上方向键是增大，向下方向键是减小，如果选中这个属性，那么控制就会正好反过来。

Slider包含了自己的两个属性：

• 属性tickPosition：设置显示刻度的位置，默认是不显示刻度

• 属性tickInterval：设置刻度的间隔

Dial包含：

• 属性wrapping：用来设置是否首尾相连；
• 属性notchTarget：用来设置刻度之间的间隔；
• 属性notchesVisible：用来设置是否显示刻度。

对话框

QDialog类是所有对话框窗口类的基类。对话框窗口是一个经常用来完成短小任务或者和用户进行简单交互的顶层窗口。按照运行对话框时是否还可以和该程序的其他窗口进行交互，对话框常被分为两类：模态的（modal）和非模态的（modeless）。

• 模态对话框：在没有关闭它之前，不能再与同一个应用程序的其他窗口进行交互，比如新建项目时弹出的对话框。

QDialog dialog(this);
dialog.exec();
或者：
QDialog *dialog = new QDialog(this);
dialog->setModal(true);
dialog->show();

• 非模态对话框：既可以与它交互，也可以与同一程序中的其他窗口交互，如一些软件中的查找替换对话框。

QDialog *dialog = new QDialog(this);
dialog->show();

标准对话框

Qt提供了一些常用的对话框类型，它们全部继承自QDialog类，并增加了自己的特色功能。

颜色对话框QColorDialog

颜色对话框类QColorDialog提供了一个可以获取指定颜色的对话框部件。需要添加#include <QColorDialog>头文件。可以使用QColorDialog的静态函数getColor()来获取颜色，它的3个参数的作用分别是：设置初始颜色、指定父窗口和设置对话框标题。

QColor color = QColorDialog::getColor(Qt::red, this, tr("颜色对话框"));
qDebug() << "color: " << color;

如果想要更灵活的设置时，则可以先创建对象，然后进行各项设置

QColorDialog dialog(Qt::red, this);                  // 创建对象
dialog.setOption(QColorDialog::ShowAlphaChannel);    // 显示alpha选项
dialog.exec();                                       // 以模态方式运行对话框
QColor color = dialog.currentColor();                // 获取当前颜色
qDebug()<<"color:"<<color;                           // 输出颜色信息

错误信息对话框QErrorMessage

QErrorMessage 专门用于批量展示错误弹窗，独有记忆功能：弹窗底部自带复选框「不再显示此消息」，勾选后同一条错误后续不会再弹出。

继承自 QDialog，全局单例模式，适合程序运行时批量报错。

• 全局单例快速弹窗（最常用）

// 一行弹出错误，自动使用全局对象
QErrorMessage::showMessage("文件读取失败：找不到目标路径");

• 手动获取实例，自定义控制

// 获取全局单例
QErrorMessage *errDlg = QErrorMessage::qtHandler();

// 展示错误
errDlg->showMessage("网络连接超时，请检查端口");

// 重置所有记忆（取消所有“不再提示”记录）
errDlg->clear();

• 富文本报错（带颜色、换行、标签，支持 HTML）

QErrorMessage::showMessage(
    "<font color='red'>严重错误</font><br/>"
    "数据库连接失败<br/>"
    "错误码：E1001"
);

• 绑定全局消息处理器（捕获 qDebug/qWarning/qCritical）

// 全局日志全部弹出错误框,把 Qt 所有日志自动转发到 QErrorMessage 弹窗
qInstallMessageHandler(QErrorMessage::qtHandler()->message);

输入对话框QInputDialog

QInputDialog 专门用来弹出模态窗口，让用户输入文本、数字、下拉选择项，全部提供静态快捷函数，一行代码就能弹出，无需手动 new 控件。

内置以下输入模式：

• 单行文本输入
• 多行文本输入
• 整数输入
• 浮点数输入
• 下拉列表选择

返回两个信息：输入的值 + 用户是否点击确认（bool）。

示例（获取单行字符串-getText）：

// 参数：父窗口、标题、提示文字、默认输入、输出ok标记
bool ok;
QString text = QInputDialog::getText(
    this,
    "输入名称",
    "请输入文件名：",
    QLineEdit::Normal, // 密码模式填 Password
    "默认文本",
    &ok
);
if (ok)
{
    // 用户点了确定
    qDebug() << "输入内容：" << text;
}
else
{
    // 用户点取消
}

示例（获取多行文本-getMultiLineText）：

bool ok;
QString content = QInputDialog::getMultiLineText(
    this,
    "备注",
    "请输入详细描述：",
    "初始多行文字\n第二行",
    &ok
);

示例（获取整数-getInt）：

bool ok;
int num = QInputDialog::getInt(
    this,
    "设置数量",
    "请输入数值：",
    5,    // 默认值
    0,    // 最小值
    100,  // 最大值
    1,    // 增减步长
    &ok
);

示例（获取浮点数-getDouble）：

bool ok;
double val = QInputDialog::getDouble(
    this,
    "设置比例",
    "缩放系数：",
    1.0,   // 默认
    0.01,  // 最小
    10.0,  // 最大
    2,     // 保留2位小数
    &ok
);

示例（下拉选择-getItem）（给出候选列表，只能选不能自定义输入）：

bool ok;
QStringList items = {"苹果", "香蕉", "橙子", "葡萄"};
QString select = QInputDialog::getItem(
    this,
    "选择水果",
    "请选择一项：",
    items,
    0,        // 默认选中索引
    false,    // true允许手动编辑输入，false只能下拉选
    &ok
);

高级控制，手动创建对象：

QInputDialog dialog(this);
dialog.setWindowTitle("自定义输入框");
dialog.setLabelText("请输入密钥：");
dialog.setInputMode(QInputDialog::TextInput);
dialog.setTextEchoMode(QLineEdit::Password);
dialog.setOkButtonText("确认提交");
dialog.setCancelButtonText("放弃");

if (dialog.exec() == QDialog::Accepted)
{
    QString res = dialog.textValue();
}

setInputMode 可选：

• TextInput 文本
• IntInput 整数
• DoubleInput 浮点数

字体对话框QFontDialog

QFontDialog 提供系统标准字体选择弹窗，可选择字体家族、字号、加粗、斜体、下划线、删除线、颜色，分两种用法：静态一行调用（推荐） / 实例化自定义弹窗。

示例（getFont () 获取字体）：

bool ok;
// 参数：&ok标记、默认字体、父窗口、窗口标题
QFont font = QFontDialog::getFont(
    &ok,
    QFont("微软雅黑",12), // 打开时默认选中的字体
    this,
    "选择字体样式"
);

if(ok)
{
    // 用户点击确定，使用font
    qDebug() << "字体：" << font.family()
             << "字号：" << font.pointSize()
             << "加粗：" << font.bold();
}
else
{
    // 用户取消
}

示例（开启字体颜色选择框）：默认弹窗没有颜色选项，传入第 5 个参数开启颜色

bool ok;
QFont font = QFontDialog::getFont(&ok, QFont(), this, "选择字体", true);
// 最后一个true = 显示颜色选择器

示例（手动创建对象）：适合修改按钮文字、监听实时变化、限制可选字体

QFontDialog dlg(this);
dlg.setWindowTitle("自定义字体面板");
dlg.setCurrentFont(QFont("宋体",14));
dlg.setOption(QFontDialog::ShowColorDialog); // 显示颜色选择

// 实时监听字体拖动改变
connect(&dlg, &QFontDialog::currentFontChanged, this, [](const QFont &f){
    qDebug() << "实时预览字体：" << f.family();
});

if(dlg.exec() == QDialog::Accepted)
{
    QFont selFont = dlg.selectedFont();
}

//可选配置 Options
dlg.setOption(QFontDialog::NoButtons);        // 隐藏确定取消按钮
dlg.setOption(QFontDialog::ShowColorDialog);  // 显示字体颜色
dlg.setOption(QFontDialog::ScalableFonts);    // 只显示可缩放矢量字体
dlg.setOption(QFontDialog::NonScalableFonts); // 显示点阵字体

文件对话框QFileDialog

QFileDialog 是 Qt 标准文件 / 文件夹选择弹窗，支持：

• 打开单个文件、多选文件
• 选择文件夹目录
• 保存文件（自动提示覆盖）

提供静态快捷方法（一行调用，最常用），也支持实例化自定义过滤、标题、布局。

示例（打开单个文件 getOpenFileName）：

bool ok;
// 参数：父窗口、标题、默认打开目录、文件过滤器、输出选中文件、选项
QString filePath = QFileDialog::getOpenFileName(
    this,
    "打开文件",
    QDir::homePath(), // 默认路径：用户主目录
    "文本文件(*.txt);;图片(*.png *.jpg *.bmp);;所有文件(*.*)",
    nullptr,
    QFileDialog::ReadOnly
);

if (!filePath.isEmpty())
{
    qDebug() << "选中文件：" << filePath;
}

示例（多选文件 getOpenFileNames）：返回字符串列表，可按住 Ctrl 多选

QStringList files = QFileDialog::getOpenFileNames(
    this,
    "多选文件",
    "./",
    "图片(*.png *.jpg)"
);
for (auto &path : files)
{
    qDebug() << path;
}

示例（选择文件夹 getExistingDirectory）：只选目录，不能选文件

QString dir = QFileDialog::getExistingDirectory(
    this,
    "选择文件夹",
    QDir::currentPath(),
    QFileDialog::ShowDirsOnly | QFileDialog::DontResolveSymlinks
);

示例（保存文件 getSaveFileName）：自带覆盖弹窗提示

QString savePath = QFileDialog::getSaveFileName(
    this,
    "保存文件",
    "untitled.txt", // 默认文件名
    "文本(*.txt)"
);
if (!savePath.isEmpty())
{
    // 执行写入文件逻辑
}

"文本文件(*.txt);;C++源码(*.h *.cpp);;所有文件(*.*)"

高级使用方法：适合自定义按钮、监听选中变化、多条件过滤

QFileDialog dlg(this);
dlg.setWindowTitle("自定义文件窗口");
dlg.setDirectory("./");
// 模式：打开文件 / 保存 / 选择文件夹
dlg.setFileMode(QFileDialog::ExistingFiles); // 多选文件
dlg.setNameFilter("图片(*.png *.jpg)");
// 显示详情视图
dlg.setViewMode(QFileDialog::Detail);

// 实时选中变化信号
connect(&dlg, &QFileDialog::currentChanged, this, [](const QString &path){
    qDebug() << "当前选中：" << path;
});

if (dlg.exec() == QDialog::Accepted)
{
    QStringList paths = dlg.selectedFiles();
}

FileMode 枚举：

• AnyFile：任意文件（可输入不存在文件名，保存用）
• ExistingFile：单个存在文件
• ExistingFiles：多个存在文件
• Directory：文件夹，允许选文件
• ExistingDirectory：仅文件夹

消息对话框QMessageBox

QMessageBox 是最常用的标准弹窗，用于提示信息、警告、错误、询问确认、选择操作。

提供两套用法：

1. 静态快捷函数（一行弹出，90% 场景使用）
2. 实例化自定义弹窗（多按钮、自定义文本图标）

四大静态快捷弹窗（极简写法）：

• 信息提示 information：普通成功 / 通知提示，蓝色 i 图标

QMessageBox::information(this, "提示", "操作执行成功！");

• 警告提示 warning：黄色感叹号，提醒风险但不致命

QMessageBox::warning(this, "警告", "文件未保存，关闭会丢失修改！");

错误提示 critical：红色叉号，程序异常、失败

QMessageBox::critical(this, "错误", "数据库连接失败，请检查网络！");

询问确认 question：问号图标，返回用户点击的按钮枚举（Yes/No/Cancel）

// 返回值：QMessageBox::Yes / No / Cancel
int ret = QMessageBox::question(
    this,
    "确认删除",
    "确定要删除这条记录吗？删除后无法恢复！",
    QMessageBox::Yes | QMessageBox::No, // 显示哪些按钮
    QMessageBox::No // 默认高亮按钮
);

if(ret == QMessageBox::Yes)
{
    qDebug() << "用户确认删除";
}
else if(ret == QMessageBox::No)
{
    qDebug() << "用户取消操作";
}

手动创建对象（高级自定义）：适合于多按钮、自定义详情文本、自定义图标、修改按钮文字

QMessageBox box(this);
box.setWindowTitle("自定义弹窗");
box.setIcon(QMessageBox::Question);
box.setText("是否保存当前修改？");
box.setInformativeText("如果不保存，本次编辑内容将会丢失。");
box.setDetailedText("日志详情：\n文件路径：D:/test.txt\n修改时间：2026-07-01");

// 添加多个按钮
box.addButton("保存", QMessageBox::AcceptRole);
box.addButton("不保存", QMessageBox::DestructiveRole);
box.addButton("取消", QMessageBox::RejectRole);

int res = box.exec();
if(res == 0)
{
    // 点击保存按钮
}

进度对话框QProgressDialog

进度对话框QProgressDialog对一个耗时较长操作的进度提供了反馈。先添加#include <QProgressDialog>头文件。转到“进度对话框”按钮的单击信号槽，更改如下：

QProgressDialog dialog(tr("文件复制进度"), tr("取消"), 0, 50000, this);
dialog.setWindowTitle(tr("进度对话框"));       // 设置窗口标题
dialog.setWindowModality(Qt::WindowModal);     // 将对话框设置为模态
dialog.show();
for(int i=0; i<50000; i++) {                   // 演示复制进度
    dialog.setValue(i);                        // 设置进度条的当前值
    QCoreApplication::processEvents();         // 避免界面冻结
    if(dialog.wasCanceled()) break;            // 按下取消按钮则中断
}
dialog.setValue(50000);                       // 这样才能显示100%，因为for循环中少加了一个数
qDebug() << tr("复制结束！");

向导对话框QWizard

QWizard 是 Qt 多步骤分步向导（安装程序、初始化配置、新建项目向导），由多个 QWizardPage 页面组成，自带上一步 / 下一步 / 完成 / 取消按钮，自动管理页面切换逻辑。

适用场景：软件初始化、安装流程、多参数配置、新建工程引导。

/*****头文件自定义页面*****/
#include <QWizard>
#include <QWizardPage>
#include <QLineEdit>
#include <QLabel>
#include <QVBoxLayout>

// 第1页：输入用户名
class Page1 : public QWizardPage
{
public:
    Page1()
    {
        setTitle("第一步：账号信息");
        QVBoxLayout *lay = new QVBoxLayout(this);
        QLabel *lab = new QLabel("请输入用户名：");
        QLineEdit *edit = new QLineEdit;
        lay->addWidget(lab);
        lay->addWidget(edit);
        // 注册全局字段
        registerField("userName", edit);
    }

    bool validatePage() override
    {
        QString name = field("userName").toString();
        if(name.isEmpty())
        {
            QMessageBox::warning(this, "提示", "用户名不能为空！");
            return false;
        }
        return true;
    }
};

// 第2页：设置数量
class Page2 : public QWizardPage
{
public:
    Page2()
    {
        setTitle("第二步：参数设置");
        QVBoxLayout *lay = new QVBoxLayout(this);
        QLabel *lab = new QLabel("数量：");
        QLineEdit *edit = new QLineEdit("10");
        lay->addWidget(lab);
        lay->addWidget(edit);
        registerField("count", edit);
    }
};

// 第3页：完成页
class Page3 : public QWizardPage
{
public:
    Page3()
    {
        setTitle("完成");
        QVBoxLayout *lay = new QVBoxLayout(this);
        QLabel *lab = new QLabel("配置完成，点击完成保存");
        lay->addWidget(lab);
    }
};




/*****弹出向导*****/
void MainWindow::openWizard()
{
    QWizard wizard(this);
    wizard.setWindowTitle("初始化配置向导");
    wizard.setWizardStyle(QWizard::ModernStyle);

    // 添加页面，返回页面ID（0、1、2）
    wizard.addPage(new Page1);
    wizard.addPage(new Page2);
    wizard.addPage(new Page3);

    // 执行向导，点击完成返回Accepted
    if(wizard.exec() == QDialog::Accepted)
    {
        QString user = wizard.field("userName").toString();
        int cnt = wizard.field("count").toInt();
        qDebug() << "用户：" << user << " 数量：" << cnt;
    }
}