11_常用控件速查（上）：QPushButton、QLabel、QLineEdit、QComboBox控件是界面的短期状

常用控件速查（上）：QPushButton、QLabel、QLineEdit、QComboBox

引言

从本章开始，我们进入 Qt Widgets 最常见的一层：控件。按钮负责发起动作，标签负责展示信息，单行编辑框负责收集输入，下拉框负责在有限选项中做选择。它们看似简单，却正好覆盖了桌面软件中最典型的交互闭环：显示 -> 输入 -> 选择 -> 提交 -> 反馈。

本文面向 Qt 6 Widgets。学习顺序刻意安排为：先运行一个完整示例，再分别认识四个控件的常用 API 和信号，最后沿着一次交互追踪到源码层面的调用。读完后应能：

用 C++ 创建并布局四个控件；
区分“程序修改”和“用户操作”触发的信号；
用成员槽、Lambda、qOverload 三种方式安全连接信号槽；
用 text()、currentData() 等 API 读取控件状态；
从公开 API 追踪到事件处理、信号发射与槽调用的大致路径；
避免把控件指针、业务状态和界面状态混在一起。

在这里插入图片描述

图 1：四个控件都直接或间接继承 QWidget，但它们背后协作的对象不同。初学时只需操作公开类；读源码时再理解虚线所示的内部对象。

一、先会用：一个可运行的“用户资料”小窗口

先不把注意力分散到多个小片段。下面用一个小窗口贯穿全文：用户输入昵称、选择城市，点击“保存”，状态标签给出反馈；“接收通知”按钮则展示可选中按钮的用法。

1.1 CMake 配置

新建一个 Qt Widgets 项目，CMakeLists.txt 最小内容如下：

cmake_minimum_required(VERSION 3.21)
project(widget_controls_demo LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Widgets)

qt_standard_project_setup()

qt_add_executable(widget_controls_demo
    main.cpp
)

target_link_libraries(widget_controls_demo PRIVATE Qt6::Widgets)

set_target_properties(widget_controls_demo PROPERTIES
    CXX_STANDARD 17
    CXX_STANDARD_REQUIRED ON
)

这里仍然使用前几章的 QApplication、QWidget 和布局管理器。四个控件都属于 Qt6::Widgets，不需要分别链接额外模块。

1.2 完整代码

把下面代码保存为 main.cpp 后即可构建运行：

#include <QApplication>
#include <QComboBox>
#include <QFormLayout>
#include <QLabel>
#include <QLineEdit>
#include <QPushButton>
#include <QRegularExpression>
#include <QRegularExpressionValidator>
#include <QVBoxLayout>
#include <QWidget>

