3、基础控件（一）：QWidget、QLabel、QPushButton、QLineEdit 的常用属性、信号与槽实战

Qt Widgets 是 Qt 框架中最经典、最成熟的用户界面技术栈。无论你是开发桌面工具、工业控制软件，还是跨平台业务系统，掌握基础控件的属性体系与信号槽机制都是构建复杂界面的地基。本章聚焦四个最核心的控件——QWidget（所有控件的基类）、QLabel（静态文本与图像显示）、QPushButton（用户触发动作）、QLineEdit（单行文本输入），通过属性解析、信号槽实战与完整案例，帮助你建立“控件—属性—信号—槽”的闭环思维。

上图展示了四个控件之间的继承关系与信号槽分布。QWidget 是所有可视控件的基类，它定义了窗口几何、启用状态、可见性等通用属性；QLabel、QPushButton、QLineEdit 在继承这些通用属性的基础上，各自扩展了专属属性与信号。理解这张图，你就掌握了 Qt 控件体系的“骨架”。

3.1 核心原理：从 QWidget 基类到三个常用子控件

QWidget 是整个 Qt Widgets 模块的基石。它本身是一个空白的矩形区域，负责接收鼠标、键盘事件，并在屏幕上绘制自己。所有控件（包括按钮、标签、输入框）都是 QWidget 的子类，因此它们天然具备以下能力：

• 几何管理：setGeometry(x, y, w, h) 或 setFixedSize() 控制控件位置与尺寸。
• 启用状态：setEnabled(false) 使控件变灰且不响应鼠标键盘。
• 可见性：setVisible(true/false) 或 show()/hide() 控制显示。
• 窗口属性：setWindowTitle()、setWindowIcon() 等，仅对顶层窗口有效。

QLabel 的核心职责是“展示”。它不接收用户输入，但可以显示富文本（HTML 子集）、图片和动画。QPushButton 是“动作触发器”，用户点击后发出 clicked() 信号。QLineEdit 是“文本采集器”，支持单行输入、密码掩码、输入验证等。三者组合起来，就能构建一个完整的“输入—处理—输出”交互闭环。

3.2 判断方法与操作流程：如何选择控件并配置属性

在实际开发中，面对一个界面需求，你可以按照以下流程快速决策：

1. 判断交互类型：如果只是展示信息（如标题、状态提示），选 QLabel；如果需要用户点击触发动作，选 QPushButton；如果需要用户输入文本，选 QLineEdit。
2. 配置基础属性：先设置 objectName（便于样式表定位），再设置几何或交给布局管理器。
3. 设置专属属性：QLabel 设置 text、alignment、wordWrap；QPushButton 设置 text、icon、checkable；QLineEdit 设置 placeholderText、echoMode、maxLength。
4. 连接信号槽：确定哪个信号触发哪个槽函数，用 connect 建立连接。
5. 测试与迭代：运行程序，验证交互是否符合预期，必要时调整属性或增加验证逻辑。

下表总结了三个控件最常用的属性及其作用，方便你快速查阅：

控件	属性	类型	说明	典型值/示例
QLabel	text	QString	显示的文本内容	"用户名："
	alignment	Qt::Alignment	文本对齐方式	Qt::AlignCenter
	wordWrap	bool	是否自动换行	true（长文本时）
	textFormat	Qt::TextFormat	纯文本/富文本	Qt::RichText（支持HTML）
QPushButton	text	QString	按钮显示文字	"登录"
	icon	QIcon	按钮图标	QIcon(":/images/login.png")
	checkable	bool	是否可选中（保持按下状态）	true（用于开关）
	default	bool	是否为默认按钮（响应回车）	true（对话框常用）
QLineEdit	text	QString	当前输入内容	"admin"
	placeholderText	QString	输入框为空时的灰色提示	"请输入邮箱"
	echoMode	QLineEdit::EchoMode	显示模式	Password（密码掩码）
	maxLength	int	最大输入字符数	20

3.3 案例拆解：登录表单的完整实现

下面我们通过一个“用户登录表单”案例，将三个控件串联起来。这个案例包含两个 QLabel（提示文字）、一个 QLineEdit（用户名）、一个 QLineEdit（密码，密码模式）、一个 QPushButton（登录按钮）和一个 QLabel（状态反馈）。

背景与约束：这是一个桌面客户端登录窗口，要求用户输入用户名和密码，点击登录后模拟校验（用户名"admin"，密码"123456"），校验结果通过状态标签反馈。窗口固定大小 320×200，不允许拉伸。

