4、常用控件（一）：QPushButton、QLabel、QLineEdit、QTextEdit、QComboBox、QSpinBox、QSlider等控件的属性、信号与常用方法

在Qt的控件体系中，基础输入与显示控件是构建任何图形用户界面的基石。本章聚焦于七种最常用的控件：QPushButton（按钮）、QLabel（标签）、QLineEdit（单行输入框）、QTextEdit（多行文本编辑器）、QComboBox（下拉框）、QSpinBox（数字调节框）和QSlider（滑块）。这些控件覆盖了从用户指令触发（按钮）、信息展示（标签）、文本采集（输入框）到数值调节（数字框与滑块）的完整交互链路。理解它们的属性（Property）、信号（Signal）与常用方法（Method），是后续学习布局管理、模型/视图框架以及自定义控件的前提。本章将通过原理剖析、属性对比、信号连接实战以及常见误区复盘，帮助你建立扎实的控件使用基础。

上图展示了本章七种控件的分类归属与信号交互逻辑。在Qt中，控件通过属性定义静态外观与数据，通过信号对外通知用户交互事件，通过槽函数（或Lambda表达式）响应这些事件。下面我们将逐一深入剖析每个控件的核心用法。

4.1 QPushButton：用户指令的触发器

核心原理：QPushButton是最基础的指令型控件。它继承自QAbstractButton，其本质是一个可点击的矩形区域，内部维护了text（显示文本）、icon（图标）、checkable（是否可选中）等属性。当用户按下并释放鼠标左键时，它会发射clicked()信号，这是最常用的交互入口。

关键属性与方法：

属性/方法	说明	典型值/示例
setText()	设置按钮显示文字	btn->setText("登录")
setIcon()	设置按钮图标	btn->setIcon(QIcon(":/img/ok.png"))
setCheckable(true)	启用选中状态（类似开关）	配合isChecked()使用
setEnabled()	启用/禁用按钮	btn->setEnabled(false)置灰
clicked()	点击信号（最常用）	connect(btn, &QPushButton::clicked, ...)

实战场景：在登录界面中，当用户输入完账号密码后，点击“登录”按钮触发校验逻辑。此时应使用clicked信号，而非pressed（按下即触发）或released（释放触发），因为clicked综合了按下与释放的完整动作，更符合用户预期。

4.2 QLabel：信息展示的基石

核心原理：QLabel是Qt中最轻量的显示控件，用于呈现静态或动态文本、图片及富文本。它不直接响应用户输入，但可以通过setText()动态更新内容，或通过setPixmap()显示图像。其textFormat属性支持纯文本（PlainText）、富文本（RichText）和自动检测（AutoText）。

常用方法：

• setText(const QString &)：设置显示文本，支持HTML标签（若启用富文本）。
• setPixmap(const QPixmap &)：显示图片，常用于图标或缩略图展示。
• setAlignment(Qt::Alignment)：设置文字对齐方式，如Qt::AlignCenter。
• setWordWrap(bool)：启用自动换行，适合长文本显示。
• setOpenExternalLinks(bool)：允许点击超链接时打开外部浏览器。

案例拆解：在多媒体播放器中，用QLabel显示当前播放状态。初始状态为“未播放”，当用户选择文件后，通过label->setText("正在播放: " + fileName)更新。若文件名过长，启用setWordWrap(true)并设置固定宽度，避免界面布局被撑破。

4.3 QLineEdit：单行文本输入与校验

核心原理：QLineEdit用于采集单行文本，支持输入掩码（InputMask）、回显模式（EchoMode）和输入验证器（Validator）。其核心信号textChanged(const QString &)在文本内容每次变化时发射，returnPressed()在用户按下回车时发射，适合搜索框或命令行输入。

关键属性：

