对于Qt：QLineEdit控件常见属性的解析

开篇介绍：

hello 大家，本篇博客我们来学习QLineEdit控件常见属性。

在 Qt 桌面应用开发中，我们每天都会遇到一个最最最基础、最最最常用、最最最重要的需求：让用户输入一段文字—— 比如登录时输入用户名和密码、注册时输入手机号和邮箱、搜索时输入关键词、填写表单时输入姓名和地址。在这些场景下，你总不能让用户对着空气说话吧？你需要一个 “输入框”—— 一个能让用户点击、能让用户打字、能显示用户输入内容的控件。

为了满足这个需求，Qt 专门为我们提供了一个开箱即用的核心控件：QLineEdit（单行输入框）。QLineEdit 就像一个 “电子写字板”—— 不过它只能写一行字（不能换行），但它的功能却极其强大：你可以用它做普通的文本输入框，可以用它做密码框（输入的内容显示为星号），可以限制用户最多输入多少个字，可以限制用户只能输入数字（比如手机号），可以在输入框为空时显示提示文字，可以在输入框右侧显示一个 “一键清空” 的按钮，可以让输入框只读（只能看不能改）…… 可以说，只要是 “单行文本输入” 的场景，QLineEdit 都能完美胜任。

很多新手刚接触 QLineEdit 时，会觉得它很简单 —— 不就是一个输入框吗？拖上去就能用。但用起来才发现，它还有很多实用的属性和信号：比如你要区分 “用户手动输入” 和 “代码自动修改”，就要搞懂 textChanged() 和 textEdited() 信号的区别；你要做密码框，就要会用 echoMode 属性；你要限制用户只能输入手机号，就要会用 inputMask 或者正则表达式验证器；你要让输入框为空时显示 “请输入用户名”，就要会用 placeholderText 属性；你要让用户能一键清空输入框，就要会用 clearButtonEnabled 属性…… 更重要的是，这里面有很多新手几乎 100% 会踩的坑—— 比如 textChanged() 和 textEdited() 到底有啥区别？readOnly 和 setEnabled(false) 到底有啥不一样？echoMode 的三种模式分别是啥？

别担心！这篇文章我会结合 QLineEdit 的所有核心属性（text、frame、inputMask、maxLength、echoMode、placeholderText、dragEnabled、readOnly、cursorPosition、alignment、clearButtonEnabled）、所有核心信号（cursorPositionChanged、editingFinished、returnPressed、selectionChanged、textChanged、textEdited）进行解析

话不多说，我们正式开始！

第一章 先搞懂基础：QLineEdit 是什么？

在讲具体属性之前，我们必须先搞懂两个最基础、最重要的问题：QLineEdit 是用来做什么的？以及，它长什么样？

1.1 QLineEdit 的核心定位

QLineEdit 是 Qt Widgets 模块中用于单行文本输入交互的核心控件。

通俗理解：QLabel 是 “告示牌”，用来显示文字，不能输入；QPushButton 是 “按钮”，用来点击触发操作；QProgressBar 是 “进度条”，用来显示进度；而 QLineEdit 就是 “单行输入框”—— 它是一个长方形的框，用户可以点击它，让光标出现在里面，然后用键盘输入文字、数字、符号，输入的内容会直接显示在框里（或者显示为星号，比如密码框）。

这里有一个非常重要的点，必须一开始就说清楚：

QLineEdit 只支持单行文本输入！不能换行！

如果你需要让用户输入多行文字（比如写一段备注、写一篇短文），不要用 QLineEdit，要用 QTextEdit（或者 QPlainTextEdit）。QTextEdit 才是支持多行输入、换行、甚至富文本的控件。QLineEdit 只能写一行，按回车键不会换行，而是会触发 returnPressed() 信号（我们后面会讲）。

QLineEdit 内置了非常多的功能，不需要你手动实现：

• 它支持文本的输入、删除、选中、复制、粘贴；
• 它支持光标移动（鼠标点击、键盘方向键）；
• 它支持输入格式约束（比如只能输入数字、只能输入手机号格式）；
• 它支持密码隐藏（输入的内容显示为星号）；
• 它支持占位提示（输入框为空时显示浅灰色的提示文字）；
• 它支持一键清空（右侧显示一个 “×” 按钮，点击清空）；
• 它支持只读模式（只能看不能改）；
• 它支持文本拖拽（把选中的文字拖到别的地方）。

总之，QLineEdit 是桌面端单行文本输入场景的首选组件，你不需要自己处理光标、不需要自己处理输入、不需要自己处理选中，直接用它就对了。

第二章 QLineEdit 核心属性详解（一）：基础属性（text、frame、inputMask、maxLength）

好，我们正式开始讲属性！我们首先讲四个最基础、最常用的核心属性：text（文本内容）、frame（边框）、inputMask（输入掩码）、maxLength（最大长度）。这四个属性决定了输入框的内容存储、输入规则、容量限制和基础视觉样式，是所有单行文本输入场景都可能用到的。

2.1 属性一：text（文本内容）—— 核心中的核心！

2.1.1 属性的核心定义

text 属性是 QLineEdit 最最最核心的属性，没有之一 —— 它存储了输入框当前的全部文本内容。

通俗理解：这个属性就像 “电子写字板上写的字”—— 你在输入框里输入了什么，text 就是什么；你用代码设置了什么，输入框里就显示什么。

这里有几个非常重要的规则，必须牢记：

2.1.2 数据类型

QString 类型 ——Qt 专门用来处理字符串的类，支持中文、英文、数字、符号等所有可显示字符。

2.1.3 关联 API 详解（逐词逐句，零模糊）

text 属性有三个关联的 API，我们逐个来讲：

1. 获取当前文本内容：QString text () const

函数原型：

QString QLineEdit::text() const;

逐词逐句底层解析：

• QString：返回值类型，返回一个 QString 对象，包含输入框当前的全部文本内容；
• QLineEdit::：说明这个函数是 QLineEdit 类的成员函数，只能用 QLineEdit 对象调用；
• text()：函数名，很直观，就是 “获取文本” 的意思；
• const：说明这个函数是常成员函数—— 它只会读取输入框的文本，不会修改任何状态，所以你可以在 const 的成员函数里调用它。

返回值说明：

• 返回 QString 类型的字符串；
• 如果输入框为空，返回空字符串（""）；
• 你可以用 text().isEmpty() 来判断输入框是否为空，非常方便。

调用示例：

// 获取输入框当前的文本内容
QString currentText = ui->lineEdit->text();
// 打印出来验证
qDebug() << "当前输入框文本：" << currentText;
// 判断是否为空
if (currentText.isEmpty()) {
qDebug() << "输入框为空";
} else {
qDebug() << "输入框不为空";
}

2. 通过代码设置文本内容：void setText (const QString &text)

函数原型：

void QLineEdit::setText(const QString &text);

逐词逐句底层解析：

• void：函数没有返回值，只是执行 “设置文本” 的操作；
• QLineEdit::：成员函数；
• setText()：函数名，“设置文本” 的意思；
• const QString &text：入参，text 是你要设置的目标文本（用 const 引用传递，避免拷贝 QString 对象，提高效率）。

参数说明：

• text：目标文本字符串，QString 类型；
• 支持任意可显示字符，包括中文、英文、数字、符号等；
• 如果传入包含换行符（\\n）的字符串，换行符会被自动过滤，仅保留单行内容。

生效规则：

• 调用后立即生效，输入框会立即显示你设置的文本；
• 会触发 textChanged(const QString &text) 信号；
• 但是！ 不会触发 textEdited(const QString &text) 信号！（因为这是代码操作，不是用户操作）；
• 如果之前有选中的文本，设置新文本后会取消选中状态。

调用示例：

// 示例1：设置普通文本
ui->lineEdit->setText("Hello Qt QLineEdit");
// 此时输入框显示 "Hello Qt QLineEdit"，触发 textChanged()，不触发 textEdited()

// 示例2：设置包含中文的文本
ui->lineEdit->setText("这是一个测试输入框");

// 示例3：清空文本（等价于 clear()）
ui->lineEdit->setText("");

3. 快速清空文本：void clear ()

函数原型：

void QLineEdit::clear();

逐词逐句底层解析：

• void：无返回值；
• QLineEdit::：成员函数；
• clear()：函数名，“清空” 的意思。

生效规则：

• 等价于 setText("")；
• 调用后立即生效，输入框文本被清空；
• 会触发 textChanged(const QString &text) 信号（参数为空字符串）；
• 不会触发 textEdited(const QString &text) 信号；
• 取消选中状态。

调用示例：

// 先设置一些文本
ui->lineEdit->setText("需要清空的文本");
// 然后清空
ui->lineEdit->clear();
// 此时输入框为空，触发 textChanged("")

2.1.4 关键注意事项（必知！）

在讲完 text 属性的 API 后，我必须把几个最容易踩坑的注意事项单独列出来：

2.2 属性二：frame（边框）—— 要不要显示输入框的框？

2.2.1 属性的核心定义

frame 属性用于控制 QLineEdit 是否绘制系统默认的矩形视觉边框。

通俗理解：这个属性就像 “电子写字板有没有画外框”—— 有的写字板有一个黑色的外框，把写字区域框起来；有的写字板没有外框，只有一块平板，看起来更简洁。这个属性就是用来切换 “显示外框” 还是 “隐藏外框” 的。

这里有几个点需要注意：

2.2.2 数据类型

bool 类型，true 表示显示边框（默认），false 表示隐藏边框。

2.2.3 关联 API 详解（逐词逐句，零模糊）

这里有一个小细节要注意：获取函数的名字不是 isFrame()，而是 hasFrame()，符合 Qt 的命名习惯（表示 “有没有” 用 has，表示 “是不是” 用 is）。

1. 获取是否显示边框：bool hasFrame () const

函数原型：

bool QLineEdit::hasFrame() const;

逐词逐句底层解析：

• bool：返回值类型，返回 true 或 false；
• QLineEdit::：成员函数；
• hasFrame()：函数名，“有没有边框” 的意思；
• const：常成员函数。

返回值说明：

• true 表示显示边框（默认）；
• false 表示隐藏边框。

调用示例：

bool hasFrame = ui->lineEdit->hasFrame();
if (hasFrame) {
qDebug() << "当前输入框显示边框";
} else {
qDebug() << "当前输入框隐藏边框";
}

2. 设置是否显示边框：void setFrame (bool enable)

函数原型：

void QLineEdit::setFrame(bool enable);

逐词逐句底层解析：

• void：无返回值；
• QLineEdit::：成员函数；
• setFrame()：函数名，“设置边框” 的意思；
• bool enable：入参，enable 是 true 显示边框，false 隐藏边框。

参数说明：

• enable：true 显示边框，false 隐藏边框。

生效规则：

• 调用后立即生效，输入框的边框会立即显示或隐藏；
• 仅影响视觉，不影响任何交互功能。

调用示例：

// 示例1：隐藏输入框边框（仅显示文本，无视觉框体）
ui->lineEdit->setFrame(false);
// 此时输入框看起来像一个普通的文本标签，但仍然可以点击输入

// 示例2：恢复显示边框（默认状态）
ui->lineEdit->setFrame(true);

2.2.4 关键注意事项

2.3 属性三：inputMask（输入掩码）—— 强制限制输入格式！

2.3.1 属性的核心定义

inputMask 属性是 QLineEdit 用于强制限制用户输入格式的属性 —— 它通过预定义的 “掩码规则”，告诉用户 “这里只能输入什么样的字符”，不符合规则的字符会被直接拒绝（用户敲键盘没反应，输不进去）。

通俗理解：这个属性就像 “一张有形状的模板”—— 比如你想让用户输入手机号，你就拿一张 “11 个数字孔” 的模板盖在输入框上，用户只能往数字孔里填数字，填别的（比如字母、符号）填不进去；如果你想让用户输入日期，你就拿一张 “4 位数字 – 2 位数字 – 2 位数字” 的模板，用户只能按这个格式填。

这里有几个非常重要的规则，必须牢记：

2.3.2 常用掩码规则示例（不用背，随用随查）

为了方便你使用，我把最常用的几个掩码规则列在下面，用表格展示，不用背，用到的时候查一下就行：

这里简单解释一下常用的占位符（不用全记，知道有这么回事就行）：

