4. Qt Widgets基础控件使用：从零构建登录界面

在嵌入式Linux的GUI开发中，Qt Widgets模块是最经典、最稳定的界面构建方案。它提供了丰富的可视化控件（Widgets），允许开发者通过组合、布局和信号槽机制快速搭建功能完整的应用界面。本章将聚焦于最常用的五个基础控件——QWidget、QLabel、QPushButton、QLineEdit和QComboBox，深入剖析它们的核心属性、常用方法与事件处理机制，并通过一个完整的登录界面案例，将理论知识与实战操作串联起来。无论你是刚接触Qt的新手，还是希望系统梳理控件用法的嵌入式工程师，本章都将为你提供一份清晰、可落地的技术指南。

上图清晰地展示了本章的知识架构：左侧是五个核心控件，中间是每个控件都具备的属性、方法与信号三大维度，右侧则是我们将要实现的登录界面案例。底部进一步拆解了登录按钮点击后的信号槽处理链路。接下来，我们将逐一深入每个控件的细节，并在最后完成一个可运行的登录界面。

4.1 QWidget：一切界面的基石

QWidget是所有用户界面对象的基类。无论是窗口、对话框还是按钮、输入框，本质上都是QWidget或其子类的实例。理解QWidget，就等于理解了Qt界面体系的根基。

4.1.1 核心原理：窗口与控件的统一抽象

QWidget提供了绘制界面、处理输入事件、管理子控件等基础能力。它既可以作为独立窗口显示（顶级窗口），也可以作为其他控件的容器（父控件）。在嵌入式开发中，我们通常将整个应用的主窗口设置为QWidget或其子类（如QMainWindow），然后在上面放置各种子控件。

4.1.2 关键属性与方法

类别	名称	说明	典型用法
属性	geometry	控件的位置和大小（x, y, width, height）	setGeometry(100, 50, 320, 240)
属性	enabled	是否可用，禁用后不响应鼠标和键盘	setEnabled(false)
属性	visible	是否可见	setVisible(true) 或 show()
属性	windowTitle	窗口标题（仅顶级窗口有效）	setWindowTitle("登录")
方法	show() / hide()	显示/隐藏控件	widget->show()
方法	setLayout()	设置布局管理器	setLayout(layout)
方法	setStyleSheet()	设置样式表（类似CSS）	setStyleSheet("background: #f0f0f0;")
事件	paintEvent()	绘制事件，自定义绘制时重写	较少直接使用
事件	resizeEvent()	窗口大小改变时触发	用于自适应布局

4.1.3 实战场景：创建主窗口框架

在登录案例中，我们首先创建一个QWidget作为主窗口，并设置其标题和初始大小。这是所有后续操作的画布。

// 创建主窗口
QWidget *loginWindow = new QWidget();
loginWindow->setWindowTitle("嵌入式Linux登录");
loginWindow->setFixedSize(360, 280);  // 固定大小，避免拉伸变形

4.1.4 常见误区与复盘

4.2 QLabel：信息展示的窗口

QLabel用于显示文本、图片或富文本内容。它是界面中最常见的静态元素，但也能通过信号实现简单的交互（如链接点击）。

4.2.1 核心原理：富文本与自动换行

QLabel支持纯文本（PlainText）、富文本（RichText，基于HTML子集）和Markdown（Qt 5.14+）。在嵌入式界面中，我们常用它显示标题、提示信息或状态反馈。

4.2.2 关键属性与方法

类别	名称	说明	典型用法
属性	text	显示的文本内容	label->setText("用户名:")
属性	alignment	文本对齐方式	setAlignment(Qt::AlignRight | Qt::AlignVCenter)
属性	wordWrap	是否自动换行	setWordWrap(true)
方法	setPixmap()	显示图片	label->setPixmap(QPixmap("icon.png"))
方法	clear()	清空内容	label->clear()
信号	linkActivated()	用户点击富文本中的链接时触发	用于实现"忘记密码"等交互

4.2.3 实战场景：登录界面标题与提示

在登录界面中，我们使用QLabel显示标题和错误提示信息。通过设置样式表，可以让界面更美观。

// 标题标签
QLabel *titleLabel = new QLabel("系统登录");
titleLabel->setAlignment(Qt::AlignCenter);
titleLabel->setStyleSheet("font-size: 20px; font-weight: bold; color: #333;");