class ProfileWidget : public QWidget
{
    Q_OBJECT

public:
    explicit ProfileWidget(QWidget *parent = nullptr)
        : QWidget(parent)
    {
        setWindowTitle(tr("用户资料"));
        resize(420, 250);

        auto *titleLabel = new QLabel(tr("创建你的资料"), this);
        titleLabel->setStyleSheet("font-size: 20px; font-weight: 600;");

        nameEdit = new QLineEdit(this);
        nameEdit->setPlaceholderText(tr("2 到 12 个中文、字母或数字"));
        nameEdit->setClearButtonEnabled(true);
        nameEdit->setMaxLength(12);
        auto *nameValidator = new QRegularExpressionValidator(
            QRegularExpression("[A-Za-z0-9\\u4e00-\\u9fa5]{2,12}"), this);
        nameEdit->setValidator(nameValidator);

        cityCombo = new QComboBox(this);
        cityCombo->addItem(tr("请选择城市"), QString());
        cityCombo->addItem(tr("北京"), "beijing");
        cityCombo->addItem(tr("上海"), "shanghai");
        cityCombo->addItem(tr("深圳"), "shenzhen");

        notifyButton = new QPushButton(tr("接收通知"), this);
        notifyButton->setCheckable(true);
        notifyButton->setToolTip(tr("点击切换通知订阅状态"));

        saveButton = new QPushButton(tr("保存"), this);
        saveButton->setDefault(true);
        saveButton->setEnabled(false);

        statusLabel = new QLabel(tr("请填写昵称并选择城市"), this);
        statusLabel->setWordWrap(true);
        statusLabel->setStyleSheet("color: #526a7d;");

        auto *formLayout = new QFormLayout;
        formLayout->addRow(tr("昵称："), nameEdit);
        formLayout->addRow(tr("城市："), cityCombo);
        formLayout->addRow(QString(), notifyButton);

        auto *rootLayout = new QVBoxLayout(this);
        rootLayout->addWidget(titleLabel);
        rootLayout->addLayout(formLayout);
        rootLayout->addWidget(saveButton);
        rootLayout->addWidget(statusLabel);

        // 用户每次编辑昵称或切换城市时，重新判断保存按钮是否可用。
        connect(nameEdit, &QLineEdit::textChanged,
                this, &ProfileWidget::updateSaveButton);
        connect(cityCombo, qOverload<int>(&QComboBox::currentIndexChanged),
                this, &ProfileWidget::updateSaveButton);

        connect(notifyButton, &QPushButton::toggled, this,
                [this](bool checked) {
                    statusLabel->setText(checked
                        ? tr("已开启通知；继续填写资料后保存。")
                        : tr("通知已关闭；继续填写资料后保存。"));
                });

        connect(saveButton, &QPushButton::clicked,
                this, &ProfileWidget::saveProfile);
    }

private slots:
    void updateSaveButton()
    {
        const bool nameIsAcceptable = nameEdit->hasAcceptableInput();
        const bool cityWasSelected = !cityCombo->currentData().toString().isEmpty();
        saveButton->setEnabled(nameIsAcceptable && cityWasSelected);
    }

    void saveProfile()
    {
        const QString name = nameEdit->text();
        const QString cityCode = cityCombo->currentData().toString();
        const bool wantsNotifications = notifyButton->isChecked();

        statusLabel->setText(
            tr("已保存：%1，城市代码：%2，通知：%3")
                .arg(name, cityCode,
                     wantsNotifications ? tr("开启") : tr("关闭")));
    }

private:
    QLineEdit *nameEdit = nullptr;
    QComboBox *cityCombo = nullptr;
    QPushButton *notifyButton = nullptr;
    QPushButton *saveButton = nullptr;
    QLabel *statusLabel = nullptr;
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    ProfileWidget window;
    window.show();

    return app.exec();
}

这个例子里控件都是 ProfileWidget 的子对象。窗口析构时，QObject 的对象树会依次析构它们，因此这里不需要手工 delete。QFormLayout 被放进 rootLayout，而 rootLayout 安装在窗口上，也会由布局体系接管。

如果你把类声明和实现拆到 profile_widget.h/.cpp，并让 CMake 的 AUTOMOC 自动运行，就不需要在 .cpp 末尾写 #include "main.moc"。这个包含仅适合本章为了便于复制而写在单文件中的 Q_OBJECT 类。

二、四个控件各自负责什么

控件	主要职责	最常见的读取 API	典型用户信号
`QPushButton`	发起一个命令，或切换一个二元状态	`isChecked()`	`clicked(bool)`、`toggled(bool)`
`QLabel`	显示只读文本、图片、富文本	`text()`	通常不承担业务交互
`QLineEdit`	输入与编辑一行文本	`text()`	`textEdited(const QString &)`、`returnPressed()`
`QComboBox`	从候选项中选择一个值	`currentData()`、`currentText()`	`activated(int)`、`currentIndexChanged(int)`

不要把这张表理解为“每个控件只用一个函数”。它只是帮助你先建立职责边界：按钮表示动作，标签表示结果，编辑框表示自由输入，下拉框表示有限选择。

三、QPushButton：把用户动作变成命令

QPushButton 继承自 QAbstractButton。因此 clicked()、pressed()、released()、toggled() 等大多数行为并不是 QPushButton 独有的，QToolButton、QCheckBox 等按钮类也共享这套机制。