• 9：可选数字（0-9），可以不输；
• 0：必须数字（0-9），必须输；
• A：必须字母或数字，必须输；
• a：可选字母或数字，可以不输；
• #：可选数字或加号 / 减号，可以不输；
• H：必须十六进制字符（0-9, A-F, a-f）；
• h：可选十六进制字符；
• B：必须二进制字符（0-1）；
• b：可选二进制字符；
• X：必须任意字符；
• x：可选任意字符；
• 其他字符（如 -、.、(、)、空格）：分隔符，自动显示，用户不用输。

2.3.3 关联 API 详解（逐词逐句，零模糊）

1. 获取当前输入掩码：QString inputMask () const

函数原型：

QString QLineEdit::inputMask() const;

逐词逐句底层解析：

• QString：返回值类型，返回当前设置的掩码字符串；
• QLineEdit::：成员函数；
• inputMask()：函数名，“获取输入掩码” 的意思；
• const：常成员函数。

返回值说明：

• 返回当前设置的掩码字符串；
• 如果没有设置掩码，返回空字符串（""）。

调用示例：

QString mask = ui->lineEdit->inputMask();
if (mask.isEmpty()) {
qDebug() << "当前无输入格式约束";
} else {
qDebug() << "当前输入掩码：" << mask;
}

2. 设置输入掩码：void setInputMask (const QString &mask)

函数原型：

void QLineEdit::setInputMask(const QString &mask);

逐词逐句底层解析：

• void：无返回值；
• QLineEdit::：成员函数；
• setInputMask()：函数名，“设置输入掩码” 的意思；
• const QString &mask：入参，mask 是掩码规则字符串。

参数说明：

• mask：掩码规则字符串，QString 类型；
• 传入空字符串（""）可以取消所有格式约束，恢复自由输入。

生效规则：

• 调用后立即生效；
• 输入框会自动显示分隔符和占位字符（如下划线）；
• 用户只能输入符合掩码规则的字符，不符合的字符会被直接拒绝（敲键盘没反应）。

调用示例：

// 示例1：设置手机号格式约束（仅允许输入11位数字，未输入位置显示下划线）
ui->lineEdit->setInputMask("99999999999;_");
// 此时输入框显示 "___________"，用户只能输入数字，输满11位就不能再输了

// 示例2：设置日期格式约束（年-月-日）
ui->lineEdit->setInputMask("9999-99-99;_");
// 此时输入框显示 "____-__-__"，用户输入时 "-" 会自动保留，不用手动输

// 示例3：取消所有格式约束（恢复自由输入）
ui->lineEdit->setInputMask("");

2.3.4 关键注意事项

2.4 属性四：maxLength（最大长度）—— 最多能输多少个字？

2.4.1 属性的核心定义

maxLength 属性用于限制 QLineEdit 允许输入的最大字符数量。

通俗理解：这个属性就像 “电子写字板的大小限制”—— 比如你规定写字板最多只能写 11 个字，用户写满 11 个字后，再敲键盘就没反应了，写不进去了；如果你用代码设置超过 11 个字的内容，Qt 会自动把后面的字砍掉，只保留前 11 个。

这里有几个非常重要的规则，必须牢记：

2.4.2 数据类型

int 类型，非负整数（length ≥ 0）。

2.4.3 关联 API 详解（逐词逐句，零模糊）

1. 获取当前最大长度：int maxLength () const

函数原型：

int QLineEdit::maxLength() const;

逐词逐句底层解析：

• int：返回值类型，返回当前设置的最大字符数；
• QLineEdit::：成员函数；
• maxLength()：函数名，“获取最大长度” 的意思；
• const：常成员函数。

返回值说明：

• 返回 int 类型的整数；
• 默认返回 32767（无实际限制）。

调用示例：

int maxLen = ui->lineEdit->maxLength();
qDebug() << "当前输入框最大长度：" << maxLen;

2. 设置最大长度：void setMaxLength (int length)

函数原型：

void QLineEdit::setMaxLength(int length);

逐词逐句底层解析：

• void：无返回值；
• QLineEdit::：成员函数；
• setMaxLength()：函数名，“设置最大长度” 的意思；
• int length：入参，length 是最大字符数（非负整数）。

参数说明：

• length：非负整数（length ≥ 0）；
• 如果 length = 0，表示无长度限制（等价于默认值 32767）。

生效规则：

• 调用后立即生效；
• 如果当前输入框的文本长度已经超过了新的 maxLength，会自动截断为前 maxLength 个字符；
• 截断操作会触发 textChanged() 信号。

调用示例：

// 示例1：限制输入框最多输入11个字符（适配手机号场景）
ui->lineEdit->setMaxLength(11);
// 此时用户输入满11个字符后，再敲键盘没反应

// 示例2：代码设置超出长度的文本（会自动截断）
ui->lineEdit->setMaxLength(11);
ui->lineEdit->setText("1380013800012345"); // 这个字符串有16个字符
qDebug() << ui->lineEdit->text(); // 输出 "13800138000"（自动截断为前11位）

// 示例3：取消长度限制（恢复默认）
ui->lineEdit->setMaxLength(0);

2.4.4 关键注意事项

示例代码：

#include "widget.h"
#include "ui_widget.h"
#include <QLineEdit>

Widget::Widget(QWidget *parent)
: QWidget(parent)
, ui(new Ui::Widget)
{
ui->setupUi(this);

//OK，那么本文件我们来学习QLineEdit的text属性、frame属性、inputMask属性、maxLength属性
//其中frame属性最简单，就是控制QLineEdit输入框要不要有边框，要的话就是true，不然则为false
//而maxLength属性则是控制QLineEdit输入框用户最多能输入多少个长度的字符，传入整数
//inputMask属性则是控制QLineEdit输入框中用户的输入格式，即只能输入什么样的数据格式，不能输入什么样的格式，这个一般要用到正则表达式
//最后的text属性，则是获取QLineEdit输入框中用户输入的数据给我们，亦或者我们也可以设置最开始QLineEdit输入框中的数据~~

/**
* @class QLineEdit 核心基础属性
* @brief QLineEdit单行输入框的核心基础属性，覆盖文本内容、输入约束、长度限制、视觉边框四大核心维度
* @details 以下属性是QLineEdit最基础且高频使用的核心配置，决定了输入框的内容存储、输入规则、容量限制和基础视觉样式，适用于所有单行文本输入场景。
*
* ===================================== 属性1：text =====================================
* @property QLineEdit::text
* @brief QLineEdit输入框的核心文本内容属性
* @details 该属性存储输入框当前的全部文本内容，默认值为空字符串（""）；
* 支持两种修改方式：① 用户手动输入/删除；② 代码调用setText()/clear()修改；
* 文本修改后会触发差异化信号：代码修改仅触发textChanged()，用户操作同时触发textChanged()和textEdited()。
*
* 【关联API详解】
* 1. QString text() const
* – 功能：获取输入框当前的文本内容
* – 返回值：QString类型，空输入框返回空字符串
*
* 2. void setText(const QString &text)
* – 功能：通过代码设置输入框文本
* – 参数：text – 目标文本字符串（支持任意可显示字符，含中文、符号等）
* – 注意：代码设置会触发textChanged()信号，但不会触发textEdited()信号
*
* 3. void clear()
* – 功能：快速清空输入框文本（等价于setText("")）
* – 注意：清空操作会触发textChanged()信号
*
* @使用示例：
* // 设置文本内容（代码修改，触发textChanged()）
* ui->lineEdit->setText("Qt LineEdit Demo");
* // 获取文本内容并输出
* qDebug() << "当前输入框文本：" << ui->lineEdit->text(); // 输出"Qt LineEdit Demo"
* // 清空文本
* ui->lineEdit->clear();
*
* 【关键注意事项】
* 1. 文本内容始终为单行：即使传入含换行符（\\n）的字符串，换行符会被自动过滤，仅保留单行内容；
* 2. 空文本判定：text().isEmpty()可准确判断输入框是否为空，无需额外校验；
* 3. 信号触发规则：代码修改仅触发textChanged()，是区分“用户操作”和“代码操作”的核心依据。
*
* ===================================== 属性2：inputMask =====================================
* @property QLineEdit::inputMask
* @brief QLineEdit输入内容的格式约束掩码属性
* @details 该属性通过预定义的掩码规则强制限制输入格式（如手机号、日期、IP地址等），输入不符合掩码规则的字符会被直接拒绝（无法输入）；
* 默认值为空字符串（""），表示无格式约束，用户可输入任意字符；
* 掩码格式由“占位符+分隔符+终止符”组成（终止符通常为;，后跟默认占位字符，如_）。
*
* 【常用掩码规则示例】
* | 掩码规则 | 约束效果 | 输入示例 | 说明 |
* |——————-|—————————|——————-|————————–|
* | 9999-99-99;_ | 年月日格式（4位年-2位月-2位日） | 2026-03-08 | 9表示仅允许输入数字 |
* | 000.000.000.000;_ | IP地址格式 | 192.168.1.1 | 0表示必须输入数字（补0） |
* | 99999999999;_ | 11位手机号格式 | 13800138000 | 仅允许输入11位数字 |
*
* 【关联API详解】
* 1. QString inputMask() const → 获取当前设置的输入掩码；
* 2. void setInputMask(const QString &mask)
* – 功能：设置输入格式掩码，传入空字符串可取消所有格式约束
* – 参数：mask – 掩码规则字符串，空字符串表示无约束
*
* @使用示例：
* // 设置手机号格式约束（仅允许输入11位数字）
* ui->lineEdit->setInputMask("99999999999;_");
* // 取消格式约束
* ui->lineEdit->setInputMask("");
*
* 【关键注意事项】
* 1. 掩码优先级高于maxLength：掩码限定的长度会覆盖maxLength（如手机号掩码限定11位，maxLength设为20仍仅能输入11位）；
* 2. 分隔符自动填充：掩码中的分隔符（如-、.）会自动显示在输入框中，用户无需手动输入；
* 3. 仅约束输入：掩码不影响代码设置setText()（如代码可设置不符合掩码的文本），仅约束用户输入。
*
* ===================================== 属性3：maxLength =====================================
* @property QLineEdit::maxLength
* @brief QLineEdit允许输入的最大字符长度属性
* @details 该属性限制输入框可容纳的最大字符数量，默认值为32767（无实际业务限制）；
* 超出最大长度时：① 用户无法输入新字符；② 代码调用setText()会自动截断超出部分的文本。
*
* 【关联API详解】
* 1. int maxLength() const → 获取当前设置的最大字符长度；
* 2. void setMaxLength(int length)
* – 功能：设置最大字符长度
* – 参数：length – 非负整数（length=0表示无长度限制，等价于默认值）
*
* @使用示例：
* // 限制输入框最多输入11个字符（适配手机号场景）
* ui->lineEdit->setMaxLength(11);
* // 代码设置超出长度的文本（会自动截断为前11位）
* ui->lineEdit->setText("1380013800012345");
* qDebug() << ui->lineEdit->text(); // 输出"13800138000"
*
* 【关键注意事项】
* 1. 长度单位为“字符数”：不是字节数，中文、英文、数字均计为1个字符（如“Qt编程”计为4个字符）；
* 2. 截断规则：代码设置超长文本时，仅保留前maxLength个字符，无任何警告/报错；
* 3. 掩码兼容：若inputMask限定的长度小于maxLength，以掩码长度为准；反之则以maxLength为准。
*
* ===================================== 属性4：frame =====================================
* @property QLineEdit::frame
* @brief QLineEdit是否显示视觉边框的属性
* @details 该属性控制输入框是否绘制系统默认的矩形边框，默认值为true（显示边框）；
* 设为false时，输入框无任何视觉边框，仅显示文本内容，适用于需要融入界面风格的场景（如搜索框、内嵌式输入框）。
*
* 【关联API详解】
* 1. bool hasFrame() const
* – 功能：获取输入框是否显示边框（注意方法名不是isFrame()）
* – 返回值：true显示边框（默认），false隐藏边框
*
* 2. void setFrame(bool enable)
* – 功能：设置是否显示边框
* – 参数：enable – true显示边框，false隐藏边框
*
* @使用示例：
* // 隐藏输入框边框（仅显示文本，无视觉框体）
* ui->lineEdit->setFrame(false);
* // 恢复显示边框
* ui->lineEdit->setFrame(true);
*
* 【关键注意事项】
* 1. 仅影响视觉：隐藏边框不影响输入框的任何交互功能（输入、选中、拖拽等均正常）；
* 2. 样式兼容：若通过setStyleSheet()自定义了边框样式，frame属性会被样式表覆盖；
* 3. 焦点提示：隐藏边框后，输入框获焦时无默认的边框高亮，需通过样式表自定义焦点样式。
*/

QLineEdit* lineedit=new QLineEdit(this);

//设置最开始输入框显示的文本
lineedit->setText("18888888888");

//获取到输入框中的文本
QString s=lineedit->text();

//设置该输入框没有边框（默认是有边框的）
lineedit->setFrame(false);

//设置该输入框最大输入长度为11
lineedit->setMaxLength(11);

//设置该输入框的格式只能为电话号码格式
lineedit->setInputMask("999-9999-9999");

//总而言之，还是比较简单的~~~
}

