QLineEdit类详细介绍

QLineEdit 是 PyQt5 中用于单行文本输入的控件，支持文本编辑、格式验证、密码掩码、自动补全等功能，是构建表单和交互界面的核心组件。以下是详细介绍及常用方法：

一、核心功能

• ​文本输入：输入单行文本（如用户名、密码、搜索框）。
• ​格式验证：通过验证器限制输入类型（数字、邮箱、正则表达式等）。
• ​密码掩码：隐藏敏感输入内容（显示为圆点或星号）。
• ​自动补全：根据历史记录或预设列表提供输入建议。
• ​交互信号：实时响应文本变化、回车键事件等。

 

二、常用方法

​1. 文本操作

方法	说明	示例
setText(text: str)	设置输入框内容	line_edit.setText("默认文本")
text() -> str	获取当前文本	content = line_edit.text()
clear()	清空输入内容	line_edit.clear()
setPlaceholderText(text: str)	设置提示文本（灰色占位符）	line_edit.setPlaceholderText("请输入用户名")

​2. 格式验证

方法	说明	示例
setValidator(validator: QValidator)	设置验证器（数字、正则表达式等）	line_edit.setValidator(QIntValidator(0, 100))
setInputMask(mask: str)	设置输入掩码（规范输入格式）	line_edit.setInputMask("9999-99-99")（日期格式）

​3. 密码模式

方法	说明	示例
setEchoMode(mode: QLineEdit.EchoMode)	设置回显模式	line_edit.setEchoMode(QLineEdit.Password)
​枚举值	QLineEdit.Normal（明文） QLineEdit.Password（密码掩码） QLineEdit.NoEcho（无回显，用于密码长度隐藏）

​4. 外观与交互

方法	说明	示例
setMaxLength(length: int)	限制最大输入长度	line_edit.setMaxLength(20)
setReadOnly(enable: bool)	设为只读模式（不可编辑）	line_edit.setReadOnly(True)
addAction(icon: QIcon, position: QLineEdit.ActionPosition)	添加图标按钮（如搜索、清除按钮）	line_edit.addAction(QIcon("search.png"), QLineEdit.TrailingPosition)
setStyleSheet(css: str)	通过 CSS 设置样式	line_edit.setStyleSheet("border: 1px solid #ccc;")

​5. 自动补全

方法	说明	示例
setCompleter(completer: QCompleter)	设置自动补全建议	completer = QCompleter(["apple", "banana"]) line_edit.setCompleter(completer)

---

​三、信号

信号	说明	使用场景
textChanged(text: str)	文本内容变化时触发	实时搜索、输入验证
returnPressed()	按下回车键时触发	提交表单
editingFinished()	焦点离开输入框时触发	触发最终验证

---

​四、代码示例

1. 基础文本输入

python

from PyQt5.QtWidgets import QLineEdit, QWidget, QVBoxLayout, QApplication

class Form(QWidget):
    def __init__(self):
        super().__init__()
        layout = QVBoxLayout(self)
        
        self.username = QLineEdit()
        self.username.setPlaceholderText("用户名")
        layout.addWidget(self.username)
        
        self.password = QLineEdit()
        self.password.setPlaceholderText("密码")
        self.password.setEchoMode(QLineEdit.Password)
        layout.addWidget(self.password)
        
        self.setWindowTitle("登录表单")
        self.resize(300, 150)

app = QApplication([])
window = Form()
window.show()
app.exec_()

​2. 输入验证（邮箱格式）​

python

from PyQt5.QtGui import QRegExpValidator
from PyQt5.QtCore import QRegExp

class ValidatedForm(QWidget):
    def __init__(self):
        super().__init__()
        layout = QVBoxLayout(self)
        
        self.email = QLineEdit()
        self.email.setPlaceholderText("邮箱")
        # 设置正则表达式验证器（简单邮箱格式）
        regex = QRegExp(r"[^@]+@[^@]+\.[^@]+")
        validator = QRegExpValidator(regex)
        self.email.setValidator(validator)
        self.email.textChanged.connect(self.validate_email)
        layout.addWidget(self.email)
        
    def validate_email(self, text):
        if not text.endswith("@example.com"):
            self.email.setStyleSheet("border: 1px solid red;")
        else:
            self.email.setStyleSheet("border: 1px solid green;")

​3. 添加清除按钮

python

class ClearableLineEdit(QLineEdit):
    def __init__(self):
        super().__init__()
        self.addAction(QIcon("clear.png"), QLineEdit.TrailingPosition).triggered.connect(self.clear)

​4. 自动补全

python

from PyQt5.QtWidgets import QCompleter

class AutoCompleteDemo(QWidget):
    def __init__(self):
        super().__init__()
        layout = QVBoxLayout(self)
        
        self.search_box = QLineEdit()
        completer = QCompleter(["Python", "Java", "C++", "JavaScript"])
        self.search_box.setCompleter(completer)
        layout.addWidget(self.search_box)

---

​五、注意事项

1. ​验证器优先级：
   若同时设置 setValidator 和 setInputMask，输入掩码优先生效。

2. ​密码安全：
   NoEcho 模式适用于需要完全隐藏输入的场景（如密码长度保护）。

3. ​性能优化：
   避免在 textChanged 信号中执行耗时操作（如频繁数据库查询），建议使用防抖（Debounce）技术。

4. ​输入掩码语法：
   掩码字符需符合规范（如 A 代表字母，9 代表数字），需参考官方文档。

---

​六、与其他控件对比

​QLineEdit	​QTextEdit
仅支持单行文本输入	支持多行富文本编辑
轻量级，适合表单字段	功能复杂，适合长文本编辑

---

通过 QLineEdit，可以高效构建用户输入界面，结合验证和自动补全功能，显著提升交互体验！