3.1 最小使用

auto *deleteButton = new QPushButton(tr("删除"), this);
deleteButton->setEnabled(false);       // 当前不可点击
deleteButton->setToolTip(tr("删除当前记录"));

auto *saveButton = new QPushButton(tr("保存"), this);
saveButton->setIcon(QIcon(":/icons/save.svg"));

connect(deleteButton, &QPushButton::clicked, this, &ProfileWidget::deleteCurrentRecord);

按钮的显示文字由构造函数或 setText() 指定；

setEnabled(false) 会同时让按钮呈现禁用外观并拒绝用户输入。不要只在槽函数里判断“能不能执行”，而把本就不允许的动作禁用掉，用户体验更清晰。

QPushButton 不只是文字按钮，也可以同时显示图标和文字。在桌面应用中，常见做法是用SetIcon()图标强化动作含义，同时保留文字保证可理解性。

3.2 `clicked`、`pressed`、`released`、`toggled` 怎么选

信号	何时发出	适合做什么
`pressed()`	按钮刚被按下	需要立即视觉或临时反馈的场景
`released()`	鼠标或键盘操作释放	少见；通常优先用 `clicked()`
`clicked(bool checked)`	完成一次点击；也可由 `click()` 触发	提交、打开窗口、执行命令
`toggled(bool checked)`	可选中状态发生改变	订阅开关、显示/隐藏面板

普通命令按钮使用 clicked()；有持续状态的按钮先 setCheckable(true)，再监听 toggled(bool)。clicked(bool) 的参数是当前选中状态；对不可选中按钮，它始终是 false。

auto *previewButton = new QPushButton(tr("预览"), this);
previewButton->setCheckable(true);

connect(previewButton, &QPushButton::toggled, this,
        [this](bool enabled) {
            previewPanel->setVisible(enabled);
        });

3.3 默认按钮不是“自动保存”

setDefault(true) 用于设置 QDialog 中的默认按钮。

当对话框存在默认按钮时，用户按 Enter/Return 可以激活该按钮。它不意味着窗口一打开就会调用槽函数，也不意味着每次输入都会自动保存。需要注意：

default 按钮机制主要针对 QDialog；
普通 QWidget 不应把 setDefault() 当作通用的 Enter 快捷键机制；
如果只是希望响应 Enter，应根据场景使用 QLineEdit::returnPressed()、QShortcut 等机制。

四、QLabel：只读信息的展示出口

QLabel 是展示控件。它适合标题、字段名、说明、状态、图标与缩略图；它不是输入控件，也不适合承担复杂富文本编辑。

4.1 文本、换行、富文本边界与控制内容位置

auto *hintLabel = new QLabel(tr("密码至少包含 8 个字符。"), this);
hintLabel->setWordWrap(true);
hintLabel->setTextInteractionFlags(Qt::TextSelectableByMouse);

statusLabel->setText(tr("正在连接服务器..."));

当文本会随着窗口宽度变化时，使用 setWordWrap(true)。需要让用户复制错误信息时，使用 Qt::TextSelectableByMouse。QLabel 能识别一部分 HTML 富文本，但业务输入不应直接拼进 HTML；至少要用 toHtmlEscaped() 转义，避免文本被当作标签解释。

const QString userName = nameEdit->text();
label->setText(tr("欢迎，<b>%1</b>").arg(userName.toHtmlEscaped()));

常用的还有设置文本内容位置setAlignment()

auto *label = new QLabel(tr("处理中..."), this);
label->setAlignment(Qt::AlignCenter);

Qt::AlignLeft		//左对齐
Qt::AlignRight		//右对齐
Qt::AlignHCenter	//横向居中对齐
Qt::AlignTop		//顶部对齐
Qt::AlignVCenter	//垂直居中对齐
Qt::AlignBottom		//底部对齐

QLabel 的“控件大小”和“文字绘制位置”是两个概念。setAlignment() 控制的是内容在 QLabel 内部如何对齐。