Widget::~Widget()
{
delete ui;
}

第三章 QLineEdit 核心属性详解（二）：显示与提示属性（echoMode、placeholderText）

讲完了四个基础属性，我们接下来讲两个和 “显示” 与 “提示” 相关的核心属性：echoMode（显示模式）、placeholderText（占位提示文本）。这两个属性非常常用，特别是 echoMode，它是实现密码框的核心！

3.1 属性五：echoMode（显示模式）—— 密码框的核心！

3.1.1 属性的核心定义

echoMode 属性是 QLineEdit 用于控制输入文本视觉展示方式的属性 —— 它是实现密码隐藏、隐私输入保护的核心配置。

通俗理解：这个属性就像 “电子写字板的显示模式”—— 有的模式是 “你写什么就显示什么”（普通模式）；有的模式是 “你写的字都变成星号（*）或圆点（●）”（密码模式）；还有的模式是 “你写什么都不显示，写字板看起来始终是空的”（无显示模式，高安全级别）。

这里有几个非常重要的规则，必须牢记：

3.1.2 枚举值详解（QLineEdit::EchoMode，必知！）

我把 echoMode 的三个枚举值列在下面，用表格展示，讲清楚每个值的功能、效果和适用场景：

我再用大白话分别解释一下这三个模式：

3.1.3 关联 API 详解（逐词逐句，零模糊）

1. 获取当前显示模式：QLineEdit::EchoMode echoMode () const

函数原型：

QLineEdit::EchoMode QLineEdit::echoMode() const;

逐词逐句底层解析：

• QLineEdit::EchoMode：返回值类型，返回 echoMode 枚举值；
• QLineEdit::：成员函数；
• echoMode()：函数名，“获取显示模式” 的意思；
• const：常成员函数。

返回值说明：

• 返回 QLineEdit::Normal、QLineEdit::Password 或 QLineEdit::NoEcho；
• 默认返回 QLineEdit::Normal。

调用示例：

QLineEdit::EchoMode mode = ui->lineEdit->echoMode();
if (mode == QLineEdit::Normal) {
qDebug() << "当前是正常显示模式";
} else if (mode == QLineEdit::Password) {
qDebug() << "当前是密码隐藏模式";
} else if (mode == QLineEdit::NoEcho) {
qDebug() << "当前是无显示模式";
}

2. 设置显示模式：void setEchoMode (QLineEdit::EchoMode mode)

函数原型：

void QLineEdit::setEchoMode(QLineEdit::EchoMode mode);

逐词逐句底层解析：

• void：无返回值；
• QLineEdit::：成员函数；
• setEchoMode()：函数名，“设置显示模式” 的意思；
• QLineEdit::EchoMode mode：入参，mode 是目标显示模式枚举值。

参数说明：

• mode：QLineEdit::Normal、QLineEdit::Password 或 QLineEdit::NoEcho。

生效规则：

• 调用后立即生效，无需刷新输入框；
• 已输入的文本会同步切换显示样式（比如之前是 Normal 模式显示 “123”，切换到 Password 模式后立即变成 “***”）；
• 不影响 text() 的内容，text() 始终返回原始文本。

调用示例：

// 示例1：普通文本输入（默认 Normal 模式，可省略）
ui->lineEdit_user->setEchoMode(QLineEdit::Normal);
ui->lineEdit_user->setPlaceholderText("请输入用户名");

// 示例2：普通密码输入（Password 模式，最常用）
ui->lineEdit_pwd->setEchoMode(QLineEdit::Password);
ui->lineEdit_pwd->setPlaceholderText("请输入密码");
// 此时用户输入 "123456"，输入框显示 "******"，但 text() 返回 "123456"

// 示例3：高安全密码输入（NoEcho 模式）
ui->lineEdit_high_pwd->setEchoMode(QLineEdit::NoEcho);
ui->lineEdit_high_pwd->setPlaceholderText("请输入核心密码");
// 此时用户输入任何内容，输入框看起来都是空的，但 text() 仍能获取到

3.1.4 关键注意事项（必知！）

3.2 属性六：placeholderText（占位提示文本）—— 空的时候显示提示！

3.2.1 属性的核心定义

placeholderText 属性是 QLineEdit 用于空状态下显示占位提示文本的属性 —— 它是提升用户操作引导性的关键配置。

通俗理解：这个属性就像 “电子写字板上的浅灰色提示小字”—— 当写字板上什么都没写的时候，它会显示一行浅灰色的字，比如 “请输入用户名”“请输入手机号”“请输入搜索关键词…”，告诉你这里应该填什么；当你开始写字的时候，这行浅灰色的字就会自动消失；当你把写的字都删掉的时候，它又会自动出现。

这里有几个非常重要的规则，必须牢记：

3.2.2 数据类型

QString 类型，支持中文、英文、符号等，建议简洁明了，适配输入框宽度。

3.2.3 关联 API 详解（逐词逐句，零模糊）

1. 获取当前占位提示文本：QString placeholderText () const

函数原型：

QString QLineEdit::placeholderText() const;

逐词逐句底层解析：

• QString：返回值类型，返回当前设置的占位提示文本；
• QLineEdit::：成员函数；
• placeholderText()：函数名，“获取占位提示文本” 的意思；
• const：常成员函数。

返回值说明：

• 返回当前设置的占位提示文本；
• 如果没有设置，返回空字符串（""）。

调用示例：

QString placeholder = ui->lineEdit->placeholderText();
if (placeholder.isEmpty()) {
qDebug() << "当前无占位提示";
} else {
qDebug() << "当前占位提示：" << placeholder;
}

2. 设置占位提示文本：void setPlaceholderText (const QString &text)

函数原型：

void QLineEdit::setPlaceholderText(const QString &text);

逐词逐句底层解析：

• void：无返回值；
• QLineEdit::：成员函数；
• setPlaceholderText()：函数名，“设置占位提示文本” 的意思；
• const QString &text：入参，text 是提示文案。

参数说明：

• text：提示文案，QString 类型；
• 支持中文、英文、符号等，建议简洁明了，适配输入框宽度（太长会超出可视区域）；
• 支持国际化翻译（比如通过 tr() 包裹文案：setPlaceholderText(tr("Please enter username"))）。

生效规则：

• 调用后立即生效；
• 仅当 text() 为空时显示，有文本时自动隐藏；
• 不影响 text 属性，不触发任何信号。

调用示例：

// 示例1：搜索框占位提示
ui->lineEdit_search->setPlaceholderText("请输入搜索关键词…");

// 示例2：手机号输入框占位提示（结合 maxLength）
ui->lineEdit_phone->setPlaceholderText("请输入11位手机号");
ui->lineEdit_phone->setMaxLength(11);

// 示例3：密码框占位提示（结合 echoMode）
ui->lineEdit_pwd->setEchoMode(QLineEdit::Password);
ui->lineEdit_pwd->setPlaceholderText("请输入6-16位密码");

3.2.4 关键注意事项

示例代码：

#include "widget.h"
#include "ui_widget.h"
#include <QLineEdit>

Widget::Widget(QWidget *parent)
: QWidget(parent)
, ui(new Ui::Widget)
{
ui->setupUi(this);
//OK，本文件我们就来学习QLineEdit的echoMode属性、placeHolderText属性
//这两个属性就是比较重要的属性了，各有各的用处
//echoMode属性就是控制输入框中，用户输入的数据要展示为样子的，
//• QLineEdit::Normal ：这是默认值，文本框会显示输入的文本。
//• QLineEdit::Password ：在这种模式下，输入的字符会被隐藏，通常用星号（*）或等号（=）代替。
//• QLineEdit::NoEcho ：在这种模式下，文本框不会显示任何输入的字符。
//看了这个之后，大家就很清楚了，一般是用于输入密码的~~~

//然后是placeHolderText属性，这个属性是负责显示，当输入框中没有数据的时候
//输入框自己就会显示出一个较浅颜色的我们给placeHolderText属性所设置的字符串来~~~

/**
* @class QLineEdit 显示与提示属性
* @brief QLineEdit单行输入框的文本显示模式与空状态提示核心属性，聚焦输入框的视觉展示与用户引导
* @details 以下属性分别控制输入文本的显示方式（如密码隐藏）和空状态下的提示文案，是优化输入框视觉体验、提升用户操作引导性的关键配置，广泛应用于密码框、搜索框、表单输入框等场景。
*
* ===================================== 属性1：echoMode =====================================
* @property QLineEdit::echoMode
* @brief QLineEdit输入文本的显示模式属性（核心用于密码/隐私输入场景）
* @details 该属性控制输入框内文本的视觉展示形式，仅改变字符的显示效果，**不会修改text属性存储的实际文本内容**；
* 默认值为QLineEdit::Normal（正常显示），是实现密码隐藏、隐私输入保护的核心配置。
*
* 【枚举值详解（QLineEdit::EchoMode）】
* | 枚举值 | 中文名称 | 功能说明 | 适用场景 |
* |———————-|—————-|————————————————————————–|——————————|
* | QLineEdit::Normal | 正常显示模式 | 输入什么字符就显示什么字符，无任何隐藏（默认模式）； | 普通文本输入（用户名、搜索内容） |
* | QLineEdit::Password | 密码隐藏模式 | 输入的所有字符均被掩码字符替代（通常为*、=或●，具体样式随系统/样式表变化）； | 普通密码输入（登录密码、支付密码） |
* | QLineEdit::NoEcho | 无显示模式 | 输入的任何字符都不显示，输入框视觉上始终为空（即使text有内容）； | 高安全级隐私输入（核心密码、验证码） |
*
* 【关联API详解】
* 1. QLineEdit::EchoMode echoMode() const
* – 功能：获取当前文本显示模式
* – 返回值：QLineEdit::EchoMode枚举值，默认返回QLineEdit::Normal
*
* 2. void setEchoMode(QLineEdit::EchoMode mode)
* – 功能：设置文本显示模式
* – 参数：mode – 目标显示模式枚举值
* – 生效规则：设置后立即生效，无需刷新输入框，已输入的文本会同步切换显示样式
*
* @使用示例：
* // 场景1：普通文本输入（默认Normal模式）
* ui->lineEdit_user->setEchoMode(QLineEdit::Normal);
* ui->lineEdit_user->setPlaceholderText("请输入用户名");
*
* // 场景2：普通密码输入（Password模式）
* ui->lineEdit_pwd->setEchoMode(QLineEdit::Password);
* ui->lineEdit_pwd->setPlaceholderText("请输入密码"); // 输入"123456"显示为"******"
*
* // 场景3：高安全密码输入（NoEcho模式）
* ui->lineEdit_high_pwd->setEchoMode(QLineEdit::NoEcho);
* ui->lineEdit_high_pwd->setPlaceholderText("请输入核心密码"); // 输入任何内容都无显示
*
* 【关键注意事项】
* 1. 内容不变：无论哪种模式，text()获取的始终是用户实际输入的原始文本（如Password模式下输入"123"，text()仍返回"123"）；
* 2. 光标可见：NoEcho模式下光标仍会正常显示（仅字符隐藏），用户可感知输入位置；
* 3. 样式兼容：掩码字符（如*）可通过QSS样式表自定义（如设置lineEdit { password-character: ●; }）；
* 4. 快捷键兼容：复制/粘贴快捷键在Normal/Password模式下正常生效，NoEcho模式下仍可复制（仅显示隐藏）。
*
* ===================================== 属性2：placeholderText =====================================
* @property QLineEdit::placeholderText
* @brief QLineEdit输入框空状态下的占位提示文本属性
* @details 该属性定义输入框text为空时显示的提示文案（浅灰色、低对比度），输入框有文本时自动隐藏；
* 默认值为空字符串（""），仅用于用户操作引导，**不会被计入text属性**，也不会触发任何文本变更信号。
*
* 【关联API详解】
* 1. QString placeholderText() const
* – 功能：获取当前占位提示文本
* – 返回值：QString类型，空表示未设置占位提示
*
* 2. void setPlaceholderText(const QString &text)
* – 功能：设置空状态下的占位提示文本
* – 参数：text – 提示文案（支持中文、英文、符号等，建议简洁明了）
* – 生效规则：仅当text()为空时显示，有文本时自动隐藏，设置后立即生效
*
* @使用示例：
* // 场景1：搜索框占位提示
* ui->lineEdit_search->setPlaceholderText("请输入搜索关键词…");
*
* // 场景2：手机号输入框占位提示
* ui->lineEdit_phone->setPlaceholderText("请输入11位手机号");
* ui->lineEdit_phone->setMaxLength(11);
*
* // 场景3：密码框占位提示（结合echoMode）
* ui->lineEdit_pwd->setEchoMode(QLineEdit::Password);
* ui->lineEdit_pwd->setPlaceholderText("请输入6-16位密码");
*
* 【关键注意事项】
* 1. 独立于text：占位文本不会影响text()的取值（即使显示占位文本，text()仍为空），也不会被clear()/setText()操作修改；
* 2. 样式自定义：占位文本的颜色、字体可通过QSS修改（如lineEdit { placeholder-text-color: #999; }）；
* 3. 只读兼容：输入框设为readOnly=true时，若text为空，占位文本仍会正常显示；
* 4. 长度限制：占位文本长度无强制限制，但过长会超出输入框可视区域，建议适配输入框宽度精简文案；
* 5. 多语言兼容：支持国际化翻译（如通过tr()包裹文案：setPlaceholderText(tr("Please enter username"))）。
*/

QLineEdit* lineedit=new QLineEdit(this);

//设置显示方式为密码方式
lineedit->setEchoMode(QLineEdit::Password);

//设置输入框内容为空时的提示信息
lineedit->setPlaceholderText("请输入密码");

//总而言之，还是比较简单的~~~
}

