QLineEdit 是 PyQt 和 PySide 中最常用的单行文本输入控件,它允许用户输入和编辑单行纯文本。

基本用法
你需要导入必要的模块并创建一个 QLineEdit 实例。
import sys from PyQt5.QtWidgets import QApplication, QMainWindow, QLineEdit, QVBoxLayout, QWidget # --- 最简单的例子 --- app = QApplication(sys.argv) # 创建 QLineEdit 控件 line_edit = QLineEdit() # 显示控件 line_edit.show() sys.exit(app.exec_())
代码解释:
QApplication(sys.argv): 创建一个应用程序对象,这是使用 PyQt 的第一步。QLineEdit(): 实例化一个行编辑器,此时它是一个空白的输入框。line_edit.show(): 在屏幕上显示这个输入框。app.exec_(): 启动应用程序的事件循环,程序会一直运行,直到窗口被关闭。
在窗口中布局
上面的例子只是一个孤立的输入框,我们会把它放在一个主窗口里,并使用布局管理器来排列它。
import sys
from PyQt5.QtWidgets import (QApplication, QMainWindow, QWidget,
QLineEdit, QVBoxLayout, QLabel)
class MainWindow(QMainWindow):
def __init__(self):
super().__init__()
self.setWindowTitle("QLineEdit 示例")
self.setGeometry(300, 300, 350, 150) # x, y, width, height
# 创建一个中央控件和布局
central_widget = QWidget()
self.setCentralWidget(central_widget)
layout = QVBoxLayout(central_widget)
# 创建一个标签用于显示提示
self.label = QLabel("请在此输入文本:")
# 创建 QLineEdit
self.line_edit = QLineEdit()
# 将控件添加到布局中
layout.addWidget(self.label)
layout.addWidget(self.line_edit)
# --- 主程序 ---
if __name__ == '__main__':
app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())
代码解释:
QMainWindow: 创建一个主窗口。QWidget和QVBoxLayout: 我们使用一个QWidget作为中央容器,并使用QVBoxLayout(垂直布局) 来自动管理内部控件的位置和大小,这比手动设置x, y坐标更灵活。layout.addWidget(...): 将QLabel和QLineEdit添加到垂直布局中,它们会从上到下依次排列。
获取和设置文本
这是 QLineEdit 最核心的功能。
设置文本
使用 setText() 方法。
self.line_edit.setText("这是预设的文本")
获取文本
使用 text() 方法,这个方法返回一个字符串。
input_text = self.line_edit.text()
print("输入框的内容是:", input_text)
完整示例:获取输入并在标签上显示
import sys
from PyQt5.QtWidgets import (QApplication, QMainWindow, QWidget,
QLineEdit, QVBoxLayout, QLabel, QPushButton)
class MainWindow(QMainWindow):
def __init__(self):
super().__init__()
self.setWindowTitle("获取输入示例")
self.setGeometry(300, 300, 400, 200)
central_widget = QWidget()
self.setCentralWidget(central_widget)
layout = QVBoxLayout(central_widget)
self.input_label = QLabel("输入内容:")
self.line_edit = QLineEdit()
# 按钮用于触发获取文本的操作
self.get_button = QPushButton("获取文本")
self.get_button.clicked.connect(self.get_text_from_line_edit)
self.result_label = QLabel("结果将显示在这里...")
layout.addWidget(self.input_label)
layout.addWidget(self.line_edit)
layout.addWidget(self.get_button)
layout.addWidget(self.result_label)
def get_text_from_line_edit(self):
# 获取 QLineEdit 中的文本
text = self.line_edit.text()
# 将获取到的文本设置到结果标签上
self.result_label.setText(f"你输入了: {text}")
if __name__ == '__main__':
app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())
常用信号
QLineEdit 是一个交互式控件,当用户进行操作时会发出信号,你可以将这些信号连接到自定义的槽函数上。
textChanged: 当文本内容任何改变时(包括添加、删除、粘贴等)都会发出,参数是改变后的新文本。editingFinished: 当用户完成编辑时发出(按下回车键或点击输入框外部)。没有参数。returnPressed: 当用户在输入框中按下回车键时发出。没有参数。
示例:连接 textChanged 信号
# ... (在 MainWindow 的 __init__ 中)
self.line_edit.textChanged.connect(self.on_text_changed)
# ... (在 MainWindow 类中定义槽函数)
def on_text_changed(self, new_text):
"""当文本改变时,更新结果标签"""
self.result_label.setText(f"当前内容: {new_text}")
高级功能与属性
QLineEdit 提供了许多属性来定制其行为和外观。
1 只读模式
将输入框设置为只读,用户无法修改内容,但可以复制。
self.line_edit.setReadOnly(True)
2 占位符文本
当输入框为空时显示的灰色提示文本,当用户开始输入时会自动消失。
self.line_edit.setPlaceholderText("请输入您的用户名...")
3 输入掩码
用于限制用户输入的格式,如电话号码、日期等。 代表一个数字, 代表一个字母或数字。
# 只能输入 5 位数字
self.line_edit.setInputMask("#####")
# 输入一个日期,"2025-12-31"
# 0 代表一个数字,D 代表一个字母
date_edit = QLineEdit()
date_edit.setInputMask("0000-00-00;_") # 下划线是占位符
4 密码模式
将输入的字符显示为掩码字符(通常是圆点或星号)。
password_edit = QLineEdit() password_edit.setEchoMode(QLineEdit.Password) # 设置为密码模式
5 对齐方式
设置文本在输入框内的对齐方式。
from PyQt5.QtCore import Qt self.line_edit.setAlignment(Qt.AlignCenter) # 居中对齐 self.line_edit.setAlignment(Qt.AlignRight) # 右对齐
6 验证输入
你可以使用 QIntValidator (整数), QDoubleValidator (浮点数), QRegExpValidator (正则表达式) 来验证用户输入。
示例:只允许输入 0 到 100 之间的整数
from PyQt5.QtGui import QIntValidator validator = QIntValidator(0, 100) # 范围是 0 到 100 self.line_edit.setValidator(validator) # 如果用户输入了无效内容,QLineEdit 会拒绝或恢复
完整综合示例
下面是一个结合了多种功能的完整示例。
import sys
from PyQt5.QtWidgets import (QApplication, QMainWindow, QWidget,
QLineEdit, QVBoxLayout, QLabel, QPushButton, QHBoxLayout)
from PyQt5.QtCore import Qt
from PyQt5.QtGui import QIntValidator
class AdvancedLineEditDemo(QMainWindow):
def __init__(self):
super().__init__()
self.setWindowTitle("QLineEdit 高级功能演示")
self.setGeometry(300, 300, 500, 400)
central_widget = QWidget()
self.setCentralWidget(central_widget)
main_layout = QVBoxLayout(central_widget)
# --- 1. 基本输入 ---
basic_layout = QHBoxLayout()
self.basic_label = QLabel("基本输入:")
self.basic_input = QLineEdit()
basic_layout.addWidget(self.basic_label)
basic_layout.addWidget(self.basic_input)
main_layout.addLayout(basic_layout)
# --- 2. 带占位符的只读输入 ---
readonly_layout = QHBoxLayout()
self.readonly_label = QLabel("只读 (带占位符):")
self.readonly_input = QLineEdit()
self.readonly_input.setReadOnly(True)
self.readonly_input.setPlaceholderText("这是只读提示")
self.readonly_input.setText("预设内容")
readonly_layout.addWidget(self.readonly_label)
readonly_layout.addWidget(self.readonly_input)
main_layout.addLayout(readonly_layout)
# --- 3. 密码输入 ---
password_layout = QHBoxLayout()
self.password_label = QLabel("密码输入:")
self.password_input = QLineEdit()
self.password_input.setEchoMode(QLineEdit.Password)
self.password_input.setPlaceholderText("请输入密码")
password_layout.addWidget(self.password_label)
password_layout.addWidget(self.password_input)
main_layout.addLayout(password_layout)
# --- 4. 数字验证输入 (0-100) ---
number_layout = QHBoxLayout()
self.number_label = QLabel("数字输入 (0-100):")
self.number_input = QLineEdit()
validator = QIntValidator(0, 100)
self.number_input.setValidator(validator)
number_layout.addWidget(self.number_label)
number_layout.addWidget(self.number_input)
main_layout.addLayout(number_layout)
# --- 5. 显示所有输入的按钮和结果 ---
self.show_all_button = QPushButton("显示所有输入")
self.show_all_button.clicked.connect(self.show_all_inputs)
self.result_display = QLabel("点击按钮后,所有输入将显示在这里")
self.result_display.setAlignment(Qt.AlignTop | Qt.AlignLeft)
self.result_display.setWordWrap(True) # 允许文本换行
main_layout.addWidget(self.show_all_button)
main_layout.addWidget(self.result_display)
# 连接 textChanged 信号进行实时演示
self.basic_input.textChanged.connect(lambda text: self.update_realtime_label("基本输入", text))
self.password_input.textChanged.connect(lambda text: self.update_realtime_label("密码输入", '*'*len(text)))
self.number_input.textChanged.connect(lambda text: self.update_realtime_label("数字输入", text))
def update_realtime_label(self, field_name, text):
"""实时更新一个标签来显示输入"""
# 这里只是演示,你可以创建专门的标签来显示
print(f"[实时] {field_name}: {text}")
def show_all_inputs(self):
"""获取所有 QLineEdit 的内容并显示"""
basic_text = self.basic_input.text()
password_text = self.password_input.text() # 获取的是真实密码,不是掩码
number_text = self.number_input.text()
result_text = f"""
--- 所有输入内容 ---
基本输入: {basic_text}
密码输入: {'*' * len(password_text)} (出于安全考虑,不显示真实密码)
数字输入: {number_text}
"""
self.result_display.setText(result_text)
if __name__ == '__main__':
app = QApplication(sys.argv)
window = AdvancedLineEditDemo()
window.show()
sys.exit(app.exec_())
这个例子涵盖了:
- 基本输入
- 只读和占位符
- 密码模式
- 输入验证
- 信号连接 (
textChanged) - 按钮点击事件 (
clicked) - 结果动态显示
希望这个详细的指南能帮助你全面掌握 QLineEdit 的使用!