4.2 图片与高 DPI

显示图片时使用 QPixmap：

auto *avatarLabel = new QLabel(this);
QPixmap avatar(":/images/avatar.png");
avatarLabel->setPixmap(avatar);
avatarLabel->setScaledContents(false);

不要一上来就 setScaledContents(true)。它会强制把图片拉伸到标签大小，容易造成比例失真。保持原比例缩放时，应根据目标大小先调用 pixmap.scaled(..., Qt::KeepAspectRatio, Qt::SmoothTransformation)；图标、头像等资源还应准备高分辨率版本，让 Qt 在高 DPI 屏幕上选择合适的像素密度。

4.3 `setBuddy()`：标签和输入框的键盘关联

auto *nameLabel = new QLabel(tr("&昵称："), this);
nameLabel->setBuddy(nameEdit);

& 标出助记键。用户按 Alt+N 时，焦点会进入 nameEdit。这是桌面端表单的细节优势：不要只为鼠标用户设计。

五、QLineEdit：单行输入、校验与提交时机

QLineEdit 只处理一行文本；地址、备注、日志等需要多行时应使用 QTextEdit 或 QPlainTextEdit。它的关键不是“拿到字符串”，而是区分输入是否有效、变化来自程序还是用户，以及何时提交。

5.1 常用属性

passwordEdit->setPlaceholderText(tr("请输入密码"));
passwordEdit->setEchoMode(QLineEdit::Password);
passwordEdit->setClearButtonEnabled(true);
passwordEdit->setMaxLength(64);

placeholderText 是提示，不是默认值，调用 text() 时不会得到它。密码框只影响屏幕显示，不会加密内存中的字符串，也不会替你安全传输密码。

5.2 三个高频信号：不要混用

信号	程序调用 `setText()`	用户编辑	常见用途
`textChanged()`	会触发	会触发	实时同步、实时校验
`textEdited()`	不会触发	会触发	只关心用户输入
`editingFinished()`	不因 `setText()` 直接触发	焦点离开或 Enter 时触发，但受输入状态限制	提交、失焦校验

如果设置了 QValidator 或 inputMask，用户按 Enter 时，只有输入达到 Acceptable 状态才会发出 returnPressed() 和 editingFinished()；另外，单纯失去焦点且内容没有变化时，不会重复发出 editingFinished()。

本章示例用 textChanged() 启用保存按钮，因为昵称无论来自用户输入还是从已有资料回填，都应重新计算按钮状态。搜索建议、撤销栈统计这类只应由人操作触发的逻辑，则更适合 textEdited()。

connect(searchEdit, &QLineEdit::textEdited, this, &SearchWidget::requestSuggestions);

connect(nameEdit, &QLineEdit::returnPressed, this, &ProfileWidget::saveProfile);

returnPressed() 不等于任何时候按下 Enter 都会发出。设置校验器或输入掩码后，输入必须是可接受的，信号才会发出。

5.3 `QValidator`：让“是否有效”成为控件状态

本章示例把正则校验器安装到 nameEdit 上：

auto *validator = new QRegularExpressionValidator(
    QRegularExpression("[A-Za-z0-9\\u4e00-\\u9fa5]{2,12}"), this);
nameEdit->setValidator(validator);

const bool ok = nameEdit->hasAcceptableInput();

验证器会对每次编辑返回三种状态：Invalid、Intermediate、Acceptable。Intermediate 很重要，例如用户刚输入第一个字符时，虽然尚未达到两字符要求，但仍应允许他继续输入；因此不要简单地把“尚未完整”理解为“非法”。提交前用 hasAcceptableInput() 统一判断即可。

校验器改善交互，但不能替代业务校验。用户名是否被占用、手机号是否已注册、权限是否允许，都必须在业务层或服务端再次验证。

5.4 可编辑与只读

lineEdit->setReadOnly(true);

readOnly 和 enabled 是两个不同概念。

setReadOnly(true)：用户不能修改，但仍可以获得焦点、选择和复制文本；
setEnabled(false)：控件整体进入禁用状态，通常不能接受正常交互。