Widget::~Widget()
{
delete ui;
}

第四章 QLineEdit 核心属性详解（三）：交互控制属性（dragEnabled、readOnly）

讲完了显示与提示属性，我们接下来讲两个和 “交互控制” 相关的核心属性：dragEnabled（拖拽启用）、readOnly（只读）。这两个属性用于精细化控制输入框的文本交互权限 —— 比如允不允许把文字拖走、允不允许修改文字。

4.1 属性七：dragEnabled（拖拽启用）—— 能不能把文字拖走？

4.1.1 属性的核心定义

dragEnabled 属性用于控制 QLineEdit 是否允许用户拖拽选中的文本。

通俗理解：这个属性就像 “电子写字板上的文字能不能撕下来贴到别的地方”—— 如果允许拖拽，你选中一段文字后，可以用鼠标把它拖到另一个输入框里（或者另一个支持文本输入的控件里），实现快速的文本复制或移动；如果不允许拖拽，你选中文字后，只能用 Ctrl+C 复制，不能用鼠标拖。

这里有几个非常重要的规则，必须牢记：

4.1.2 数据类型

bool 类型，true 表示允许拖拽，false 表示禁止拖拽（默认）。

4.1.3 关联 API 详解（逐词逐句，零模糊）

1. 获取是否允许拖拽：bool dragEnabled () const

函数原型：

bool QLineEdit::dragEnabled() const;

逐词逐句底层解析：

• bool：返回值类型，返回 true 或 false；
• QLineEdit::：成员函数；
• dragEnabled()：函数名，“是否允许拖拽” 的意思；
• const：常成员函数。

返回值说明：

• true 表示允许拖拽；
• false 表示禁止拖拽（默认）。

调用示例：

bool dragEnabled = ui->lineEdit->dragEnabled();
if (dragEnabled) {
qDebug() << "当前允许文本拖拽";
} else {
qDebug() << "当前禁止文本拖拽";
}

2. 设置是否允许拖拽：void setDragEnabled (bool enable)

函数原型：

void QLineEdit::setDragEnabled(bool enable);

逐词逐句底层解析：

• void：无返回值；
• QLineEdit::：成员函数；
• setDragEnabled()：函数名，“设置是否允许拖拽” 的意思；
• bool enable：入参，enable 是 true 允许拖拽，false 禁止拖拽。

参数说明：

• enable：true 允许拖拽，false 禁止拖拽。

生效规则：

• 调用后立即生效；
• 仅影响用户的拖拽操作，不影响其他交互。

调用示例：

// 示例1：启用文本拖拽（适配需要快速复用文本的场景，如表单回填）
ui->lineEdit_src->setDragEnabled(true);
ui->lineEdit_src->setText("需要复用的文本内容");
// 效果：选中该输入框的文本后，可拖拽到 ui->lineEdit_dst 中，自动填充至目标输入框

// 示例2：禁用文本拖拽（默认状态，防止误操作拖拽文本）
ui->lineEdit_src->setDragEnabled(false);

4.1.4 关键注意事项

4.2 属性八：readOnly（只读）—— 只能看不能改？（核心区别于禁用！）

4.2.1 属性的核心定义

readOnly 属性是 QLineEdit 用于控制用户是否可修改文本的属性 —— 它是平衡输入框 “可操作范围” 与 “数据保护” 的关键配置。

通俗理解：这个属性就像 “电子写字板被锁起来了，但你还能看、还能抄”—— 如果设为只读，用户可以点击输入框、可以移动光标、可以选中文本、可以复制文本，但就是不能修改（输入、删除、粘贴都无效）；但你在代码里仍然可以修改 text 属性（比如用 setText() 设置新内容）。

这里有一个超级重要、超级容易搞混的点，必须一开始就说清楚：

⚠️ ⚠️ ⚠️ 超级重要！超级容易搞混！⚠️ ⚠️ ⚠️

readOnly=true（只读）和 setEnabled(false)（禁用控件）是完全不一样的！

我用表格把它们的核心区别列出来，你一定要记清楚：

简单总结：

• 只读（readOnly=true）：“我锁起来不让你改，但你可以看，可以抄”—— 适用于保护已填写的数据、展示可复制的信息；
• 禁用（setEnabled (false)）：“我直接把它关掉，你看都看不清，碰都碰不了”—— 适用于完全不需要交互的场景。

除了这个核心区别，还有几个规则必须牢记：

4.2.2 数据类型

bool 类型，true 表示只读（禁止用户编辑），false 表示可编辑（默认）。

4.2.3 关联 API 详解（逐词逐句，零模糊）

这里有一个小细节要注意：获取函数的名字是 isReadOnly()，符合 Qt 的命名习惯（布尔值的获取函数通常以 is 开头）。

1. 获取是否为只读：bool isReadOnly () const

函数原型：

bool QLineEdit::isReadOnly() const;

逐词逐句底层解析：

• bool：返回值类型，返回 true 或 false；
• QLineEdit::：成员函数；
• isReadOnly()：函数名，“是不是只读” 的意思；
• const：常成员函数。

返回值说明：

• true 表示只读（禁止用户编辑）；
• false 表示可编辑（默认）。

调用示例：

bool isReadOnly = ui->lineEdit->isReadOnly();
if (isReadOnly) {
qDebug() << "当前输入框为只读状态";
} else {
qDebug() << "当前输入框为可编辑状态";
}

2. 设置是否为只读：void setReadOnly (bool readOnly)

函数原型：

void QLineEdit::setReadOnly(bool readOnly);

逐词逐句底层解析：

• void：无返回值；
• QLineEdit::：成员函数；
• setReadOnly()：函数名，“设置是否只读” 的意思；
• bool readOnly：入参，readOnly 是 true 设为只读，false 恢复可编辑。

参数说明：

• readOnly：true 设为只读，false 恢复可编辑。

生效规则：

• 调用后立即生效；
• 设为只读后，用户无法修改文本，但仍可选中、复制、移动光标；
• 代码仍可修改文本。

调用示例：

// 示例1：表单提交后，将输入框设为只读（保护已填写数据）
ui->lineEdit_username->setText("ZhangSan");
ui->lineEdit_username->setReadOnly(true);
// 效果：用户可选中/复制“ZhangSan”，但无法修改，光标仍可移动

// 示例2：代码层面修改只读输入框的文本（仍生效）
ui->lineEdit_readonly->setReadOnly(true);
ui->lineEdit_readonly->setText("代码修改的只读文本"); // 可正常设置，text() 返回该内容，触发 textChanged()

// 示例3：恢复可编辑状态
ui->lineEdit_username->setReadOnly(false);

4.2.4 关键注意事项（必知！）

示例代码：

#include "widget.h"
#include "ui_widget.h"
#include <QLineEdit>

Widget::Widget(QWidget *parent)
: QWidget(parent)
, ui(new Ui::Widget)
{
ui->setupUi(this);

//OK，那么本文件我们就来学习QLineEdit的dragEnabled属性以及readOnly属性
//readOnly属性就是设置输入框内的数据是否是只读的(不允许修改)，默认为false，一般也是为false
//dragEnabled属性就是设置输入框内的数据是否能被拖拽用到别的地方去，这个大家也不陌生了~~~

/**
* @class QLineEdit 交互控制属性
* @brief QLineEdit单行输入框的拖拽与只读核心属性，聚焦文本交互权限的精细化控制
* @details 以下属性分别控制输入框文本的拖拽权限和编辑权限，是平衡输入框“可操作范围”与“数据保护”的关键配置，适用于需要限制文本修改、支持文本复用的场景。
*
* ===================================== 属性1：dragEnabled =====================================
* @property QLineEdit::dragEnabled
* @brief QLineEdit是否允许用户拖拽选中文本的属性
* @details 该属性控制用户是否可通过鼠标拖拽的方式移动/复制输入框内的选中文本，默认值为false（禁止拖拽）；
* 启用拖拽后，选中文本时鼠标指针变为拖拽样式，可将文本拖拽至其他支持文本输入的控件（如另一个QLineEdit、QTextEdit），实现快速文本复用。
*
* 【关联API详解】
* 1. bool dragEnabled() const
* – 功能：获取当前是否允许文本拖拽
* – 返回值：true允许拖拽，false禁止拖拽（默认）
*
* 2. void setDragEnabled(bool enable)
* – 功能：设置是否允许文本拖拽
* – 参数：enable – true启用拖拽，false禁用拖拽
*
* @使用示例：
* // 启用文本拖拽（适配需要快速复用文本的场景，如表单回填）
* ui->lineEdit_src->setDragEnabled(true);
* ui->lineEdit_src->setText("需要复用的文本内容");
* // 效果：选中该输入框的文本后，可拖拽到ui->lineEdit_dst中，自动填充至目标输入框
*
* // 禁用文本拖拽（默认状态，防止误操作拖拽文本）
* ui->lineEdit_src->setDragEnabled(false);
*
* 【关键注意事项】
* 1. 拖拽前提：必须先选中部分/全部文本才能触发拖拽，无选中文本时拖拽功能不生效；
* 2. 仅影响用户操作：禁用拖拽不影响“复制（Ctrl+C）/粘贴（Ctrl+V）”快捷键，也不影响代码层面的文本复制；
* 3. 拖拽行为：拖拽本质是“移动”还是“复制”，取决于系统设置（通常按住Ctrl键拖拽为复制，直接拖拽为移动）；
* 4. 交互兼容：启用/禁用拖拽不影响输入框的其他核心交互（如输入、选中、光标移动）。
*
* ===================================== 属性2：readOnly =====================================
* @property QLineEdit::readOnly
* @brief QLineEdit是否为只读状态的属性（核心区别于“禁用控件”）
* @details 该属性控制用户是否可修改输入框内的文本，默认值为false（可编辑）；
* 设为只读后，输入框仍保持交互状态（可选中、复制文本，光标正常显示），但用户无法通过键盘/鼠标修改文本（输入、删除、粘贴均无效），代码层面仍可修改text属性。
*
* 【关联API详解】
* 1. bool isReadOnly() const
* – 功能：获取当前是否为只读状态
* – 返回值：true只读（禁止用户编辑），false可编辑（默认）
*
* 2. void setReadOnly(bool readOnly)
* – 功能：设置输入框的只读状态
* – 参数：readOnly – true设为只读，false恢复可编辑
*
* @使用示例：
* // 场景1：表单提交后，将输入框设为只读（保护已填写数据）
* ui->lineEdit_username->setReadOnly(true);
* // 效果：用户可选中/复制“用户名”文本，但无法修改，光标仍可移动
*
* // 场景2：代码层面修改只读输入框的文本（仍生效）
* ui->lineEdit_readonly->setReadOnly(true);
* ui->lineEdit_readonly->setText("代码修改的只读文本"); // 可正常设置，text()返回该内容
*
* 【关键注意事项】
* 1. 只读 vs 禁用（setEnabled(false)）：
* – 只读（readOnly=true）：控件激活状态，可选中/复制文本，光标可见，样式无灰化；
* – 禁用（setEnabled(false)）：控件灰化，无任何交互（无法选中、复制、移动光标）；
* 2. 信号兼容：只读状态下，选中文本仍触发selectionChanged()，光标移动仍触发cursorPositionChanged()；
* 3. 文本修改规则：用户操作无法修改文本，但代码调用setText()/clear()仍可修改，且触发textChanged()信号；
* 4. 清除按钮兼容：若启用了clearButtonEnabled，只读状态下即使有文本，清除按钮也不会显示（防止用户清空）；
* 5. 粘贴禁用：只读状态下，粘贴（Ctrl+V）操作无效，无法向输入框粘贴任何内容。
*/

QLineEdit* lineedit=new QLineEdit(this);

//设置显示方式为密码方式
lineedit->setEchoMode(QLineEdit::Password);

//设置输入框内容为空时的提示信息
lineedit->setPlaceholderText("请输入密码");

//设置输入框为允许拖拽
lineedit->setDragEnabled(true);

//设置输入框为只读
lineedit->setReadOnly(true);
}