// 错误提示标签（初始隐藏）
QLabel *errorLabel = new QLabel("用户名或密码错误");
errorLabel->setStyleSheet("color: red;");
errorLabel->setVisible(false);  // 默认隐藏

4.2.4 常见误区与复盘

4.3 QPushButton：用户操作的触发器

QPushButton是界面中最常用的交互控件。用户点击按钮时，会触发clicked()信号，我们通过连接该信号到自定义槽函数来执行相应逻辑。

4.3.1 核心原理：信号-槽机制

Qt的信号槽机制是一种类型安全的回调方式。当按钮被点击时，clicked()信号被发射，所有连接到该信号的槽函数都会被调用。这种解耦设计使得代码结构清晰，易于维护。

4.3.2 关键属性与方法

类别	名称	说明	典型用法
属性	text	按钮上显示的文本	button->setText("登录")
属性	enabled	是否可点击	setEnabled(false) 禁用按钮
属性	checkable	是否为可选中按钮（类似开关）	setCheckable(true)
方法	setIcon()	设置按钮图标	setIcon(QIcon(":/images/login.png"))
方法	setDefault()	设置为默认按钮（按回车触发）	setDefault(true)
信号	clicked()	按钮被点击时发射	connect(btn, &QPushButton::clicked, this, &MyClass::onLogin)
信号	pressed() / released()	按下/释放时发射	用于特殊交互效果

4.3.3 实战场景：登录与退出按钮

我们创建两个按钮，并连接它们的clicked()信号到对应的槽函数。

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

// 退出按钮
QPushButton *cancelBtn = new QPushButton("退 出");

// 连接信号槽
connect(loginBtn, &QPushButton::clicked, this, &LoginDialog::onLoginClicked);
connect(cancelBtn, &QPushButton::clicked, this, &LoginDialog::onCancelClicked);

4.3.4 常见误区与复盘

4.4 QLineEdit：单行文本输入

QLineEdit是用户输入文本的核心控件。在登录界面中，它用于输入用户名和密码。针对密码输入，QLineEdit提供了掩码（EchoMode）功能。

4.4.1 核心原理：输入模式与验证

QLineEdit支持多种输入模式（EchoMode），包括Normal（正常显示）、Password（显示为圆点）、NoEcho（完全不显示）等。此外，还可以通过QValidator设置输入验证规则（如只允许数字、限制长度）。

4.4.2 关键属性与方法

类别	名称	说明	典型用法
属性	text	当前输入的文本	lineEdit->text()
属性	placeholderText	输入框为空时显示的灰色提示	setPlaceholderText("请输入用户名")
属性	echoMode	输入显示模式	setEchoMode(QLineEdit::Password)
属性	maxLength	最大输入长度	setMaxLength(16)
方法	clear()	清空输入内容	lineEdit->clear()
方法	setFocus()	设置焦点到该输入框	lineEdit->setFocus()
信号	textChanged()	文本内容变化时发射	用于实时搜索、输入提示
信号	returnPressed()	用户按下回车键时发射	用于快速提交

4.4.3 实战场景：用户名与密码输入

// 用户名输入框
QLineEdit *userEdit = new QLineEdit();
userEdit->setPlaceholderText("请输入用户名");
userEdit->setMaxLength(20);

// 密码输入框
QLineEdit *passEdit = new QLineEdit();
passEdit->setPlaceholderText("请输入密码");
passEdit->setEchoMode(QLineEdit::Password);
passEdit->setMaxLength(16);

// 连接回车信号，方便用户操作
connect(passEdit, &QLineEdit::returnPressed, loginBtn, &QPushButton::click);

4.4.4 常见误区与复盘

4.5 QComboBox：下拉选择控件

QComboBox提供下拉列表选择功能。在登录界面中，我们可以用它来选择用户角色（如管理员、普通用户、访客），从而根据角色加载不同的权限配置。

4.5.1 核心原理：模型-视图架构

QComboBox基于Qt的模型/视图架构，内部维护一个列表模型（QStandardItemModel）。它既可以作为只读下拉框，也可以设置为可编辑（允许用户输入自定义内容）。

4.5.2 关键属性与方法