5.4 程序回填时如何避免触发联动？

QSignalBlocker blocker(nameEdit);
nameEdit->setText(profile.name);

QSignalBlocker 适合处理一次性的程序回填场景；它不是解决信号循环依赖的万能手段。

六、QComboBox：显示文本与业务值分开保存

QComboBox 将“用户看见的条目”与“程序需要的值”分开保存，这是它比一组硬编码 if 更可靠的原因。

6.1 添加条目与读取数据

cityCombo->addItem(tr("北京"), "beijing");
cityCombo->addItem(tr("上海"), "shanghai");

const QString displayName = cityCombo->currentText();
const QString cityCode = cityCombo->currentData().toString();

第一个参数是显示文本，第二个参数保存在 Qt::UserRole 位置的 QVariant。界面未来从“北京”改成“北京市”时，业务代码仍然拿到稳定的 beijing，不需要跟着改字符串判断。

如果业务数据本身就是枚举，可直接保存枚举值，但跨边界传递前要考虑 QVariant 是否注册了该类型。入门项目中，字符串代码通常已经足够清晰。

6.2 信号的两个语义层次

信号	程序调用 `setCurrentIndex()` 是否发出	用户选择是否发出	推荐用途
`currentIndexChanged(int)`	是	是	所有状态同步，例如刷新依赖字段
`currentTextChanged(const QString &)`	是	是	只关心可见文本时
`activated(int)`	否	是，即使重复点当前项也会发出	用户明确确认了一次选择
`highlighted(int)`	否	用户在弹出列表中移动高亮项	预览，不宜做提交

可以把这三个信号简单理解成：

currentIndexChanged()：状态变了
currentTextChanged()：显示文本变了
activated()：用户主动选了一次

QComboBox 有不少重载信号。Qt 6 中推荐用 qOverload 消除歧义：

connect(cityCombo, qOverload<int>(&QComboBox::currentIndexChanged), this, &ProfileWidget::updateSaveButton);

不要写旧式字符串连接：

// 不推荐：编译器无法检查拼写和参数签名。
connect(cityCombo, SIGNAL(currentIndexChanged(int)), this, SLOT(updateSaveButton()));

6.3 可编辑下拉框不是普通输入框的替代品

cityCombo->setEditable(true);
cityCombo->setInsertPolicy(QComboBox::NoInsert);
cityCombo->setCompleter(completer);

设为可编辑后，QComboBox 内部会持有一个 QLineEdit，用户既能输入又能选择。适合“常用值 + 允许自定义值”的场景，例如标签、服务器地址、历史目录；如果只有自由输入需求，直接使用 QLineEdit 更简单。可编辑模式下，明确设置 InsertPolicy，避免用户的临时输入意外进入候选列表。

6.4 查找数据findData()

在实际业务中经常存在反向需求：已经有一个 cityCode = "shanghai"，如何让 ComboBox 选中它？

这时候可以这样使用：

const int index = cityCombo->findData("shanghai");
if (index >= 0) {
    cityCombo->setCurrentIndex(index);
}

通过查找该数据项的索引，如果不存在那么说明没有这个数据。否则表示找到，可以继续使用索引执行自己的业务。

6.5 清空Clear()与统计Count()

combo->count();
combo->clear();
combo->removeItem(index);

这三个是QCombobox最常用的接口，分别是：统计当前数量、清空下拉项、删除指定下拉项。

七、信号槽：三种应该掌握的连接写法

信号槽并不是控件专属机制，但控件是最常见的发送者。connect() 的前两个参数描述“谁发出什么”，后两个参数描述“谁接收、执行什么”。

7.1 成员函数槽：业务逻辑的默认选择

connect(saveButton, &QPushButton::clicked, this, &ProfileWidget::saveProfile);

这适合可命名、可测试、可能增长的业务动作。由于函数指针在编译期参与类型检查，信号参数可以比槽函数参数多，但槽函数不能要求更多参数。例如 clicked(bool) 可连接到无参数的 saveProfile()。