Widget::~Widget()
{
delete ui;
}

第五章 QLineEdit 核心属性详解（四）：交互与样式属性（cursorPosition、alignment、clearButtonEnabled）

讲完了交互控制属性，我们最后讲三个和 “交互” 与 “样式” 相关的属性：cursorPosition（光标位置）、alignment（文本对齐）、clearButtonEnabled（清除按钮）。这三个属性用于优化输入框的交互体验和视觉样式，虽然不是最核心的，但非常实用。

5.1 属性九：cursorPosition（光标位置）—— 光标在哪？

5.1.1 属性的核心定义

cursorPosition 属性用于表示和控制 QLineEdit 输入框内光标所在的索引位置。

通俗理解：这个属性就像 “电子写字板上光标在第几个字后面”—— 比如文本是 “Hello”，光标在 “H” 后面，位置就是 0；光标在 “ll” 之间，位置就是 2；光标在 “o” 后面（文本末尾），位置就是 5（因为 “Hello” 有 5 个字符）。

这里有几个非常重要的规则，必须牢记：

5.1.2 数据类型

int 类型，非负整数（从 0 开始）。

5.1.3 关联 API 详解（逐词逐句，零模糊）

1. 获取当前光标位置：int cursorPosition () const

函数原型：

int QLineEdit::cursorPosition() const;

逐词逐句底层解析：

• int：返回值类型，返回当前光标位置（索引）；
• QLineEdit::：成员函数；
• cursorPosition()：函数名，“获取光标位置” 的意思；
• const：常成员函数。

返回值说明：

• 返回 int 类型的整数；
• 0 表示文本开头，text.length() 表示文本末尾。

调用示例：

// 先设置文本
ui->lineEdit->setText("Hello"); // 文本长度为 5
// 获取光标位置
int pos = ui->lineEdit->cursorPosition();
qDebug() << "当前光标位置：" << pos; // 默认返回 0（文本开头）

2. 设置光标位置：void setCursorPosition (int pos)

函数原型：

void QLineEdit::setCursorPosition(int pos);

逐词逐句底层解析：

• void：无返回值；
• QLineEdit::：成员函数；
• setCursorPosition()：函数名，“设置光标位置” 的意思；
• int pos：入参，pos 是目标光标位置（非负整数）。

参数说明：

• pos：目标光标位置，非负整数；
• 超出有效范围会自动修正。

生效规则：

• 调用后立即生效；
• 光标会立即移动到目标位置；
• 会触发 cursorPositionChanged(int old, int new) 信号；
• 如果存在选中文本，会取消选中状态。

调用示例：

// 先设置基础文本
ui->lineEdit->setText("Qt Input Demo"); // 文本长度为 11
// 将光标移动到第 5 个字符后（索引 5，对应 "Input" 开头）
ui->lineEdit->setCursorPosition(5);
qDebug() << "当前光标位置：" << ui->lineEdit->cursorPosition(); // 输出 5
// 尝试设置超出范围的位置（自动修正为文本末尾 11）
ui->lineEdit->setCursorPosition(20);
qDebug() << "修正后光标位置：" << ui->lineEdit->cursorPosition(); // 输出 11

5.1.4 关键注意事项

5.2 属性十：alignment（文本对齐）—— 文字居左、居右还是居中？

5.2.1 属性的核心定义

alignment 属性用于控制 QLineEdit 输入框内文本的排版对齐方式（支持水平 + 垂直方向配置）。

通俗理解：这个属性就像 “电子写字板上的字怎么摆”—— 你可以让字靠左摆（左对齐）、靠右摆（右对齐）、摆在中间（居中对齐）；垂直方向默认就是居中的，没法改。

这里有几个非常重要的规则，必须牢记：

5.2.2 常用对齐值详解

我把常用的对齐值列在下面，用表格展示：

5.2.3 关联 API 详解（逐词逐句，零模糊）

1. 获取当前对齐方式：Qt::Alignment alignment () const

函数原型：

Qt::Alignment QLineEdit::alignment() const;

逐词逐句底层解析：

• Qt::Alignment：返回值类型，返回对齐枚举组合值；
• QLineEdit::：成员函数；
• alignment()：函数名，“获取对齐方式” 的意思；
• const：常成员函数。

返回值说明：

• 返回 Qt::Alignment 枚举组合值；
• 默认返回 Qt::AlignLeft | Qt::AlignVCenter。

调用示例：

Qt::Alignment align = ui->lineEdit->alignment();
if (align.testFlag(Qt::AlignLeft)) {
qDebug() << "当前文本左对齐";
} else if (align.testFlag(Qt::AlignRight)) {
qDebug() << "当前文本右对齐";
} else if (align.testFlag(Qt::AlignCenter)) {
qDebug() << "当前文本居中对齐";
}

2. 设置对齐方式：void setAlignment (Qt::Alignment align)

函数原型：

void QLineEdit::setAlignment(Qt::Alignment align);

逐词逐句底层解析：

• void：无返回值；
• QLineEdit::：成员函数；
• setAlignment()：函数名，“设置对齐方式” 的意思；
• Qt::Alignment align：入参，align 是对齐枚举值（可组合水平 + 垂直，仅垂直居中有效）。

参数说明：

• align：对齐枚举值，比如 Qt::AlignLeft、Qt::AlignRight、Qt::AlignCenter。

生效规则：

• 调用后立即生效；
• 文本立即重新排版；
• 选中文本的对齐方式与整体文本一致，不会单独调整。

调用示例：

// 示例1：设置文本为右对齐（适配金额输入场景）
ui->lineEdit->setAlignment(Qt::AlignRight);
ui->lineEdit->setText("1000.00"); // 文本靠右显示

// 示例2：设置文本为居中对齐（适配验证码输入场景）
ui->lineEdit->setAlignment(Qt::AlignCenter);
ui->lineEdit->setText("1234"); // 文本居中显示

5.2.4 关键注意事项

5.3 属性十一：clearButtonEnabled（清除按钮）—— 一键清空！

5.3.1 属性的核心定义

clearButtonEnabled 属性用于控制 QLineEdit 右侧是否根据文本状态自动显示快捷清除按钮（×）。

通俗理解：这个属性就像 “电子写字板旁边的一个小橡皮”—— 当写字板上有字的时候，橡皮就会自动出现在右边；当你点击橡皮，写字板上的字就会被一键清空；当写字板上没字的时候，橡皮就会自动消失。

这里有几个非常重要的规则，必须牢记：

5.3.2 数据类型

bool 类型，true 表示启用（有文本显示按钮），false 表示禁用（始终不显示）。

5.3.3 关联 API 详解（逐词逐句，零模糊）

这里有一个小细节要注意：获取函数的名字是 isClearButtonEnabled()，符合 Qt 的命名习惯（布尔值的获取函数通常以 is 开头）。

1. 获取是否启用清除按钮：bool isClearButtonEnabled () const

函数原型：

bool QLineEdit::isClearButtonEnabled() const;

逐词逐句底层解析：

• bool：返回值类型，返回 true 或 false；
• QLineEdit::：成员函数；
• isClearButtonEnabled()：函数名，“是否启用清除按钮” 的意思；
• const：常成员函数。

返回值说明：

• true 表示启用（有文本显示按钮）；
• false 表示禁用（始终不显示）。

调用示例：

bool clearBtnEnabled = ui->lineEdit->isClearButtonEnabled();
if (clearBtnEnabled) {
qDebug() << "当前启用了清除按钮";
} else {
qDebug() << "当前未启用清除按钮";
}

2. 设置是否启用清除按钮：void setClearButtonEnabled (bool enable)

函数原型：

void QLineEdit::setClearButtonEnabled(bool enable);

逐词逐句底层解析：

• void：无返回值；
• QLineEdit::：成员函数；
• setClearButtonEnabled()：函数名，“设置是否启用清除按钮” 的意思；
• bool enable：入参，enable 是 true 启用，false 禁用。

参数说明：

• enable：true 启用，false 禁用。

生效规则：

• 调用后立即生效；
• 如果输入框有文本，清除按钮会立即显示；
• 点击清除按钮清空文本，触发 textChanged()，不触发 textEdited()。

调用示例：

// 示例：启用清除按钮（适配搜索框、表单输入框，提升用户体验）
ui->lineEdit->setClearButtonEnabled(true);
ui->lineEdit->setPlaceholderText("请输入搜索内容");
ui->lineEdit->setText("测试文本"); // 右侧显示 × 按钮
// 点击清除按钮后，文本清空，按钮自动隐藏，触发 textChanged("")

5.3.4 关键注意事项

#include "widget.h"
#include "ui_widget.h"
#include <QLineEdit>

