QT编程(10): QLineEdit

一、QLineEdit核心定义与继承关系

QLineEdit是Qt Widgets模块中最基础、最常用的单行文本输入与显示控件，专门用于处理短文本内容的交互，仅支持单行纯文本输入，不支持换行和富文本格式，是Qt界面开发中短文本交互的核心组件，几乎所有需要简短文本录入的场景都会用到该控件。

继承体系：QLineEdit 直接继承自 QWidget，属于基础桌面控件，不自带滚动区域，文本过长时会自动显示省略号或支持光标横向滚动，结构轻量化，内存占用低、渲染速度快，适配各类轻量化短文本交互需求。

核心定位 ：主打单行纯文本交互，兼顾输入与展示双重功能，默认支持用户编辑，也可设为只读模式用于展示短文本信息，自带基础输入校验、输入提示、快捷键等便捷功能，无需复杂配置即可满足大部分短文本交互需求。

二、核心功能与特性

1. 基础文本交互特性

纯单行文本限制：严格限制单行输入，不支持回车换行，输入内容超出控件宽度时，会自动横向滚动显示，不会自动换行或撑开控件高度，保证界面布局规整。
纯文本模式：仅支持无格式纯文本，不兼容HTML、Markdown等富文本，输入内容仅保留文字本身，无字体、颜色、段落等格式属性，适配所有标准化短文本输入场景。
基础编辑功能：自带复制、剪切、粘贴、撤销、重做、全选、清空等基础编辑操作，支持Ctrl+C/Ctrl+V等标准快捷键，无需额外编写代码实现基础编辑逻辑。

2. 实用输入控制与校验功能

输入掩码：支持自定义输入掩码，强制用户按照指定格式输入，比如手机号、身份证号、日期、邮编、IP地址等固定格式内容，杜绝无效输入。
最大长度限制：可设置最大输入字符数，限制文本长度，避免超长内容输入，适配数据库字段长度、表单规范等硬性要求。
只读/禁用模式：setReadOnly(true)设为只读，用户可选中复制但无法编辑；setEnabled(false)设为禁用，完全禁止交互，适合展示固定短文本或临时锁定输入框。
密码模式：支持密码输入模式，可将输入内容替换为圆点、星号等占位符，保护隐私信息，是登录界面密码框的首选实现方式。

3. 交互体验优化特性

占位提示文本：支持设置placeholder占位提示文字，输入框为空时显示提示内容，用户开始输入后自动隐藏，引导用户规范输入，提升界面易用性。
文本对齐与选中：支持左对齐、居中、右对齐三种文本对齐方式，点击控件可自动全选内容，也可通过代码控制文本选中范围和光标位置。
自动补全功能：搭配QCompleter类实现输入自动补全，比如搜索历史、常用词条、固定选项补全，大幅提升输入效率。
清除按钮：可开启内置清除按钮，输入内容后自动显示，点击一键清空，无需手动选中删除，优化用户操作流程。

三、核心常用API（C++版本）

使用前需引入头文件：#include <QLineEdit>，qmake项目需添加QT += widgets，CMake项目需链接Qt6::Widgets，基础配置简单，开箱即用。

1. 文本设置与获取

API函数	功能说明
setText(const QString& text)	设置控件显示的纯文本内容，清空原有内容，无格式保留
text()	获取控件内的纯文本字符串，最常用的内容获取接口
clear()	一键清空所有输入内容，操作便捷
placeholderText()	获取当前设置的占位提示文本
setPlaceholderText(const QString&)	设置占位提示文本，输入为空时显示

2. 输入控制与模式设置

setReadOnly(bool)：设置只读模式，true为不可编辑，false为可编辑
setMaxLength(int)：设置最大输入字符数，超出部分无法输入
setEchoMode(QLineEdit::EchoMode)：设置输入显示模式，支持正常、密码、密码字符切换、无显示四种模式
setInputMask(const QString&)：设置输入掩码，规范输入格式
setClearButtonEnabled(bool)：开启/关闭内置清除按钮