属性	作用	示例
setEchoMode()	设置回显模式	QLineEdit::Password用于密码输入
setPlaceholderText()	设置灰色提示文字	edit->setPlaceholderText("请输入用户名")
setMaxLength()	限制最大输入长度	edit->setMaxLength(20)
setValidator()	设置输入验证器	new QIntValidator(0, 100, this)限制数字范围
setReadOnly()	只读模式，不可编辑但可选中	用于展示系统生成的只读代码

操作流程：实现一个“搜索框”功能：

1. 创建QLineEdit，设置setPlaceholderText("输入关键词")。
2. 连接returnPressed信号到槽函数，触发搜索逻辑。
3. 在槽函数中获取text()，去除首尾空格后执行查询。
4. 若输入为空，使用QMessageBox::warning提示用户。

4.4 QTextEdit：富文本与多行编辑

核心原理：QTextEdit是一个功能强大的多行文本编辑器，支持富文本（HTML子集）、图片嵌入、表格和列表。它基于QTextDocument文档模型，适合实现日志查看器、邮件编辑器或简单的Markdown预览。其toPlainText()方法获取纯文本，toHtml()获取HTML源码。

常用信号与方法：

• textChanged()：文本内容变化时发射（无参数）。
• setPlainText() / setHtml()：设置内容。
• append()：在末尾追加文本并自动滚动到底部，非常适合日志输出。
• setReadOnly()：设置为只读模式，用于显示不可编辑的文档。
• document()->setMaximumBlockCount()：限制最大段落数，防止内存无限增长。

实战场景：开发一个调试日志窗口。将QTextEdit设置为只读，连接业务模块的日志信号，在槽函数中调用append("[INFO] " + msg)。为避免日志过多导致卡顿，设置document()->setMaximumBlockCount(1000)，自动丢弃最旧的日志。

4.5 QComboBox：下拉选择与可编辑输入

核心原理：QComboBox提供下拉列表选择功能，同时支持设置为可编辑（setEditable(true)），允许用户输入自定义内容。它内部维护一个QModelIndex列表，通过addItem()或addItems()添加选项。当前选中项变化时发射currentIndexChanged(int)信号，文本变化时发射currentTextChanged(const QString &)。

常用方法：

方法	说明
addItem(text, userData)	添加选项，可附带用户数据（QVariant）
insertItem(index, text)	在指定位置插入选项
removeItem(index)	移除指定索引的选项
currentData()	获取当前选项的用户数据，避免通过文本匹配
setCurrentIndex()	程序化设置当前选中项

案例拆解：在设置界面中，用QComboBox选择“分辨率”。将选项文本设为“1920x1080”，同时通过addItem("1920x1080", QSize(1920,1080))存储实际尺寸。当用户选择后，在槽函数中通过currentData().toSize()获取真实分辨率，避免解析字符串带来的错误。

4.6 QSpinBox与QSlider：数值调节的两种范式

核心原理：QSpinBox（数字框）和QSlider（滑块）都继承自QAbstractSpinBox，用于数值输入。QSpinBox适合精确输入，支持键盘直接键入；QSlider适合快速调节或粗略定位，支持拖拽。两者通过setRange()设置范围，setValue()设置当前值，valueChanged(int)信号在数值变化时发射。

对比分析：

维度	QSpinBox	QSlider
输入方式	键盘输入 + 上下箭头	鼠标拖拽 + 键盘方向键
精度控制	支持小数（QDoubleSpinBox）	仅整数（可乘以系数模拟小数）
视觉反馈	紧凑，适合表单	直观，适合音量、亮度调节
常用信号	valueChanged(int)	valueChanged(int) / sliderMoved(int)
附加属性	setPrefix() / setSuffix() 添加单位	setTickPosition() 显示刻度

联动案例：实现一个“音量调节”控件。使用QSlider（水平方向）控制音量，QSpinBox显示当前数值。两者绑定同一变量：

// 初始化
QSlider *slider = new QSlider(Qt::Horizontal);
slider->setRange(0, 100);
QSpinBox *spin = new QSpinBox;
spin->setRange(0, 100);
spin->setSuffix("%");