7.2 Lambda：短小的界面绑定

connect(notifyButton, &QPushButton::toggled, this,
        [this](bool checked) {
            statusLabel->setText(checked ? tr("通知开启") : tr("通知关闭"));
        });

这里的第三个参数 this 称为上下文对象。当 ProfileWidget 析构时，这条连接会自动断开，Lambda 不会继续访问已经销毁的 statusLabel。不要省略上下文对象后再捕获裸指针；那会让生命周期判断变得困难。

7.3 重载信号：用 `qOverload` 说清楚签名

connect(cityCombo, qOverload<int>(&QComboBox::activated),
        this, [this](int index) {
            qDebug() << "用户选择了" << cityCombo->itemData(index);
        });

有重载时，&QComboBox::activated 本身不够明确。qOverload<int> 告诉编译器要选 int 版本。对于本章四个控件，QComboBox 是最常遇到这种情况的类。

在这里插入图片描述

图 2：connect() 通常在构造函数中建立一次；之后每次用户交互，控件事件处理会更新状态、发射信号，并根据连接关系调用槽函数。

7.4 `AutoConnection` 的初步理解

不指定连接类型时，connect() 默认使用 Qt::AutoConnection：如果发送者发射信号的线程与接收者所在的线程相同，槽通常直接调用；如果不同，Qt 会把调用投递到接收者线程的事件队列。本章所有控件和窗口都在 GUI 线程，所以不需要显式指定连接类型。

后续的多线程章节会深入队列连接。现在只记住一条边界：只能在 GUI 线程创建和操作 QWidget。 即使槽函数通过跨线程信号到达，也必须让真正的界面更新在 GUI 线程执行。

八、从 API 到源码：控件是怎样把操作送进槽函数的

这一节不要求你立刻下载 Qt 源码逐行阅读。目标是建立一张稳定的调用地图：公开 API 改了什么状态，用户事件从哪里进入，信号大致在哪一层发出。

不同 Qt 6 小版本的私有类名和行号可能变化，下面使用的是 Qt 6 系列的简化调用链；公开语义保持稳定。

8.1 `connect()` 做的不是“保存一个 C++ 回调指针”

当你写：

connect(saveButton, &QPushButton::clicked, this, &ProfileWidget::saveProfile);

新式函数指针连接利用 C++ 类型系统进行编译期检查；

对于 Qt 的元对象信号槽机制，连接关系会被 Qt 的元对象系统记录和管理。真正发射信号时，MOC 生成的信号函数会进入 QMetaObject::activate()；它遍历匹配的连接，并按连接类型直接调用或投递事件。

可以先把它理解成：

connect(...)
  -> 记录连接关系（sender + signal -> receiver + slot）

emit clicked(...)
  -> MOC 生成的 clicked 函数
  -> QMetaObject::activate(...)
  -> 找到连接
  -> 直接调用槽，或向接收者线程投递调用

emit 只是一个便于阅读的宏。它不是一次独立的运行时操作；去掉 emit，信号函数调用依然成立。真正让 Qt 能分发信号的是 MOC 生成的元对象代码和 QMetaObject::activate()。

8.2 QPushButton：点击先落到 `QAbstractButton`

QPushButton 的鼠标交互大部分来自基类 QAbstractButton。一条简化路径是：

QApplication 交付 QMouseEvent
  -> QAbstractButton::mousePressEvent()
  -> 按钮进入 down 状态，发射 pressed()
  -> QAbstractButton::mouseReleaseEvent()
  -> 命中按钮区域时调用 click()
  -> 若 checkable，更新 checked 状态并发射 toggled(...)
  -> 发射 released()
  -> 发射 clicked(checked)
  -> QMetaObject::activate()
  -> ProfileWidget::saveProfile()

因此，setCheckable(true) 并不是 QPushButton 额外加一个布尔字段那么简单：它会改变 click() 时的状态切换和信号序列。也能解释为什么“订阅开关”更适合 toggled()，而“保存”更适合 clicked()。