Widget::Widget(QWidget *parent)
: QWidget(parent)
, ui(new Ui::Widget)
{
ui->setupUi(this);

QLineEdit* lineedit=new QLineEdit(this);

//OK，那么本文件我们就来学习QLineEdit的cursorPosition属性、alignment属性、clearButtonEnabled属性
//这三个属性也是比较简单的啦~~~
//alignment属性我们已经很熟悉了，就是控制输入框中文字的对齐方式，左对齐（默认），右对齐，居中对齐~~~
//而clearButtonEnabled属性则是说要不要在输入框旁边有一个清空按钮，一旦按了这个按钮，就会把它对应的输入框中的数据都清空
//最后的cursorPosition属性，则是控制光标在文本中的索引位置（从0开始计数），默认值为0（文本开头）
//其实也是没有什么用，用默认的就够了，一般我们都是习惯我们输入一个字，光标就后移动一位的~~~

/**
* @class QLineEdit 交互与样式属性
* @brief QLineEdit单行输入框的光标控制、文本对齐、快捷清除三大核心属性，聚焦输入交互体验与视觉样式优化
* @details 以下属性分别控制输入框的光标位置、文本排版对齐方式、快捷清除按钮显隐，是提升输入框交互友好性的关键配置，适用于表单、搜索框等高频交互场景。
*
* ===================================== 属性1：cursorPosition =====================================
* @property QLineEdit::cursorPosition
* @brief QLineEdit输入框内光标所在位置的属性
* @details 该属性表示光标在文本中的索引位置（从0开始计数），默认值为0（文本开头）；
* 光标位置的有效范围是 0 ~ text.length()（光标在文本末尾时，位置等于文本长度），超出范围的设置会被自动修正为最近的有效边界。
*
* 【关联API详解】
* 1. int cursorPosition() const
* – 功能：获取当前光标在文本中的索引位置
* – 返回值：int类型，0表示文本开头，text.length()表示文本末尾
*
* 2. void setCursorPosition(int pos)
* – 功能：手动设置光标位置（支持鼠标/代码两种方式调整）
* – 参数：pos – 目标光标位置（非负整数，超出范围会自动修正）
*
* @使用示例：
* // 先设置基础文本
* ui->lineEdit->setText("Qt Input Demo"); // 文本长度为11
* // 将光标移动到第5个字符后（索引5，对应"Input"开头）
* ui->lineEdit->setCursorPosition(5);
* qDebug() << "当前光标位置：" << ui->lineEdit->cursorPosition(); // 输出5
* // 尝试设置超出范围的位置（自动修正为文本末尾11）
* ui->lineEdit->setCursorPosition(20);
* qDebug() << "修正后光标位置：" << ui->lineEdit->cursorPosition(); // 输出11
*
* 【关键注意事项】
* 1. 索引规则：光标位置是字符之间的间隙，如文本"abc"，位置0在a前，位置1在a和b之间，位置3在c后；
* 2. 信号联动：光标位置变更会触发cursorPositionChanged(int old, int new)信号，可监听光标移动事件；
* 3. 空文本处理：输入框为空时，光标位置固定为0，设置其他值无效；
* 4. 选中文本兼容：若存在选中文本，设置光标位置会取消选中状态，光标定位到目标位置。
*
* ===================================== 属性2：alignment =====================================
* @property QLineEdit::alignment
* @brief QLineEdit输入框内文本的对齐方式属性（支持水平+垂直方向配置）
* @details 该属性控制文本在输入框可视区域内的排版对齐方式，默认值为 Qt::AlignLeft | Qt::AlignVCenter（左对齐+垂直居中）；
* 水平方向支持左/右/居中对齐，垂直方向仅支持居中对齐（设置顶部/底部对齐无视觉效果）。
*
* 【常用对齐值详解】
* | 对齐常量 | 功能说明 | 适用场景 |
* |————————-|——————————|————————|
* | Qt::AlignLeft | 水平左对齐（默认）| 普通表单输入框 |
* | Qt::AlignRight | 水平右对齐 | 金额、数字类输入框 |
* | Qt::AlignCenter | 水平居中对齐 | 验证码、搜索框 |
* | Qt::AlignCenter | Qt::AlignVCenter | 水平+垂直居中（等价于Qt::AlignCenter） | 所有场景默认垂直居中 |
*
* 【关联API详解】
* 1. Qt::Alignment alignment() const
* – 功能：获取当前文本对齐方式
* – 返回值：Qt::Alignment枚举组合值，默认返回Qt::AlignLeft | Qt::AlignVCenter
*
* 2. void setAlignment(Qt::Alignment align)
* – 功能：设置文本对齐方式
* – 参数：align – 对齐枚举值（可组合水平+垂直，仅垂直居中有效）
*
* @使用示例：
* // 设置文本为右对齐（适配金额输入场景）
* ui->lineEdit->setAlignment(Qt::AlignRight);
* ui->lineEdit->setText("1000.00"); // 文本靠右显示
* // 设置文本为居中对齐（适配验证码输入场景）
* ui->lineEdit->setAlignment(Qt::AlignCenter);
*
* 【关键注意事项】
* 1. 垂直对齐限制：Qt::AlignTop/Qt::AlignBottom等垂直对齐值无效果，输入框文本始终垂直居中；
* 2. 实时生效：修改对齐方式后，文本立即重新排版，无需刷新输入框；
* 3. 选中文本兼容：选中文本的对齐方式与整体文本一致，不会单独调整；
* 4. 样式表兼容：若通过样式表设置了text-align属性，会覆盖该属性的配置。
*
* ===================================== 属性3：clearButtonEnabled =====================================
* @property QLineEdit::clearButtonEnabled
* @brief QLineEdit是否自动显示“清除按钮（×）”的属性
* @details 该属性控制输入框右侧是否根据文本状态自动显示快捷清除按钮，默认值为false（不显示）；
* 显隐规则：输入框有文本时显示清除按钮，文本为空时自动隐藏；点击清除按钮会一键清空文本，并触发textChanged()信号。
*
* 【关联API详解】
* 1. bool isClearButtonEnabled() const
* – 功能：获取是否启用清除按钮自动显示功能
* – 返回值：true启用（有文本显示按钮），false禁用（始终不显示）
*
* 2. void setClearButtonEnabled(bool enable)
* – 功能：设置是否启用清除按钮自动显示功能
* – 参数：enable – true启用，false禁用
*
* @使用示例：
* // 启用清除按钮（适配搜索框、表单输入框）
* ui->lineEdit->setClearButtonEnabled(true);
* ui->lineEdit->setText("请输入搜索内容"); // 右侧显示×按钮
* // 点击清除按钮后，文本清空，按钮自动隐藏
*
* 【关键注意事项】
* 1. 触发逻辑：点击清除按钮等价于调用clear()，会触发textChanged()信号，但不会触发textEdited()信号（属于代码操作）；
* 2. 样式自定义：清除按钮的样式可通过QSS（样式表）修改，如调整按钮大小、颜色、位置；
* 3. 兼容性：该属性在Qt 5.2及以上版本支持，低版本需手动实现清除按钮逻辑；
* 4. 只读兼容：输入框设为readOnly=true时，即使启用该属性，清除按钮也不会显示（禁止修改文本）。
*/

//设置最开始输入框显示的文本
lineedit->setText("18888888888");

//获取到输入框中的文本
QString s=lineedit->text();

//设置该输入框没有边框（默认是有边框的）
lineedit->setFrame(false);

//设置该输入框最大输入长度为11
lineedit->setMaxLength(11);

//设置该输入框的格式只能为电话号码格式
lineedit->setInputMask("999-9999-9999");

//设置右对齐
lineedit->setAlignment(Qt::AlignRight);

//设置有清空按钮
lineedit->setClearButtonEnabled(true);

//设置光标位置在第五位
lineedit->setCursorPosition(5);
}

Widget::~Widget()
{
delete ui;
}

第六章 QLineEdit 核心信号详解

讲完了所有核心属性，我们最后来讲 QLineEdit 的核心交互信号。信号是 QLineEdit 与业务逻辑交互的核心桥梁 —— 用户 “移动光标”“编辑完成”“按下回车”“选中文本”“修改文本” 时，QLineEdit 会发出对应的信号，你只需要绑定这些信号的槽函数，就能响应这些操作了。

QLineEdit 有六个核心信号，我们逐个来讲，按照你提供的顺序：cursorPositionChanged、editingFinished、returnPressed、selectionChanged、textChanged、textEdited。

6.1 信号一：cursorPositionChanged (int old, int new)—— 光标移动了！

6.1.1 信号的核心定义

cursorPositionChanged(int old, int new) 是当输入框光标位置发生变化时触发的信号。

通俗理解：这个信号就像 “你在电子写字板上移动了光标”—— 不管你是用鼠标点击移动的，还是用键盘方向键移动的，还是用代码设置的，只要光标位置变了，这个信号就会响。

触发场景：

6.1.2 参数说明

这个信号有两个参数：

• int old：int 类型，光标变更前的原始位置（索引，从 0 开始）；
• int new：int 类型，光标变更后的新位置（索引，从 0 开始）。

6.1.3 信号绑定示例

我们用 Qt5 的 Lambda 表达式来绑定信号，非常方便：

// 绑定 cursorPositionChanged 信号到 Lambda 表达式
connect(ui->lineEdit, &QLineEdit::cursorPositionChanged, this, [=](int oldPos, int newPos){
qDebug() << "光标从位置" << oldPos << "移动到" << newPos;
});

6.1.4 关键注意事项

6.2 信号二：editingFinished ()—— 编辑完成了！（无参数！）

6.2.1 信号的核心定义

editingFinished() 是当输入框编辑行为结束时触发的信号 —— 它是表单提交、输入确认的常用信号。

通俗理解：这个信号就像 “你写完字了，要么按了回车，要么点了别的地方”—— 只要满足这两个条件之一，就表示你编辑完了，这个信号就会响。

触发场景（满足其一即可）：

核心规则：

• 若为输入框设置了验证器（QValidator）或输入掩码，仅当输入内容验证通过时才会触发—— 如果输入内容不符合规则，按回车或失去焦点都不会触发这个信号。

6.2.2 参数说明

这个信号没有参数！—— 你需要通过 text() 主动获取当前输入文本。

6.2.3 信号绑定示例

// 绑定 editingFinished 信号到 Lambda 表达式
connect(ui->lineEdit, &QLineEdit::editingFinished, this, [=](){
// 主动获取当前输入文本
QString input = ui->lineEdit->text();
qDebug() << "输入编辑完成，内容：" << input;
// 这里可以写编辑完成后的业务逻辑，比如提交表单、验证输入
});

6.2.4 关键注意事项

6.3 信号三：returnPressed ()—— 按下回车了！（无参数！）

6.3.1 信号的核心定义

returnPressed() 是当 ** 按下回车键 / 返回键（Enter/Return）** 时触发的信号 —— 它区别于 editingFinished()，仅响应 “回车确认” 操作，失去焦点不会触发。

通俗理解：这个信号就像 “你写完字后，特意按了一下回车键确认”—— 只有按回车才会响，点别的地方不会响。

核心区别于 editingFinished ()：

• returnPressed()：仅在按下回车时触发；
• editingFinished()：按下回车或失去焦点时触发。

核心规则：

• 若设置了验证器 / 输入掩码，必须验证通过（输入内容符合规则）才会触发，否则按回车无反应。

6.3.2 参数说明

这个信号没有参数！—— 你需要通过 text() 主动获取当前输入文本。

6.3.3 信号绑定示例

// 绑定 returnPressed 信号到 Lambda 表达式
connect(ui->lineEdit, &QLineEdit::returnPressed, this, [=](){
// 主动获取当前输入文本
QString input = ui->lineEdit->text();
qDebug() << "回车确认输入，内容：" << input;
// 这里可以写回车确认后的业务逻辑，比如提交搜索、提交表单
});

6.3.4 关键注意事项

6.4 信号四：selectionChanged ()—— 选中的文本变了！（无参数！）

6.4.1 信号的核心定义

selectionChanged() 是当输入框选中文本范围发生变化时触发的信号 —— 它是监听文本选择的核心信号。

通俗理解：这个信号就像 “你在电子写字板上选中了一段文字，或者取消了选中”—— 只要选中的范围变了，这个信号就会响。

触发场景：

6.4.2 参数说明

这个信号没有参数！—— 你需要通过 selectedText() 主动获取当前选中的文本。

6.4.3 信号绑定示例

// 绑定 selectionChanged 信号到 Lambda 表达式
connect(ui->lineEdit, &QLineEdit::selectionChanged, this, [=](){
// 主动获取当前选中的文本
QString selectedText = ui->lineEdit->selectedText();
qDebug() << "选中文本变更：" << selectedText;
});

6.4.4 关键注意事项

6.5 信号五：textChanged (const QString &text)—— 文本变了！（代码 / 用户都触发！）

6.5.1 信号的核心定义

textChanged(const QString &text) 是当输入框文本内容发生变化时触发的信号 —— 它是监听文本内容变化的最通用信号，任何文本变更都会触发。

通俗理解：这个信号就像 “电子写字板上的字变了”—— 不管是你用键盘输入的、删除的、粘贴的，还是用代码设置的、清空的，只要字变了，这个信号就会响。

触发场景（全覆盖！）：

6.5.2 参数说明

这个信号有一个参数：

• const QString &text：QString 类型，文本变化后的新内容（空文本时传入空字符串）。

6.5.3 信号绑定示例

// 绑定 textChanged 信号到 Lambda 表达式
connect(ui->lineEdit, &QLineEdit::textChanged, this, [=](const QString &newText){
qDebug() << "文本已修改（代码/用户）：" << newText;
// 这里可以写文本变更后的业务逻辑，比如实时验证、实时搜索
});

6.5.4 关键注意事项（超级重要！）

6.6 信号六：textEdited (const QString &text)—— 文本变了！（仅用户操作触发！）

6.6.1 信号的核心定义

textEdited(const QString &text) 是当输入框文本内容发生变化时触发的信号 —— 它精准区分 “用户手动修改” 和 “代码自动修改”，仅响应用户的输入操作。

通俗理解：这个信号就像 “只有你用手在电子写字板上写字、擦字，它才会响；如果是别人（代码）帮你写的、擦的，它不会响”。

核心区别于 textChanged ()（超级重要！必知！）：我用表格把它们的核心区别列出来，你一定要记清楚：

触发场景（仅用户操作！）：

• 仅用户手动输入 / 删除 / 粘贴文本（代码操作不触发）。

6.6.2 参数说明

这个信号有一个参数：

• const QString &text：QString 类型，用户操作后的新文本内容（空文本时传入空字符串）。

6.6.3 信号绑定示例

// 绑定 textEdited 信号到 Lambda 表达式
connect(ui->lineEdit, &QLineEdit::textEdited, this, [=](const QString &newText){
qDebug() << "用户手动修改文本：" << newText; // 代码调用 setText() 不会触发此输出
// 这里可以写仅响应用户输入的业务逻辑，比如实时验证用户输入
});

6.6.4 关键注意事项（超级重要！）

信号示例代码：