// 双向绑定
connect(slider, &QSlider::valueChanged, spin, &QSpinBox::setValue);
connect(spin, QOverload<int>::of(&QSpinBox::valueChanged), slider, &QSlider::setValue);

此模式确保无论用户拖拽滑块还是手动输入数字，两个控件始终保持同步。注意使用QOverload<int>::of解决valueChanged信号重载的歧义。

4.7 综合实战：构建一个简易配置面板

下面通过一个完整的案例，将上述控件整合到一个“显示设置”面板中。该面板包含：主题选择（QComboBox）、字体大小（QSpinBox）、亮度调节（QSlider）、预览文本（QLabel）以及应用按钮（QPushButton）。

需求与约束：界面需实时预览效果，但“应用”按钮仅在设置变更后可用。初始状态为默认值，用户修改任意控件后，预览区立即更新，同时“应用”按钮变为可用。

关键实现步骤：

1. 创建控件并设置范围：主题下拉框添加“浅色”“深色”“自动”；字体大小SpinBox范围8-24；亮度Slider范围0-100。
2. 连接信号：为每个控件连接currentIndexChanged或valueChanged信号到同一个updatePreview()槽函数。
3. 在updatePreview()中：根据主题设置QLabel的样式表（如深色背景+白色文字），根据字体大小设置font，根据亮度调整背景色亮度。
4. 启用“应用”按钮：在updatePreview()中调用applyBtn->setEnabled(true)。
5. 点击“应用”后，将当前设置保存到配置文件，并禁用按钮。

结果与复盘：该面板展示了信号/槽机制如何将多个独立控件串联为有机整体。通过一个统一的更新函数，避免了为每个控件编写重复代码。复盘要点：

• 使用QSignalBlocker可在程序初始化设置控件值时临时屏蔽信号，防止误触发updatePreview()。
• 样式表（QSS）在动态更新时开销较大，若预览频繁，可考虑使用QPalette替代。
• “应用”按钮的启用逻辑应基于“当前值是否与已保存值不同”，而非简单地在每次信号中置true，否则用户改回原值后按钮仍可点击。

4.8 常见误区与总结复盘

误区一：混淆textChanged与editingFinished。textChanged在每次字符变化时触发，适合实时搜索；editingFinished在输入框失去焦点或按下回车时触发，适合最终值确认。若在textChanged中执行数据库查询，会造成大量无效请求。

误区二：忽略setValue的信号触发条件。当调用setValue()设置的值与当前值相同时，Qt不会发射valueChanged信号。这在初始化时是优点，但在需要强制刷新UI时可能造成逻辑遗漏，可手动调用update()或使用setValue(value+1); setValue(value);的技巧（不推荐）。

误区三：QComboBox的currentIndexChanged在添加第一个选项时也会触发。若在构造函数中先连接信号再添加选项，槽函数会被意外调用。建议先添加所有选项，再连接信号，或使用QSignalBlocker。

误区四：QTextEdit的append()会额外添加换行符。若需精确控制文本内容，应使用insertPlainText()或操作QTextCursor。

总结：本章控件虽基础，但组合使用能覆盖绝大多数界面交互需求。核心要点可归纳为：

控件	核心信号	典型应用
QPushButton	clicked()	提交、取消、触发动作
QLabel	linkActivated()	状态显示、图片展示
QLineEdit	textChanged() / returnPressed()	搜索框、登录表单
QTextEdit	textChanged()	日志、富文本编辑
QComboBox	currentIndexChanged()	选项选择、模式切换
QSpinBox	valueChanged()	数值输入、参数调节
QSlider	valueChanged() / sliderMoved()	音量、进度调节

掌握这些控件的属性与信号，是迈向复杂界面开发的第一步。在实际项目中，建议优先使用setRange、setValidator等约束性方法，从源头保证数据合法性，减少槽函数中的防御性判断。同时，合理利用QSignalBlocker和QOverload等工具，能让代码更健壮、更易维护。