python pyside2 line edit单行文本输入控件（QLineEdit）-马育民老师

# 介绍

[![](https://www.malaoshi.top/upload/0/0/1GW1r5D1PHOC.png)](https://www.malaoshi.top/upload/0/0/1GW1r5D1PHOC.png)

QLineEdit 是 PySide2 中最基础且常用的 **单行文本输入** 控件，主打 “轻量快捷”，适用于 **账号**、**密码**、**搜索关键词** 等短文本输入场景。本文将从基础用法、进阶功能、实战案例三个维度，系统讲解其使用方法。

# 基础用法

创建 QLineEdit 并设置提示文本、初始内容，是最基础的用法：

```
from PySide2.QtWidgets import QApplication, QLineEdit, QWidget, QVBoxLayout
import sys

app = QApplication(sys.argv)
window = QWidget()
layout = QVBoxLayout(window)

# 1. 创建默认 QLineEdit
edit1 = QLineEdit()
edit1.setPlaceholderText("请输入基础文本（如用户名）")  # 输入提示（未输入时显示）
edit1.setText("默认用户名")  # 设置初始文本

# 2. 获取文本内容（通常在按钮点击、回车触发时调用）
def get_text():
    print("输入的内容：", edit1.text())  # 输出：输入的内容：默认用户名（或用户输入的文本）

# 绑定回车触发事件（按下 Enter 时执行 get_text）
edit1.returnPressed.connect(get_text)

layout.addWidget(edit1)
window.show()
sys.exit(app.exec_())
```

# 核心文本操作方法

### setText(str)
设置控件的文本内容

```
edit.setText("hello")
```

### text()

获取当前输入的文本内容
```
content = edit.text()
```

### clear()

清空文本内容
```
edit.clear()
```

### setPlaceholderText(str)

设置输入提示文本（未输入时显示，输入后消失）
```
edit.setPlaceholderText("请输入")
```

### selectAll()
全选当前文本
```
edit.selectAll()
```

# 输入限制：控制文本长度与格式

### 限制输入长度

通过 `setMaxLength(int)` 限制文本最大字符数，适合手机号、验证码等固定长度场景：

```
# 限制输入长度为 11（如手机号）
phone_edit = QLineEdit()
phone_edit.setPlaceholderText("请输入手机号（11位）")
phone_edit.setMaxLength(11)  # 最多输入 11 个字符，超出部分无法输入
layout.addWidget(phone_edit)
```

### 限制输入格式（输入掩码）

通过 `setInputMask(str)` 强制文本按固定格式输入（如日期、身份证、IP 地址），格式字符对应规则如下：

|格式字符|含义|示例场景|
|---|---|---|---|
|0|必须输入数字（0-9）|手机号、日期中的年份|
|9|可选输入数字（0-9）|电话号码中的分机号|
|A|必须输入字母（A-Z,a-z）|身份证中的字母（如 X）|
|a|可选输入字母（A-Z,a-z）|可选的字母输入|
|`-`/`_`/`.`|固定显示的分隔符|日期中的 `-`、IP 中的 `.`|

示例：实现日期格式输入（YYYY-MM-DD）

```
date_edit = QLineEdit()
# 输入掩码：4个必须数字（年）-2个必须数字（月）-2个必须数字（日）
date_edit.setInputMask("0000-00-00")
date_edit.setPlaceholderText("请输入日期（YYYY-MM-DD）")
layout.addWidget(date_edit)
# 输入时会自动显示分隔符“-”，且仅允许在对应位置输入数字
```

# 进阶功能：样式、模式与交互

### 密码输入模式（EchoMode）

QLineEdit 独有的 EchoMode 属性，支持四种输入显示模式，其中 密码隐藏模式 是最常用的进阶功能：

|模式常量|功能描述|适用场景|
|---|---|---|---|
|QLineEdit.Normal|正常显示输入内容（默认）|普通文本输入（如用户名）|
|QLineEdit.Password|输入内容隐藏为 `*`|密码输入|
|QLineEdit.PasswordEchoOnEdit|输入时显示明文，失去焦点后隐藏为 `*`|敏感信息输入（兼顾便捷与安全）|
|QLineEdit.NoEcho|完全不显示输入内容（连 `*` 都没有）|极高安全要求的场景（如支付密码）|

示例：密码输入与切换显示

```
from PySide2.QtWidgets import QCheckBox

# 密码输入框
pwd_edit = QLineEdit()
pwd_edit.setPlaceholderText("请输入密码")
pwd_edit.setEchoMode(QLineEdit.Password)  # 默认隐藏为“*”

# 密码显示切换复选框
show_pwd_box = QCheckBox("显示密码")
def toggle_pwd_visible(state):
    # 复选框勾选时，切换为输入时显示明文；未勾选时，隐藏为“*”
    if state == 2:  # Qt.CheckState.Checked 对应值为 2
        pwd_edit.setEchoMode(QLineEdit.PasswordEchoOnEdit)
    else:
        pwd_edit.setEchoMode(QLineEdit.Password)

show_pwd_box.stateChanged.connect(toggle_pwd_visible)

layout.addWidget(pwd_edit)
layout.addWidget(show_pwd_box)
```

### 样式定制：美化外观

通过 setStyleSheet(str) 用 CSS 语法定制控件样式，支持修改背景色、边框、字体、选中状态等，满足界面美化需求：

```
# 定制带圆角、蓝色边框的 QLineEdit
styled_edit = QLineEdit()
styled_edit.setPlaceholderText("美化后的输入框")
styled_edit.setStyleSheet("""
    QLineEdit {
        border: 2px solid #4A90E2;  /* 边框：2px 蓝色 */
        border-radius: 8px;         /* 圆角：8px */
        padding: 6px 12px;          /* 内边距：上下 6px，左右 12px（避免文本贴边） */
        font-size: 14px;            /* 字体大小：14px */
        color: #333333;             /* 文本颜色：深灰色 */
        background-color: #F8F9FA;  /* 背景色：浅灰色 */
    }
    QLineEdit:focus {
        border-color: #2563EB;      /* 获焦时边框颜色：深蓝色（突出交互） */
        outline: none;              /* 清除默认获焦外框（避免重复边框） */
    }
    QLineEdit:disabled {
        background-color: #E9ECEF;  /* 禁用时背景色：更浅的灰色 */
        color: #ADB5BD;             /* 禁用时文本颜色：浅灰色 */
    }
""")
layout.addWidget(styled_edit)

# 禁用状态示例（按需开启）
# styled_edit.setDisabled(True)
```

# 状态控制：启用 / 禁用与只读

### 启用 / 禁用控件

通过 `setEnabled(bool)` 控制控件是否可交互，禁用后无法输入、无法获焦，适合 “条件触发输入” 场景（如勾选同意协议后才允许输入手机号）：

```
# 同意协议复选框
agree_box = QCheckBox("我已阅读并同意用户协议")
# 手机号输入框（默认禁用）
phone_edit = QLineEdit()
phone_edit.setPlaceholderText("请输入手机号")
phone_edit.setEnabled(False)

# 勾选协议后启用手机号输入
def toggle_phone_edit(state):
    phone_edit.setEnabled(state == 2)  # 勾选时启用，未勾选时禁用

agree_box.stateChanged.connect(toggle_phone_edit)

layout.addWidget(agree_box)
layout.addWidget(phone_edit)
```

### 只读模式

通过 `setReadOnly(bool)` 设置控件为只读状态，此时文本可选中、可复制，但无法修改，适合 “展示不可编辑的文本” 场景（如订单号、用户 ID）：

```
# 只读的订单号显示
order_edit = QLineEdit()
order_edit.setText("ORDER20251001001")  # 固定文本，用户无法修改
order_edit.setReadOnly(True)  # 设为只读
layout.addWidget(order_edit)
```

# 实战案例：QLineEdit 典型应用场景

1. 登录表单（账号 + 密码）

结合 QLineEdit 的密码模式、输入限制，实现一个简易登录表单：

```
from PySide2.QtWidgets import QPushButton, QHBoxLayout

app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("简易登录")
layout = QVBoxLayout(window)

# 1. 账号输入（限制长度 20）
account_edit = QLineEdit()
account_edit.setPlaceholderText("请输入账号（最长20位）")
account_edit.setMaxLength(20)
layout.addWidget(account_edit)

# 2. 密码输入（隐藏模式+显示切换）
pwd_edit = QLineEdit()
pwd_edit.setPlaceholderText("请输入密码")
pwd_edit.setEchoMode(QLineEdit.Password)

# 密码显示切换复选框（横向布局）
pwd_layout = QHBoxLayout()
show_pwd_box = QCheckBox("显示密码")
show_pwd_box.stateChanged.connect(lambda s: pwd_edit.setEchoMode(
    QLineEdit.PasswordEchoOnEdit if s == 2 else QLineEdit.Password
))
pwd_layout.addWidget(pwd_edit)
pwd_layout.addWidget(show_pwd_box)
layout.addLayout(pwd_layout)

# 3. 登录按钮（点击时验证输入）
def login():
    account = account_edit.text().strip()
    pwd = pwd_edit.text().strip()
    if not account:
        print("请输入账号")
        return
    if not pwd:
        print("请输入密码")
        return
    print(f"登录请求：账号={account}，密码={pwd}")  # 实际项目中会替换为接口请求

login_btn = QPushButton("登录")
login_btn.clicked.connect(login)
# 回车触发登录（账号或密码框按下 Enter 时）
account_edit.returnPressed.connect(login)
pwd_edit.returnPressed.connect(login)

layout.addWidget(login_btn)
window.show()
sys.exit(app.exec_())
```

### 搜索框（实时搜索 / 回车搜索）

结合 textChanged 信号实现实时搜索，或 returnPressed 实现回车搜索，适用于搜索功能：

```
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("简易搜索")
layout = QVBoxLayout(window)

# 搜索框
search_edit = QLineEdit()
search_edit.setPlaceholderText("请输入搜索关键词（实时搜索/按 Enter 搜索）")
# 搜索图标（可选，用样式模拟）
search_edit.setStyleSheet("""
    QLineEdit {
        padding-left: 30px;  /* 左侧留空间放图标 */
        background-image: url(:/icons/search.png);  /* 实际项目需导入图标资源 */
        background-repeat: no-repeat;
        background-position: left 8px center;
        background-size: 16px 16px;
    }
""")

# 1. 实时搜索（文本变化时触发，适合短关键词）
def realtime_search(text):
    print(f"实时搜索：{text}")  # 实际项目中会替换为筛选列表、接口请求等

search_edit.textChanged.connect(realtime_search)

# 2. 回车搜索（避免实时搜索频繁触发，适合长关键词）
def enter_search():
    text = search_edit.text().strip()
    print(f"回车搜索：{text}")

search_edit.returnPressed.connect(enter_search)

layout.addWidget(search_edit)
window.show()
sys.exit(app.exec_())
```

# 常见问题与解决方案

### 问题：按下 Enter 键无法触发 returnPressed 信号

原因：控件未获焦（焦点在其他控件上），或信号未正确绑定。
解决方案：

- 确保信号绑定代码正确（如 `edit.returnPressed.connect(func)`）；
- 可通过 `edit.setFocus()` 让控件默认获焦（如登录表单中，默认聚焦账号输入框）：

```
# 登录表单中，窗口显示时默认聚焦账号输入框
window.showEvent = lambda e: account_edit.setFocus()
```

### 问题：输入掩码无法满足复杂格式需求（如邮箱）

原因：`setInputMask` 仅支持固定格式，邮箱、URL 等动态格式无法覆盖。
解决方案：使用 `QRegExpValidator` 或 `QIntValidator` 进行正则验证：

```
from PySide2.QtGui import QRegExpValidator, QRegExp

# 邮箱输入验证（正则表达式）
email_edit = QLineEdit()
email_edit.setPlaceholderText("请输入邮箱")
# 邮箱正则（简化版）：xxx@xxx.xxx
email_reg = QRegExp(r"^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$")
email_validator = QRegExpValidator(email_reg)
email_edit.setValidator(email_validator)  # 仅允许输入符合邮箱格式的文本
layout.addWidget(email_edit)
```

### 问题：控件样式在不同系统中显示不一致
原因：`QLineEdit` 默认样式依赖系统主题，Windows、macOS 显示效果不同。
解决方案：通过完整的 CSS 样式覆盖默认样式，确保跨系统一致性（参考 “进阶功能 2：样式定制” 中的示例，明确设置边框、背景、字体等属性）。

原文出处：http://malaoshi.top/show_1GW1r5RZTEul.html