关键代码实现：

// 创建控件
QLabel *userLabel = new QLabel("用户名:", this);
QLineEdit *userEdit = new QLineEdit(this);
userEdit->setPlaceholderText("请输入用户名");
userEdit->setMaxLength(20);

QLabel *pwdLabel = new QLabel("密码:", this);
QLineEdit *pwdEdit = new QLineEdit(this);
pwdEdit->setEchoMode(QLineEdit::Password);
pwdEdit->setPlaceholderText("请输入密码");

QPushButton *loginBtn = new QPushButton("登录", this);
loginBtn->setDefault(true);  // 回车触发

QLabel *statusLabel = new QLabel("等待输入...", this);
statusLabel->setAlignment(Qt::AlignCenter);

// 使用布局管理器（后续章节详解，此处先展示效果）
QVBoxLayout *layout = new QVBoxLayout(this);
layout->addWidget(userLabel);
layout->addWidget(userEdit);
layout->addWidget(pwdLabel);
layout->addWidget(pwdEdit);
layout->addWidget(loginBtn);
layout->addWidget(statusLabel);

// 信号槽连接
connect(loginBtn, &QPushButton::clicked, this, [=]() {
    QString user = userEdit->text().trimmed();
    QString pwd = pwdEdit->text();
    if (user == "admin" && pwd == "123456") {
        statusLabel->setText("登录成功！欢迎 " + user);
        statusLabel->setStyleSheet("color: green; font-weight: bold;");
    } else {
        statusLabel->setText("用户名或密码错误");
        statusLabel->setStyleSheet("color: red;");
        pwdEdit->clear();          // 清空密码
        pwdEdit->setFocus();       // 焦点回到密码框
    }
});

// 实时反馈：当用户输入时清除错误状态
connect(userEdit, &QLineEdit::textChanged, this, [=](const QString &) {
    statusLabel->setText("等待输入...");
    statusLabel->setStyleSheet("color: gray;");
});

分析判断过程：这里使用了 Lambda 表达式作为槽函数，避免了为简单逻辑单独定义成员函数。注意 text().trimmed() 去除用户名首尾空格，而密码不 trim（密码中空格是有效字符）。setDefault(true) 让按钮在用户按下回车时自动触发 clicked()，提升操作效率。

结果与复盘：运行后，输入正确凭据点击登录，状态标签变绿显示成功；输入错误则变红并清空密码框，同时焦点回到密码框方便重新输入。这个案例展示了三个控件的核心协作模式：QLabel 做静态提示与动态反馈，QLineEdit 负责采集输入，QPushButton 触发校验逻辑。实际项目中，你还可以增加 returnPressed() 信号连接，让密码框回车也能触发登录。

3.4 常见误区与总结复盘

在实际教学和项目评审中，我发现初学者经常陷入以下几个误区，需要特别警惕：

• 误区一：忘记设置 objectName。没有 objectName，后续使用 QSS 样式表（如 #loginBtn { background: blue; }）时无法精确定位控件，导致样式失效。
• 误区二：混淆 clicked() 与 pressed()。clicked() 是完整的“按下+释放”动作，而 pressed() 只要鼠标按下就触发。对于普通按钮，应优先使用 clicked()，避免用户误触。
• 误区三：在 QLabel 上尝试捕获点击。QLabel 默认不接收鼠标事件，如果确实需要点击标签，应重写 mousePressEvent() 或改用 QPushButton 的扁平样式。
• 误区四：忽略 QLineEdit 的输入验证。仅靠 maxLength 不够，对于邮箱、数字等格式，应使用 QValidator 或 QRegularExpressionValidator 进行前置过滤。
• 误区五：信号槽连接后不检查返回值。在 Qt 5 中，connect 返回一个 QMetaObject::Connection，如果连接失败（如信号或槽拼写错误），程序不会报错但功能失效。建议在调试阶段用 qDebug() 输出连接结果。

总结复盘：本章的核心是建立“基类属性 + 子类专属属性 + 信号槽”的三层认知模型。QWidget 提供通用能力，QLabel/QPushButton/QLineEdit 各自解决“显示、触发、输入”三类基本需求。在实战中，先明确控件职责，再配置属性，最后用信号槽串联逻辑。下一阶段，你将学习 QLayout 布局管理器，让控件在窗口缩放时自动排列——那是构建复杂界面的下一步关键。