QLineEdit 详解（C++）

QLineEdit 是 Qt 框架中用于单行文本输入的核心控件，广泛应用于表单输入、搜索框、命令行交互等场景。它提供了丰富的文本处理功能、输入验证机制和交互特性，是 Qt 界面开发中不可或缺的组件。本文将从基础用法、高级特性、信号与槽、输入验证、样式定制等方面全面解析 QLineEdit 的使用方法。

一、基础用法

创建与初始化
在 C++ 中使用 QLineEdit 需包含头文件 <QLineEdit>，并通过构造函数创建实例。基本语法如下：


#include <QLineEdit>
// 构造函数：父对象指针可选，用于内存管理
QLineEdit *lineEdit = new QLineEdit(parent);

可通过构造函数直接设置初始文本：


QLineEdit *lineEdit = new QLineEdit("初始文本", parent);

文本设置与获取

设置文本：setText(const QString &text)


lineEdit->setText("Hello Qt");

获取文本：QString text() const


QString input = lineEdit->text();

追加文本：insert(const QString &text)（在光标位置插入）


lineEdit->insert(" World"); // 原文本为"Hello"时，结果为"Hello World"

基本属性控制

只读模式：setReadOnly(bool)


lineEdit->setReadOnly(true); // 文本可选中但不可编辑

清空文本：clear()


lineEdit->clear();

占位提示文本：setPlaceholderText(const QString &text)（未输入时显示灰色提示）


lineEdit->setPlaceholderText("请输入用户名");

最大长度限制：setMaxLength(int length)


lineEdit->setMaxLength(20); // 最多输入20个字符

二、输入模式与显示格式

QLineEdit 支持多种输入模式，通过 setEchoMode(EchoMode mode) 控制文本显示方式，适用于密码输入等场景：

QLineEdit::Normal：默认模式，输入即显示（如普通文本）。QLineEdit::Password：输入字符显示为占位符（如 •），实际文本可通过 text() 获取。QLineEdit::PasswordEchoOnEdit：输入时显示明文，失去焦点后转为密码模式。QLineEdit::NoEcho：不显示任何输入（如敏感信息）。

示例：


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

三、信号与槽机制

QLineEdit 提供了丰富的信号，用于响应文本变化、焦点切换等事件，常用信号如下：

文本变化相关

textChanged(const QString &text)：文本发生改变时触发（包括编程修改）。


connect(lineEdit, &QLineEdit::textChanged, this, [=](const QString &text) {
    qDebug() << "当前文本：" << text;
});

textEdited(const QString &text)：仅用户手动编辑导致文本变化时触发（排除 setText() 等编程修改）。

焦点与交互相关

returnPressed()：用户按下回车键时触发（常用于提交表单）。


connect(lineEdit, &QLineEdit::returnPressed, this, &MyWidget::onSubmit);

editingFinished()：编辑完成且失去焦点时触发（如用户点击其他控件）。

四、输入验证

QLineEdit 可通过验证器（Validator）限制输入格式，确保输入符合预期（如数字、邮箱、IP地址等）。Qt 提供了三种内置验证器：

QIntValidator：限制整数输入（支持范围设定）


#include <QIntValidator>
QIntValidator *intValidator = new QIntValidator(1, 100, this); // 1~100的整数
lineEdit->setValidator(intValidator);

QDoubleValidator：限制浮点数输入（支持范围和精度）


#include <QDoubleValidator>
// -100.0~100.0，精度2位小数
QDoubleValidator *doubleValidator = new QDoubleValidator(-100.0, 100.0, 2, this);
doubleValidator->setNotation(QDoubleValidator::StandardNotation); // 标准表示法（非科学计数）
lineEdit->setValidator(doubleValidator);

QRegExpValidator：通过正则表达式验证（灵活适配复杂格式）
示例：验证邮箱格式


#include <QRegExpValidator>
QRegExp emailRegExp("[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,4}");
QRegExpValidator *emailValidator = new QRegExpValidator(emailRegExp, this);
lineEdit->setValidator(emailValidator);

自定义验证器
若内置验证器不满足需求，可继承 QValidator 重写 validate() 方法实现自定义逻辑：


class CustomValidator : public QValidator {
public:
    State validate(QString &input, int &pos) const override {
        // 自定义验证逻辑，返回 Acceptable/Intermediate/Invalid
        if (input.contains("invalid")) return Invalid;
        return Acceptable;
    }
};
// 使用
lineEdit->setValidator(new CustomValidator(this));