#include "widget.h"
#include "ui_widget.h"
#include <QLineEdit>
#include <QDebug>

Widget::Widget(QWidget *parent)
: QWidget(parent)
, ui(new Ui::Widget)
{
ui->setupUi(this);
//OK，那么本文件我们就来学习QLineEdit的一些核心信号，其实就是用于获取用户在输入框中输入的数据，然后我们在后端中进行使用~~~
//首先是cursorPositionChanged信号，这个信号就是当用户在输入框中移动鼠标光标的时候会发出这个信号来~~~
//说实话，这个信号没什么用~~~谁会关心用户鼠标移动~~~
//这个信号会给两个参数，一个是之前的光标位置，一个是新的光标位置，都是int类型

//然后是editingFinished信号，这个信号就是当用户按返回或者回车键的时候，或者用户把鼠标点到输入框外的地方了之后
//就会触发这个信号，这个信号还是比较关键的，一般就是使用这个信号然后去获取到用户输入到输入框中的数据~~~

//接着是returnPressed信号，这个信号和上面的editingFinished信号一样，只不过这个信号是只当用户按下返回和回车键的时候，才会触发该信号
//当把鼠标点到输入框外的地方之外，就不会触发这个信号了~~~

//再接着是selectionChanged信号，这个信号就是当用户选中的文本改变的时候，就会发出这个信号~~~
//也没有什么用，一样没有参数

//再接着是textChanged信号，这个信号就是当QLineEdit中的文本改变时，发出此信号，text是新的文本。代码对文本的修改能够触发这个信号.
//这个的参数就是text~~~

//最后是textEdited信号，这个信号也是当QLineEdit中的文本改变时，发出此信号，text是新的文本。区别就是代码对文本的修改不能触发这个信号.
//这个的参数也是text哦

/**
* @class QLineEdit 核心交互信号
* @brief QLineEdit单行输入框的核心交互信号，覆盖光标移动、编辑完成、回车确认、文本选择变更、文本内容修改等关键交互场景
* @details 这些信号是QLineEdit与业务逻辑交互的核心桥梁，不同信号对应不同的用户/代码操作场景，需根据业务需求精准绑定，区分触发条件与参数规则。
*
* ===================================== 信号1：cursorPositionChanged(int old, int new) =====================================
* @signal void QLineEdit::cursorPositionChanged(int old, int new)
* @brief 输入框光标位置发生变化时触发的信号
* @details 触发场景覆盖所有导致光标位置变更的操作，是监听光标移动的核心信号；
* 【触发场景】：
* 1. 鼠标点击输入框内不同位置调整光标；
* 2. 键盘方向键（←/→）移动光标；
* 3. 代码调用setCursorPosition()手动设置光标位置；
* 4. 选中文本后取消选中，光标定位到选中区域边缘。
* @参数说明：
* @param old – int类型，光标变更前的原始位置（索引，从0开始）；
* @param new – int类型，光标变更后的新位置（索引，从0开始）。
* @使用示例：
* connect(ui->lineEdit, &QLineEdit::cursorPositionChanged, this, [=](int oldPos, int newPos){
* qDebug() << "光标从位置" << oldPos << "移动到" << newPos;
* });
*
* 【关键注意事项】
* 1. 位置索引规则：光标位置是字符间隙，如文本"abc"，位置0在a前，位置3在c后；
* 2. 空文本处理：输入框为空时，光标位置固定为0，该信号仅在首次聚焦时触发一次；
* 3. 选中文本联动：选中文本时修改光标位置会取消选中，同时触发该信号和selectionChanged()信号。
*
* ===================================== 信号2：editingFinished() =====================================
* @signal void QLineEdit::editingFinished()
* @brief 输入框编辑完成时触发的信号（无参数）
* @details 触发场景聚焦“编辑行为结束”，是表单提交、输入确认的常用信号；
* 【触发场景（满足其一即可）】：
* 1. 按下回车键/返回键（Enter/Return）；
* 2. 输入框失去焦点（如点击其他控件、切换窗口）；
* 【核心规则】：若为输入框设置了验证器（QValidator）/输入掩码，仅当输入内容验证通过时才会触发。
* @使用示例：
* connect(ui->lineEdit, &QLineEdit::editingFinished, this, [](){
* qDebug() << "输入编辑完成，可提交数据";
* });
*
* 【关键注意事项】
* 1. 无参数：需通过text()主动获取当前输入文本；
* 2. 失去焦点触发：即使未输入任何内容，失去焦点也会触发（验证器允许空值时）；
* 3. 只读兼容：输入框设为readOnly=true时，该信号不会触发（无编辑行为）。
*
* ===================================== 信号3：returnPressed() =====================================
* @signal void QLineEdit::returnPressed()
* @brief 按下回车键/返回键（Enter/Return）时触发的信号（无参数）
* @details 核心区别于editingFinished()：仅响应“回车确认”操作，失去焦点不会触发；
* 【核心规则】：若设置了验证器/输入掩码，必须验证通过（输入内容符合规则）才会触发，否则按回车无反应。
* @使用示例：
* connect(ui->lineEdit, &QLineEdit::returnPressed, this, [=](){
* QString input = ui->lineEdit->text();
* qDebug() << "回车确认输入：" << input;
* });
*
* 【关键注意事项】
* 1. 触发优先级：回车操作会先触发returnPressed()，再触发editingFinished()；
* 2. 无参数：需主动调用text()获取输入内容；
* 3. 密码框兼容：echoMode=Password/NoEcho时，回车仍可正常触发该信号。
*
* ===================================== 信号4：selectionChanged() =====================================
* @signal void QLineEdit::selectionChanged()
* @brief 输入框选中文本范围发生变化时触发的信号（无参数）
* @details 触发场景覆盖所有选中文本的变更操作，是监听文本选择的核心信号；
* 【触发场景】：
* 1. 鼠标拖动选中/取消选中文本；
* 2. 键盘快捷键（Ctrl+A全选、Shift+方向键选中文本）；
* 3. 代码调用setSelection()/clearSelection()修改选中范围；
* 4. 选中文本后点击输入框其他位置取消选中。
* @使用示例：
* connect(ui->lineEdit, &QLineEdit::selectionChanged, this, [=](){
* QString selectedText = ui->lineEdit->selectedText();
* qDebug() << "选中文本变更：" << selectedText;
* });
*
* 【关键注意事项】
* 1. 无参数：需通过selectedText()获取当前选中的文本；
* 2. 取消选中触发：即使取消所有选中文本（选中范围为空），也会触发该信号；
* 3. 只读兼容：输入框设为readOnly=true时，选中文本仍会触发该信号。
*
* ===================================== 信号5：textChanged(const QString &text) =====================================
* @signal void QLineEdit::textChanged(const QString &text)
* @brief 输入框文本内容发生变化时触发的信号（代码/用户操作均触发）
* @details 覆盖所有文本变更场景，是监听文本内容变化的最通用信号；
* 【触发场景】：
* 1. 用户手动输入/删除/粘贴文本；
* 2. 代码调用setText()/clear()修改文本；
* 3. 点击清除按钮（clearButtonEnabled=true）清空文本；
* 4. 输入掩码自动过滤字符导致文本变化。
* @参数说明：
* @param text – QString类型，文本变化后的新内容（空文本时传入空字符串）。
* @使用示例：
* connect(ui->lineEdit, &QLineEdit::textChanged, this, [=](const QString &newText){
* qDebug() << "文本已修改（代码/用户）：" << newText;
* });
*
* 【关键注意事项】
* 1. 触发全覆盖：任何文本变更（无论来源）都会触发，包括代码修改；
* 2. 空文本触发：调用clear()或用户删除所有文本时，传入空字符串并触发；
* 3. 初始设置触发：初始化时调用setText()也会触发该信号。
*
* ===================================== 信号6：textEdited(const QString &text) =====================================
* @signal void QLineEdit::textEdited(const QString &text)
* @brief 输入框文本内容发生变化时触发的信号（仅用户操作触发，代码修改不触发）
* @details 核心区别于textChanged()：精准区分“用户手动修改”和“代码自动修改”，适用于仅响应用户输入的场景；
* 【触发场景】：仅用户手动输入/删除/粘贴文本（代码操作不触发）。
* @参数说明：
* @param text – QString类型，用户操作后的新文本内容（空文本时传入空字符串）。
* @使用示例：
* connect(ui->lineEdit, &QLineEdit::textEdited, this, [=](const QString &newText){
* qDebug() << "用户手动修改文本：" << newText; // 代码调用setText()不会触发此输出
* });
*
* 【关键注意事项】
* 1. 触发限制：代码调用setText()/clear()、点击清除按钮均不会触发；
* 2. 用户操作全覆盖：包括鼠标粘贴、键盘输入/删除、输入掩码过滤用户输入等；
* 3. 空文本触发：用户删除所有文本时，传入空字符串并触发。
*/

//我们这里还是用ui界面来，比较方便

}

Widget::~Widget()
{
delete ui;
}

void Widget::on_lineEdit_cursorPositionChanged(int arg1, int arg2)
{
qDebug()<<"old cursor position："<<arg1<<"new cursor position："<<arg2;
}

void Widget::on_lineEdit_editingFinished()
{
qDebug()<<"editingFinished："<<ui->lineEdit->text();
}

void Widget::on_lineEdit_returnPressed()
{
qDebug()<<"returnPressed："<<ui->lineEdit->text();
}

void Widget::on_lineEdit_selectionChanged()
{
qDebug()<<"selectionChanged："<<ui->lineEdit->text();
}

void Widget::on_lineEdit_textChanged(const QString &arg1)
{
qDebug()<<"textChanged："<<arg1;
}

void Widget::on_lineEdit_textEdited(const QString &arg1)
{
qDebug()<<"textEdited："<<arg1;
}

完整示例代码：

#include "widget.h"
#include "ui_widget.h"