类别	名称	说明	典型用法
属性	currentIndex	当前选中项的索引（从0开始）	combo->currentIndex()
属性	currentText	当前选中项的文本	combo->currentText()
方法	addItem()	添加一个选项	combo->addItem("管理员")
方法	addItems()	添加多个选项	combo->addItems({"A", "B", "C"})
方法	clear()	清空所有选项	combo->clear()
方法	setCurrentIndex()	设置当前选中项	setCurrentIndex(1)
信号	currentIndexChanged()	当前索引变化时发射	用于联动更新界面
信号	currentTextChanged()	当前文本变化时发射	用于实时响应

4.5.3 实战场景：角色选择

// 角色选择下拉框
QComboBox *roleCombo = new QComboBox();
roleCombo->addItem("普通用户");
roleCombo->addItem("管理员");
roleCombo->addItem("访客");
roleCombo->setCurrentIndex(0);  // 默认选择普通用户

// 连接信号，当角色改变时打印日志
connect(roleCombo, QOverload<int>::of(&QComboBox::currentIndexChanged),
        [=](int index) { qDebug() << "当前角色索引:" << index; });

4.5.4 常见误区与复盘

4.6 综合实战：构建完整登录界面

现在，我们将上述控件整合到一个完整的登录界面中。该案例将展示：布局管理、控件初始化、信号槽连接、输入验证和界面反馈。

4.6.1 案例背景与目标

目标：在嵌入式Linux设备（分辨率800x480）上，实现一个简洁的登录界面。用户输入用户名、密码，选择角色后点击"登录"。系统验证输入（非空、密码长度≥6位），验证通过后显示"登录成功"并跳转（此处用消息框模拟），失败则显示错误提示。

4.6.2 界面布局设计

使用QVBoxLayout垂直布局，从上到下依次为：标题、用户名行（QLabel + QLineEdit）、密码行、角色行、错误提示标签、按钮行。

// 创建布局
QVBoxLayout *mainLayout = new QVBoxLayout;

// 添加标题
mainLayout->addWidget(titleLabel);

// 用户名行
QHBoxLayout *userLayout = new QHBoxLayout;
userLayout->addWidget(new QLabel("用户名:"));
userLayout->addWidget(userEdit);
mainLayout->addLayout(userLayout);

// 密码行
QHBoxLayout *passLayout = new QHBoxLayout;
passLayout->addWidget(new QLabel("密  码:"));
passLayout->addWidget(passEdit);
mainLayout->addLayout(passLayout);

// 角色行
QHBoxLayout *roleLayout = new QHBoxLayout;
roleLayout->addWidget(new QLabel("角  色:"));
roleLayout->addWidget(roleCombo);
mainLayout->addLayout(roleLayout);

// 错误提示
mainLayout->addWidget(errorLabel);

// 按钮行
QHBoxLayout *btnLayout = new QHBoxLayout;
btnLayout->addStretch();
btnLayout->addWidget(loginBtn);
btnLayout->addWidget(cancelBtn);
btnLayout->addStretch();
mainLayout->addLayout(btnLayout);

// 设置主窗口布局
loginWindow->setLayout(mainLayout);

4.6.3 登录逻辑实现

void LoginDialog::onLoginClicked()
{
    QString username = userEdit->text().trimmed();
    QString password = passEdit->text();
    QString role = roleCombo->currentText();

    // 输入验证
    if (username.isEmpty()) {
        errorLabel->setText("用户名不能为空！");
        errorLabel->setVisible(true);
        userEdit->setFocus();
        return;
    }
    if (password.length() < 6) {
        errorLabel->setText("密码长度至少6位！");
        errorLabel->setVisible(true);
        passEdit->setFocus();
        return;
    }

    // 模拟验证（实际项目中应查询数据库或认证服务器）
    if (username == "admin" && password == "123456") {
        QMessageBox::information(this, "成功", 
            QString("欢迎登录，%1！\n角色：%2").arg(username, role));
        accept();  // 关闭对话框
    } else {
        errorLabel->setText("用户名或密码错误！");
        errorLabel->setVisible(true);
        passEdit->clear();
        passEdit->setFocus();
    }
}

void LoginDialog::onCancelClicked()
{
    reject();  // 退出登录
}

4.6.4 案例复盘与优化建议

4.7 本章总结与常见问题排查

本章我们系统学习了Qt Widgets五个基础控件的核心用法，并通过登录界面案例将它们串联起来。在实际开发