3. 样式与对齐设置

setAlignment(Qt::Alignment)：设置文本对齐方式，可选Qt::AlignLeft、Qt::AlignCenter、Qt::AlignRight
setFont(const QFont&)：设置文本字体、字号、加粗等基础样式
setTextColor(const QColor&)：设置文本颜色（Qt高版本支持，低版本可通过样式表实现）

4. 核心常用信号

信号是QLineEdit交互逻辑的核心，通过绑定信号实现输入监听、确认、校验等功能，常用信号如下：

textChanged(const QString& text)：文本内容每次发生变化时触发，实时监听输入内容，适合实时校验、实时搜索场景
textEdited(const QString& text)：仅用户手动编辑内容时触发，代码调用setText不会触发，区分手动与代码赋值场景
editingFinished()：输入完成后触发，比如按下回车、点击其他控件失去焦点时，适合表单提交、输入确认场景
returnPressed()：按下回车键时触发，适配快速确认、搜索提交场景
selectionChanged()：文本选中范围发生变化时触发

四、适用场景

表单录入场景：用户名、密码、昵称、手机号、邮箱、邮编、验证码、IP地址、端口号等短文本输入
搜索查询场景：顶部搜索框、筛选条件输入框、关键词录入框
参数配置场景：软件配置项输入、路径填写、数值录入、固定参数设置
短文本展示场景：只读模式展示单个参数、状态信息、简短提示语

五、QLineEdit与同类文本控件区别

1. QLineEdit vs QTextEdit

QLineEdit是单行纯文本控件 ，轻量化、无富文本、不支持换行，适合短文本输入，内存占用极低；QTextEdit是多行富文本编辑器，支持换行、富文本、滚动，适合长篇内容，功能更复杂，内存占用更高，二者适用场景完全互补，短文本必选QLineEdit，长文本/富文本选QTextEdit。

2. QLineEdit vs QPlainTextEdit

QPlainTextEdit是多行纯文本控件，支持换行和滚动，主打长篇纯文本编辑（比如代码、日志），支持多行输入；QLineEdit仅支持单行，专注短文本交互，输入校验和快捷功能更贴合短文本场景，二者均为纯文本，但单行与多行的定位差异明显。

3. QLineEdit vs QTextBrowser

QTextBrowser是只读富文本展示控件，继承自QTextEdit，支持链接跳转和富文本，专门用于展示内容；QLineEdit支持编辑，仅纯文本单行展示/输入，适合可交互短文本，不可用于长篇或带格式内容展示。

六、简单使用示例

cpp 复制代码

// 创建QLineEdit控件，指定父对象
QLineEdit *lineEdit = new QLineEdit(this);
// 设置占位提示文本
lineEdit->setPlaceholderText("请输入用户名/手机号");
// 设置最大输入长度20字符
lineEdit->setMaxLength(20);
// 开启清除按钮
lineEdit->setClearButtonEnabled(true);
// 设置文本左对齐
lineEdit->setAlignment(Qt::AlignLeft);

// 绑定输入完成信号，处理输入内容
connect(lineEdit, &QLineEdit::editingFinished, this, [=]() {
    // 获取输入内容
    QString inputText = lineEdit->text();
    qDebug() << "用户输入内容：" << inputText;
});

// 密码框示例
QLineEdit *pwdEdit = new QLineEdit(this);
pwdEdit->setPlaceholderText("请输入密码");
// 设置为密码显示模式
pwdEdit->setEchoMode(QLineEdit::Password);
// 调整控件位置大小
pwdEdit->setGeometry(10, 50, 300, 30);

开发避坑小贴士：1. 禁止用QLineEdit实现多行文本输入，强行换行会导致显示异常，需改用QPlainTextEdit；2. 密码输入务必使用Password模式，切勿用普通模式明文存储；3. 表单校验优先用textChanged实时监听，最终确认用editingFinished信号；4. 大量短文本输入场景用QLineEdit，性能远优于多行控件。