程序调用 button->click() 时，也会走按钮的点击语义并发出相关信号；直接调用业务槽函数则绕过了按钮状态与信号。测试“保存业务”时可直接测业务函数；测试“按钮是否正确连接”时应触发 click() 或用 QTest 模拟用户输入。

8.3 QLabel：设置文本后，不是在 `setText()` 里立刻画字

label->setText(tr("保存成功"));

其简化过程是：

QLabel::setText()
  -> 保存新的文本与文本格式信息
  -> 重新计算 sizeHint / 文本布局所需信息
  -> updateGeometry() 通知父布局：建议尺寸可能变了
  -> update() 请求一次重绘
  -> 事件循环稍后投递 Paint 事件
  -> QLabel::paintEvent() 按当前 QStyle 绘制文本或图片

这就是为什么一次连续的 setText() 不会马上逐像素绘制多次：Qt 通常把重绘请求合并，等事件循环有机会处理绘制事件。也因此，不要为了“马上显示状态文字”在 GUI 线程里调用耗时任务。耗时任务会占住事件循环，绘制事件同样无法执行；正确方向是把耗时工作移出 GUI 线程，并以信号报告结果。

8.4 QLineEdit：用户编辑与程序设值有意分流

QLineEdit 的文本编辑细节由内部的 QLineControl 协作完成。概念上可以分为两条路：

程序：setText("Alice")
  -> 更新文本状态
  -> textChanged("Alice")
  -> 不发 textEdited(...)

用户：keyPressEvent(QKeyEvent)
  -> QLineControl 处理按键、光标、选择区、验证器
  -> 文本确实变化
  -> textEdited(newText)
  -> textChanged(newText)

这就是 textEdited() 存在的理由：程序回填输入框时，不应被误判为用户正在键入。内部还要处理撤销/重做、输入法预编辑、剪贴板粘贴、输入掩码和验证器，因此不建议通过重写 keyPressEvent() 来自己维护文本；优先使用公开信号、验证器和 QLineEdit API。

8.5 QComboBox：条目不是简单的字符串数组

addItem(text, userData) 看起来像把一行字符串加入列表，实际 QComboBox 通过内部模型保存条目数据，并使用弹出的列表视图呈现选择项。简化链路如下：

addItem("北京", "beijing")
  -> 内部模型新增一行
  -> DisplayRole 保存“北京”，UserRole 保存“beijing”

用户在弹出列表选中一行
  -> 视图的当前项改变
  -> QComboBox 更新 currentIndex / 显示文本
  -> currentIndexChanged(index)
  -> currentTextChanged(text)
  -> activated(index)（仅用户操作语义）

这也解释了两条实践建议：列表很少时用 addItem() 足够；当条目来自数据库、需要排序过滤、条目数很大或多个视图共享同一份数据时，应学习后续章节的 Model/View，改用 setModel() 提供数据模型。

九、把界面状态和业务状态分开

下面这种写法很容易在小项目里出现：

if (cityCombo->currentText() == "北京") {
    // 业务分支
}

问题是：显示文本会被翻译、会改名，也可能由用户输入。优先读取 currentData()，并在保存时把控件状态转换为业务数据：

Profile profile;
profile.name = nameEdit->text().trimmed();
profile.cityCode = cityCombo->currentData().toString();
profile.notificationsEnabled = notifyButton->isChecked();

profileService.save(profile);
statusLabel->setText(tr("保存成功"));

控件是界面的短期状态容器，不应成为业务模型本身。

把转换集中在 saveProfile()、loadProfile() 等边界函数中，后续接入数据库、网络或单元测试时会轻松得多。

十、常见问题与排查顺序

10.1 为什么槽函数没有执行？

按这个顺序检查：控件指针是否有效；connect() 是否执行过；信号是否真的发出；控件是否被禁用；槽函数签名是否匹配；发送者或接收者是否已经析构。可以临时在槽函数首行加 qDebug()，也可以保存 connect() 的返回值：