五、上下文菜单与功能扩展

QLineEdit 默认提供右键上下文菜单（包含复制、粘贴、撤销等功能），可通过以下方法扩展或定制：

内置功能控制

撤销/重做：undo()、redo()复制/粘贴：copy()、paste()剪切：cut()全选：selectAll()

示例：按钮触发全选


connect(selectAllBtn, &QPushButton::clicked, lineEdit, &QLineEdit::selectAll);

自定义上下文菜单
通过重写 contextMenuEvent(QContextMenuEvent *event) 或使用 setContextMenuPolicy() 替换默认菜单：


QMenu *menu = lineEdit->createStandardContextMenu(); // 获取默认菜单
menu->addAction("自定义操作", this, &MyWidget::customAction);
menu->exec(event->globalPos()); // 显示菜单

六、样式定制

QLineEdit 支持通过 Qt Style Sheets（QSS）定制外观，常见样式设置如下：

基本样式


lineEdit->setStyleSheet(R"(
    QLineEdit {
        border: 2px solid #ccc;       /* 边框 */
        border-radius: 4px;          /* 圆角 */
        padding: 5px;                /* 内边距 */
        font-size: 14px;             /* 字体大小 */
        color: #333;                 /* 文本颜色 */
        background-color: #fff;      /* 背景色 */
    }
    QLineEdit:focus {               /* 获焦状态 */
        border-color: #4a90e2;
        outline: none;
    }
    QLineEdit:read-only {           /* 只读状态 */
        background-color: #f5f5f5;
        color: #999;
    }
)");

占位文本样式
通过 ::placeholder 伪元素定制提示文本样式：


QLineEdit::placeholder {
    color: #999;
    font-style: italic;
}

七、高级特性

输入掩码（Input Mask）
用于固定格式输入（如电话号码、日期），通过 setInputMask(const QString &mask) 实现。掩码字符规则：

0：必须输入数字（0-9）9：可选输入数字或空格A：必须输入字母（A-Z,a-z）a：可选输入字母或空格_：空格占位符

示例：设置电话号码掩码（如 138-1234-5678）


lineEdit->setInputMask("000-0000-0000;_"); // 分号后为占位符

自动补全
结合 QCompleter 实现输入提示功能：


#include <QCompleter>
QStringList wordList = {"Apple", "Banana", "Cherry", "Date"};
QCompleter *completer = new QCompleter(wordList, this);
completer->setCaseSensitivity(Qt::CaseInsensitive); // 不区分大小写
lineEdit->setCompleter(completer);

与其他控件联动
QLineEdit 常与 QPushButton（提交）、QLabel（提示）等控件配合使用，例如实现搜索功能：


// 搜索按钮点击时触发搜索
connect(searchBtn, &QPushButton::clicked, this, [=]() {
    QString keyword = lineEdit->text();
    if (!keyword.isEmpty()) {
        search(keyword); // 自定义搜索函数
    }
});
// 回车触发搜索
connect(lineEdit, &QLineEdit::returnPressed, searchBtn, &QPushButton::click);

八、常见问题与解决方案

文本为空判断
使用 text().isEmpty() 或 text().isNull() 检查输入是否为空：


if (lineEdit->text().isEmpty()) {
    QMessageBox::warning(this, "提示", "输入不能为空！");
}

限制输入空格
通过 textChanged 信号过滤空格：


connect(lineEdit, &QLineEdit::textChanged, this, [=](const QString &text) {
    if (text.contains(" ")) {
        lineEdit->setText(text.replace(" ", "")); // 移除空格
    }
});

获取光标位置与选中文本

光标位置：cursorPosition()选中文本：selectedText()


QString selected = lineEdit->selectedText();
int cursorPos = lineEdit->cursorPosition();

总结

QLineEdit 作为 Qt 中最常用的输入控件，其功能涵盖了从基础文本输入到复杂格式验证的全场景需求。通过灵活运用其信号与槽、验证器、样式定制等特性，可快速实现用户友好的输入交互。在实际开发中，需结合具体业务场景（如表单验证、搜索功能等）选择合适的配置，同时注意通过样式设计提升用户体验。掌握 QLineEdit 的使用，是 Qt 界面开发的基础技能之一。