Widget::Widget(QWidget *parent)
: QWidget(parent)
, ui(new Ui::Widget)
{
ui->setupUi(this);

//OK，那么接下来我们来学习输入类控件，首当其冲的就是QLineEdit
//这个控件其实是比较重要的，平时我们输入姓名啊，密码啊，账号什么的，都是使用这个控件的哦~~~
//它其实就是一个输入框，我们平时没少见的~~~

/**
* @class QLineEdit
* @brief Qt中用于单行文本输入交互的核心控件
* @details QLineEdit是Qt Widgets模块提供的单行文本输入框，仅支持单行文本输入（无法换行），内置文本格式约束、密码隐藏、光标控制、只读保护等核心能力；
* 支持丰富的交互信号（文本变更、光标移动、回车确认等），是桌面端表单输入、搜索框、密码框等场景的首选控件；
* 核心特征：单行输入、格式校验、多显示模式、占位提示、清除按钮等，可通过验证器（QValidator）/输入掩码强化输入约束。
*
* 【核心属性详解】
*
* ===================================== 属性1：text =====================================
* @property QLineEdit::text
* @brief QLineEdit输入框中的文本内容属性
* @details 该属性存储输入框的当前文本，默认值为空字符串（""）；
* 支持通过代码/用户输入修改，修改后会根据场景触发textChanged()或textEdited()信号（核心区别：代码修改触发textChanged，仅用户操作触发textEdited）。
*
* 【关联API详解】
* 1. QString text() const → 获取当前文本内容；
* 2. void setText(const QString &text) → 设置文本内容（代码修改，触发textChanged()，不触发textEdited()）；
* 3. void clear() → 清空文本（等价于setText("")，触发textChanged()）；
* @示例：
* ui->lineEdit->setText("Hello Qt"); // 设置文本，触发textChanged()
* qDebug() << ui->lineEdit->text(); // 输出"Hello Qt"
*
* ===================================== 属性2：inputMask =====================================
* @property QLineEdit::inputMask
* @brief QLineEdit输入内容的格式约束掩码属性
* @details 该属性通过预定义掩码规则限制输入格式（如手机号、日期、IP地址），输入不符合掩码的字符会被直接拒绝；
* 默认值为空字符串（无约束），掩码格式由“占位符+分隔符+终止符”组成（如手机号掩码："999-9999-9999;"）。
* @常用掩码示例：
* | 掩码规则 | 约束效果 | 输入示例 |
* |—————-|—————————|—————-|
* | 9999-99-99;_ | 日期格式（年-月-日）| 2026-03-08 |
* | 000.000.000.000;_ | IP地址格式 | 192.168.1.1 |
* | 99999999999;_ | 11位手机号 | 13800138000 |
* 【关联API详解】
* 1. QString inputMask() const → 获取当前输入掩码；
* 2. void setInputMask(const QString &mask) → 设置输入掩码（空字符串取消约束）；
* @示例：
* ui->lineEdit->setInputMask("9999-99-99;_"); // 约束为年-月-日格式
*
* ===================================== 属性3：maxLength =====================================
* @property QLineEdit::maxLength
* @brief QLineEdit允许输入的最大字符长度属性
* @details 该属性限制输入框可容纳的最大字符数，默认值为32767（无实际限制）；
* 超出最大长度时，用户无法输入新字符（代码设置setText()会截断超出部分）。
* 【关联API详解】
* 1. int maxLength() const → 获取最大字符长度；
* 2. void setMaxLength(int length) → 设置最大字符长度（length≥0）；
* @示例：
* ui->lineEdit->setMaxLength(11); // 限制最多输入11个字符（适配手机号）
*
* ===================================== 属性4：frame =====================================
* @property QLineEdit::frame
* @brief QLineEdit是否显示边框的属性
* @details 该属性控制输入框是否绘制标准边框，默认值为true（显示边框）；
* 设为false时，输入框无视觉边框，仅显示文本，适用于融入界面风格的场景。
* 【关联API详解】
* 1. bool hasFrame() const → 获取是否显示边框；
* 2. void setFrame(bool enable) → 设置是否显示边框；
* @示例：
* ui->lineEdit->setFrame(false); // 隐藏输入框边框
*
* ===================================== 属性5：echoMode =====================================
* @property QLineEdit::echoMode
* @brief QLineEdit文本的显示模式属性（核心用于密码框）
* @details 该属性控制输入文本的视觉展示方式，默认值为QLineEdit::Normal（正常显示），是实现密码隐藏的核心属性。
* 【枚举值详解（QLineEdit::EchoMode）】
* | 枚举值 | 功能说明 |
* |———————-|————————————————————————–|
* | QLineEdit::Normal | 正常显示（默认），输入什么字符就显示什么，适用于普通文本输入； |
* | QLineEdit::Password | 密码模式，输入字符被掩码替代（通常为*或=），仅隐藏显示，文本内容不变； |
* | QLineEdit::NoEcho | 无显示模式，输入的任何字符都不显示，适用于高安全级别的密码输入； |
* 【关联API详解】
* 1. QLineEdit::EchoMode echoMode() const → 获取显示模式；
* 2. void setEchoMode(QLineEdit::EchoMode mode) → 设置显示模式；
* @示例：
* ui->lineEdit->setEchoMode(QLineEdit::Password); // 设置为密码框，输入显示为*
*
* ===================================== 属性6：cursorPosition =====================================
* @property QLineEdit::cursorPosition
* @brief QLineEdit光标所在位置属性
* @details 该属性表示光标在文本中的索引位置（从0开始），默认值为0（文本开头）；
* 光标位置范围为0~text.length()（光标在文本末尾时等于text.length()）。
* 【关联API详解】
* 1. int cursorPosition() const → 获取当前光标位置；
* 2. void setCursorPosition(int pos) → 设置光标位置（超出范围会自动修正）；
* @示例：
* ui->lineEdit->setText("Hello");
* ui->lineEdit->setCursorPosition(2); // 光标移动到"ll"之间（索引2）
*
* ===================================== 属性7：alignment =====================================
* @property QLineEdit::alignment
* @brief QLineEdit文本的对齐方式属性（水平+垂直）
* @details 该属性控制文本在输入框内的水平和垂直对齐方式，默认值为Qt::AlignLeft | Qt::AlignVCenter（左对齐+垂直居中）；
* 仅支持水平对齐（Left/Right/Center）和垂直居中（VCenter），垂直顶部/底部对齐无效果。
* 【常用对齐值】
* Qt::AlignLeft → 左对齐（默认） | Qt::AlignRight → 右对齐 | Qt::AlignCenter → 居中对齐
* 【关联API详解】
* 1. Qt::Alignment alignment() const → 获取对齐方式；
* 2. void setAlignment(Qt::Alignment align) → 设置对齐方式；
* @示例：
* ui->lineEdit->setAlignment(Qt::AlignCenter); // 文本居中对齐
*
* ===================================== 属性8：dragEnabled =====================================
* @property QLineEdit::dragEnabled
* @brief QLineEdit是否允许文本拖拽的属性
* @details 该属性控制用户是否可拖拽选中的文本（复制/移动），默认值为false（禁止拖拽）；
* 设为true时，选中文本后可拖拽到其他控件（如另一个QLineEdit）。
* 【关联API详解】
* 1. bool dragEnabled() const → 获取是否允许拖拽；
* 2. void setDragEnabled(bool enable) → 设置是否允许拖拽；
* @示例：
* ui->lineEdit->setDragEnabled(true); // 允许拖拽文本
*
* ===================================== 属性9：readOnly =====================================
* @property QLineEdit::readOnly
* @brief QLineEdit是否为只读状态的属性
* @details 该属性控制用户是否可修改文本，默认值为false（可编辑）；
* 设为true时，文本仅可查看/选中/复制，无法编辑（区别于setEnabled(false)：只读仍可选中，禁用则完全不可交互）。
* 【关联API详解】
* 1. bool isReadOnly() const → 获取是否为只读；
* 2. void setReadOnly(bool readOnly) → 设置是否为只读；
* @示例：
* ui->lineEdit->setReadOnly(true); // 设为只读，禁止编辑
*
* ===================================== 属性10：placeholderText =====================================
* @property QLineEdit::placeholderText
* @brief QLineEdit空状态下的占位提示文本属性
* @details 该属性定义输入框为空时显示的提示文字（浅灰色），有文本时自动隐藏，默认值为空字符串；
* 仅用于视觉提示，不会被计入text属性，也不会触发任何信号。
* 【关联API详解】
* 1. QString placeholderText() const → 获取占位提示文本；
* 2. void setPlaceholderText(const QString &text) → 设置占位提示文本；
* @示例：
* ui->lineEdit->setPlaceholderText("请输入手机号"); // 空时显示提示文字
*
* ===================================== 属性11：clearButtonEnabled =====================================
* @property QLineEdit::clearButtonEnabled
* @brief QLineEdit是否显示清除按钮的属性
* @details 该属性控制输入框右侧是否自动显示“清除按钮（×）”，默认值为false（不显示）；
* 设为true时，输入框有文本时显示清除按钮，点击按钮可一键清空文本（触发textChanged()）。
* 【关联API详解】
* 1. bool isClearButtonEnabled() const → 获取是否显示清除按钮；
* 2. void setClearButtonEnabled(bool enable) → 设置是否显示清除按钮；
* @示例：
* ui->lineEdit->setClearButtonEnabled(true); // 显示清除按钮
*
* 【核心信号详解】
*
* ===================================== 信号1：cursorPositionChanged(int old, int new) =====================================
* @signal void QLineEdit::cursorPositionChanged(int old, int new)
* @brief 光标位置发生变化时触发的信号
* @details 触发场景：鼠标点击调整光标位置、键盘方向键移动光标、代码调用setCursorPosition()；
* @参数说明：
* @param old – 光标先前的位置（索引）；
* @param new – 光标新的位置（索引）；
* @示例：
* connect(ui->lineEdit, &QLineEdit::cursorPositionChanged, this, [=](int oldPos, int newPos){
* qDebug() << "光标从" << oldPos << "移动到" << newPos;
* });
*
* ===================================== 信号2：editingFinished() =====================================
* @signal void QLineEdit::editingFinished()
* @brief 编辑完成时触发的信号
* @details 触发场景（满足其一即可）：
* 1. 按下回车键/返回键；
* 2. 输入框失去焦点（如点击其他控件）；
* @关键规则：若设置了验证器（QValidator），仅当输入内容验证通过时才会触发；
* @示例：
* connect(ui->lineEdit, &QLineEdit::editingFinished, this, [](){
* qDebug() << "输入完成，触发业务逻辑";
* });
*
* ===================================== 信号3：returnPressed() =====================================
* @signal void QLineEdit::returnPressed()
* @brief 按下回车键/返回键时触发的信号
* @details 核心区别于editingFinished()：仅在按下回车时触发，失去焦点不触发；
* @关键规则：若设置了验证器，必须验证通过才会触发（如输入格式错误按回车无反应）；
* @示例：
* connect(ui->lineEdit, &QLineEdit::returnPressed, this, [=](){
* submitInput(ui->lineEdit->text()); // 回车提交输入内容
* });
*
* ===================================== 信号4：selectionChanged() =====================================
* @signal void QLineEdit::selectionChanged()
* @brief 选中的文本范围发生变化时触发的信号
* @details 触发场景：鼠标拖动选中文本、键盘快捷键（Ctrl+A）全选、代码调用setSelection()；
* @示例：
* connect(ui->lineEdit, &QLineEdit::selectionChanged, this, [=](){
* QString selected = ui->lineEdit->selectedText(); // 获取选中的文本
* qDebug() << "选中文本：" << selected;
* });
*
* ===================================== 信号5：textChanged(const QString &text) =====================================
* @signal void QLineEdit::textChanged(const QString &text)
* @brief 文本内容发生变化时触发的信号（代码/用户操作均触发）
* @details 触发场景：
* 1. 用户输入/删除文本；
* 2. 代码调用setText()/clear()修改文本；
* 3. 清除按钮点击清空文本；
* @参数说明：
* @param text – 变化后的新文本内容；
* @示例：
* connect(ui->lineEdit, &QLineEdit::textChanged, this, [=](const QString &newText){
* qDebug() << "文本已修改为：" << newText;
* });
*
* ===================================== 信号6：textEdited(const QString &text) =====================================
* @signal void QLineEdit::textEdited(const QString &text)
* @brief 文本内容发生变化时触发的信号（仅用户操作触发，代码修改不触发）
* @details 核心区别于textChanged()：代码调用setText()/clear()不会触发此信号，仅响应用户的输入/删除操作；
* @参数说明：
* @param text – 用户操作后的新文本内容；
* @示例：
* connect(ui->lineEdit, &QLineEdit::textEdited, this, [=](const QString &newText){
* qDebug() << "用户修改文本为：" << newText; // 代码修改不会触发此输出
* });
*/
}

Widget::~Widget()
{
delete ui;
}

第七章 全文总结与学习建议

恭喜你！终于看完了这篇 QLineEdit 常见属性详细解析！

如果你跟着文章一步步敲了代码，做了练习，那么现在你已经完全掌握了 QLineEdit 的核心内容：

• 你知道了 QLineEdit 是单行输入框，不能换行；
• 你会用 text 属性获取和设置文本，知道 setText() 触发 textChanged() 不触发 textEdited()；
• 你会用 frame 属性隐藏或显示边框；
• 你会用 inputMask 做简单的格式约束，知道实际开发中常用正则表达式验证器；
• 你会用 maxLength 限制最大字符数，知道是 “字符数” 不是 “字节数”；
• 你会用 echoMode 的三种模式，特别是 Password 模式做密码框，知道显示只是视觉隐藏，text() 仍能拿到原始内容；
• 你会用 placeholderText 做空状态提示，知道它不是 text 的一部分；
• 你会用 dragEnabled 允许或禁止拖拽；
• 你彻底搞懂了 readOnly 和 setEnabled(false) 的区别！—— 只读可以选中复制，禁用完全不能交互；
• 你会用 cursorPosition（虽然不常用）、alignment 做文本对齐、clearButtonEnabled 显示一键清空按钮；
• 你会绑定 QLineEdit 的六个核心信号，特别是 editingFinished()、returnPressed()、textChanged()、textEdited()，彻底搞懂了 textChanged() 和 textEdited() 的区别！

毫不夸张地说，掌握了这些内容，你就掌握了 QLineEdit 开发的 95% 以上的需求！接下来，你可以用这些内容，实现各种你想要的输入框效果。

7.1 核心要点回顾

在结束之前，我们最后再回顾一下这篇文章的核心要点，特别是那些最容易踩坑的地方：

7.2 最后的话

编程学习没有捷径，唯手熟尔。QLineEdit 的属性和信号虽然看起来很多，但只要你多敲代码、多做练习、多踩坑、多排查，很快就能熟练掌握。

这篇文章虽然很长，但我相信，如果你认真看完了，跟着敲了代码，你一定会对 QLineEdit 有一个极其深刻的理解，再也不会为输入框的实现发愁。

感谢你阅读这篇文章，希望它能帮到你。我们下一篇 Qt 教程再见