const auto connection = connect(saveButton, &QPushButton::clicked,
                                this, &ProfileWidget::saveProfile);
Q_ASSERT(connection);

使用新式函数指针连接时，绝大多数签名问题会在编译期暴露；这正是它优于旧式 SIGNAL/SLOT 宏的重要原因。

10.2 为什么 `QLineEdit` 输入不了内容？

先检查是否被 setReadOnly(true) 或 setEnabled(false)；再检查验证器和输入掩码。尤其是验证器正则写得过严时，用户可能连第一个字符都无法输入。把规则临时移除或改为允许 Intermediate 的形式，再观察问题是否消失。

10.3 为什么设置 `setText()` 后又触发了逻辑？

因为 setText() 会发出 textChanged()。如果回填数据期间不希望触发界面联动，可缩小屏蔽范围：

QSignalBlocker blocker(nameEdit);
nameEdit->setText(profile.name);

需要 #include <QSignalBlocker>。不要长期阻塞整个窗口的信号，更不要用它掩盖循环依赖；优先让槽函数能安全处理重复状态，或改用只响应用户操作的 textEdited()。

10.4 为什么下拉框收到的索引是 `-1`？

-1 表示当前没有有效条目。常见原因是列表尚未添加数据、调用了 setCurrentIndex(-1)，或模型被清空。读取 currentData() 前要允许空值；表单场景可像本章示例那样放一个“请选择”占位项，并以空业务值表示未选择。

10.5 为什么状态标签不马上更新？

如果你在设置文本后立刻进行了耗时计算、同步网络请求或循环，事件循环没有机会执行绘制。不要用 repaint() 硬顶；应把耗时任务移至工作线程，完成后发射信号回到 GUI 线程更新 QLabel。第三阶段会完整讲解这条路径。

十一、四个控件常用API速查表

控件	API	用途
QPushButton	`setText()`	设置文字
	`setIcon()`	设置图标
	`setEnabled()`	启用/禁用
	`setCheckable()`	设置可选中
	`setChecked()`	设置选中状态
	`isChecked()`	获取状态
	`setDefault()`	设置 Dialog 默认按钮
QLabel	`setText()`	设置文本
	`setPixmap()`	设置图片
	`setWordWrap()`	自动换行
	`setAlignment()`	内容对齐
	`setBuddy()`	关联输入控件
QLineEdit	`text()`	获取文本
	`setText()`	设置文本
	`setPlaceholderText()`	占位提示
	`setReadOnly()`	只读
	`setMaxLength()`	最大长度
	`setValidator()`	输入校验
	`hasAcceptableInput()`	判断是否有效
QComboBox	`addItem()`	添加项目
	`currentText()`	当前显示文本
	`currentData()`	当前业务数据
	`findData()`	根据业务数据查找
	`setCurrentIndex()`	设置当前项
	`clear()`	清空
	`count()`	项目数量
	`setEditable()`	允许编辑

总结

四个控件可形成一个完整的最小交互闭环：QLabel 展示说明和结果，QLineEdit 收集单行输入，QComboBox 提供稳定的候选值，QPushButton 发起命令或维护二元状态。使用时优先掌握四件事：用布局安放控件；用属性限制可见行为；用新式 connect() 连接信号槽；在提交边界把控件状态转换为业务数据。

从源码视角看，控件 API 并非直接“画界面”或“调用函数”：按钮和输入框先处理事件、更新内部状态，再经 MOC 生成的信号函数与 QMetaObject::activate() 找到连接；标签把重绘请求交给事件循环；下拉框则借助模型和视图保存、展示条目。理解这条主线后，后续面对更多控件时，就不再只是背 API。

下一章将继续补齐另一组高频控件：数值输入、范围选择、进度反馈与布尔选项。

下一篇预告：《12_常用控件速查（下）：QSpinBox、QSlider、QProgressBar、QCheckBox》

11_常用控件速查（上）：QPushButton、QLabel、QLineEdit、QComboBox