目录
引言
一、为什么 PyQt6 是 Python GUI 开发的 “王牌之选”？
二、基础入门：3 分钟搭建第一个 PyQt6 应用
2.1 环境搭建：安装 PyQt6
2.2 验证安装
2.3 核心概念：PyQt6 程序的基本结构
三、核心组件详解：常用控件的使用方法
3.1 窗口（QWidget/QMainWindow）
示例：基础窗口配置
QMainWindow：带菜单栏的主窗口
3.2 标签（QLabel）：显示文本或图片
示例 1：显示文本和富文本
示例 2：显示图片
3.3 按钮（QPushButton）：触发交互事件
基础示例：点击按钮弹出提示
进阶：按钮状态控制与图标按钮
3.4 输入框（QLineEdit）：获取单行文本输入
示例：登录窗口的用户名和密码输入
3.5 文本框（QTextEdit）：获取多行文本输入
示例：文本编辑与内容获取
3.6 复选框（QCheckBox）：多选功能
示例：兴趣爱好选择
3.7 单选按钮（QRadioButton）：单选功能
示例：性别选择
3.8 下拉菜单（QComboBox）：选择预设选项
示例：城市选择
3.9 滑块（QSlider）：调节数值
示例：调节字体大小
3.10 列表框（QListWidget）：展示列表数据
示例：文件列表展示与选择
四、布局管理：让组件整齐排列
4.1 垂直布局（QVBoxLayout）：组件垂直排列
示例：垂直布局的表单
4.2 水平布局（QHBoxLayout）：组件水平排列
示例：水平布局的按钮组
4.3 网格布局（QGridLayout）：表格形式排列
示例：网格布局的登录窗口
4.4 布局嵌套：实现复杂界面
示例：嵌套布局的综合示例
五、事件处理：PyQt6 的核心 —— 信号与槽机制
5.1 信号与槽的基本使用
方式 1：直接绑定槽函数
方式 2：带参数的槽函数
方式 3：解除信号与槽的绑定
5.2 常用组件的核心信号
5.3 自定义信号与槽
示例：自定义信号
六、进阶功能：打造专业级桌面应用
6.1 菜单与工具栏：应用功能导航
示例：带菜单和工具栏的主窗口
6.2 对话框：交互提示与输入
示例：常用对话框
6.3 多线程：避免界面卡顿
示例：多线程处理耗时任务
6.4 界面美化：QSS 样式表
示例：QSS 美化界面
6.5 自定义组件：扩展功能
示例：自定义计数器组件
七、实战案例：开发一个完整的计算器应用
7.1 功能需求
7.2 代码实现
7.3 功能演示
八、避坑指南：PyQt6 新手常犯的 6 个错误
九、总结：PyQt6 学习路径与进阶建议
核心知识点回顾
进阶学习建议
class 卑微码农:
def __init__(self):
self.技能 = ['能读懂十年前祖传代码', '擅长用Ctrl+C/V搭建世界', '信奉"能跑就别动"的玄学']
self.发量 = 100 # 初始发量
self.咖啡因耐受度 = '极限'
def 修Bug(self, bug):
try:
# 试图用玄学解决问题
if bug.严重程度 == '离谱':
print("这一定是环境问题！")
else:
print("让我看看是谁又没写注释…哦，是我自己。")
except Exception as e:
# 如果try块都救不了，那就…
print("重启一下试试？")
self.发量 -= 1 # 每解决一个bug，头发-1
# 实例化一个我
我 = 卑微码农()
引言
在 Python GUI 开发领域，如果你想开发出界面美观、功能强大且跨平台的桌面应用，PyQt6 绝对是首选工具。它基于 Qt 框架，融合了 Python 的简洁易用和 Qt 的丰富功能，既能快速搭建简单工具，也能开发复杂的商业软件（如视频编辑器、数据分析平台）。
相比 Tkinter 的基础简陋，PyQt6 提供了更现代化的界面组件和更灵活的定制能力；相比 wxPython 的生态封闭，PyQt6 拥有更庞大的社区支持和更完善的文档。无论是新手入门 GUI 开发，还是开发者升级桌面应用质感，PyQt6 都能满足需求。
本文从实际开发场景出发，通过 “基础入门→组件详解→布局管理→事件处理→进阶实战” 的递进结构，搭配可直接运行的代码示例和详细注释，帮你从 0 到 1 掌握 PyQt6，轻松开发出媲美专业软件的桌面应用。
一、为什么 PyQt6 是 Python GUI 开发的 “王牌之选”？
在众多 Python GUI 库中，PyQt6 的优势尤为突出，尤其适合追求界面质感和功能完整性的开发场景：
- 界面美观且现代化：内置丰富的主题样式，支持自定义控件外观，轻松打造媲美原生系统的界面；
- 功能全面且强大：覆盖窗口、组件、布局、事件、绘图、网络、数据库等所有桌面应用所需功能；
- 跨平台兼容性好：一套代码可运行在 Windows、macOS、Linux 上，无需额外修改；
- 生态完善且活跃：海量第三方组件和教程，遇到问题能快速找到解决方案；
- 支持可视化开发：可搭配 Qt Designer 拖拽设计界面，大幅提升开发效率；
- 绑定信号与槽机制：灵活处理组件交互，逻辑清晰且易于维护。
无论是开发个人工具（如批量处理脚本界面）、企业应用（如客户管理系统），还是开源项目（如数据分析工具），PyQt6 都能胜任。
二、基础入门：3 分钟搭建第一个 PyQt6 应用
2.1 环境搭建：安装 PyQt6
PyQt6 是第三方库，需要手动安装，推荐使用 Python 3.8 及以上版本（兼容性更好）：
# 基础安装（包含核心组件）
pip install pyqt6
# 完整安装（包含Qt Designer等工具，推荐）
pip install pyqt6-tools
2.2 验证安装
安装完成后，运行以下代码，若弹出窗口则说明安装成功：
from PyQt6.QtWidgets import QApplication, QWidget, QLabel
import sys
# 1. 创建应用实例（每个PyQt程序必须有且只有一个QApplication）
app = QApplication(sys.argv)
# 2. 创建主窗口
window = QWidget()
window.setWindowTitle("我的第一个PyQt6应用") # 设置窗口标题
window.resize(400, 300) # 设置窗口大小（宽x高）
# 3. 添加组件（标签）
label = QLabel("Hello PyQt6！", parent=window)
label.move(150, 130) # 设置组件位置（x,y）
# 4. 显示窗口
window.show()
# 5. 启动应用事件循环
sys.exit(app.exec())
2.3 核心概念：PyQt6 程序的基本结构
一个标准的 PyQt6 程序包含 5 个核心步骤，所有复杂应用都基于此扩展：
三、核心组件详解：常用控件的使用方法
PyQt6 提供了上百种组件，以下是最常用的 10 种核心组件，每种都包含 “功能说明 + 代码示例 + 参数解析”，可直接套用。
3.1 窗口（QWidget/QMainWindow）
窗口是应用的容器，PyQt6 中常用QWidget（基础窗口）和QMainWindow（带菜单栏 / 工具栏的主窗口）。
示例：基础窗口配置
from PyQt6.QtWidgets import QApplication, QWidget
from PyQt6.QtGui import QIcon
import sys
app = QApplication(sys.argv)
# 创建基础窗口
window = QWidget()
window.setWindowTitle("PyQt6窗口示例") # 窗口标题
window.resize(500, 400) # 窗口大小
window.move(100, 100) # 窗口初始位置（屏幕左上角为原点）
window.setFixedSize(500, 400) # 禁止调整窗口大小
# 设置窗口图标（需.ico格式文件）
# window.setWindowIcon(QIcon("icon.ico"))
# 显示窗口
window.show()
sys.exit(app.exec())
QMainWindow：带菜单栏的主窗口
from PyQt6.QtWidgets import QApplication, QMainWindow
import sys
class MainWindow(QMainWindow):
def __init__(self):
super().__init__()
self.setWindowTitle("QMainWindow示例")
self.resize(500, 400)
# 设置中心组件（QMainWindow必须通过中心组件添加内容）
self.central_widget = QWidget()
self.setCentralWidget(self.central_widget)
if __name__ == "__main__":
app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())
3.2 标签（QLabel）：显示文本或图片
QLabel 用于显示静态文本、图片或富文本，是最基础的展示组件。
示例 1：显示文本和富文本
from PyQt6.QtWidgets import QApplication, QWidget, QLabel, QVBoxLayout
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QLabel示例")
window.resize(300, 200)
# 创建布局（后续详解）
layout = QVBoxLayout(window)
# 1. 普通文本标签
label1 = QLabel("普通文本标签")
label1.setStyleSheet("font-size: 14px; color: #333;") # 设置样式
layout.addWidget(label1)
# 2. 富文本标签（支持HTML格式）
label2 = QLabel('<font color="red" size="5">富文本标签</font>')
layout.addWidget(label2)
# 3. 居中对齐的标签
label3 = QLabel("居中对齐的标签")
label3.setAlignment(Qt.AlignmentFlag.AlignCenter) # 居中对齐
label3.setStyleSheet("background-color: #f0f0f0; padding: 10px;")
layout.addWidget(label3)
window.show()
sys.exit(app.exec())
示例 2：显示图片
from PyQt6.QtWidgets import QApplication, QWidget, QLabel, QVBoxLayout
from PyQt6.QtGui import QPixmap
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("显示图片")
window.resize(300, 300)
layout = QVBoxLayout(window)
# 创建图片标签
label = QLabel()
# 加载图片（支持jpg、png等格式）
pixmap = QPixmap("test.jpg") # 替换为你的图片路径
# 缩放图片以适应标签大小
pixmap = pixmap.scaled(200, 200)
label.setPixmap(pixmap)
label.setAlignment(Qt.AlignmentFlag.AlignCenter) # 图片居中
layout.addWidget(label)
window.show()
sys.exit(app.exec())
3.3 按钮（QPushButton）：触发交互事件
QPushButton 是最常用的交互组件，用户点击后会触发预设的功能逻辑。
基础示例：点击按钮弹出提示
from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QVBoxLayout, QMessageBox
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QPushButton示例")
window.resize(300, 200)
layout = QVBoxLayout(window)
# 定义按钮点击事件的处理函数
def on_button_click():
QMessageBox.information(window, "提示", "你点击了按钮！") # 弹出信息框
# 创建按钮
button = QPushButton("点击我")
button.setStyleSheet("""
QPushButton {
font-size: 14px;
padding: 8px 16px;
background-color: #4CAF50;
color: white;
border: none;
border-radius: 4px;
}
QPushButton:hover {
background-color: #45a049;
}
""") # 自定义按钮样式（hover为鼠标悬浮效果）
button.clicked.connect(on_button_click) # 绑定点击事件
layout.addWidget(button, alignment=Qt.AlignmentFlag.AlignCenter)
window.show()
sys.exit(app.exec())
进阶：按钮状态控制与图标按钮
from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QHBoxLayout
from PyQt6.QtGui import QIcon
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("按钮进阶示例")
window.resize(300, 100)
layout = QHBoxLayout(window)
layout.setSpacing(20) # 组件间距
# 1. 带图标的按钮
icon_button = QPushButton()
icon_button.setIcon(QIcon("icon.png")) # 设置图标
icon_button.setIconSize(QtCore.QSize(32, 32)) # 图标大小
layout.addWidget(icon_button)
# 2. 禁用状态的按钮
disabled_button = QPushButton("禁用按钮")
disabled_button.setDisabled(True) # 禁用按钮
layout.addWidget(disabled_button)
# 3. 切换按钮状态
toggle_button = QPushButton("切换状态")
toggle_button.setCheckable(True) # 可勾选状态
def on_toggle(state):
print(f"按钮状态：{'勾选' if state else '未勾选'}")
toggle_button.toggled.connect(on_toggle) # 绑定状态切换事件
layout.addWidget(toggle_button)
window.show()
sys.exit(app.exec())
3.4 输入框（QLineEdit）：获取单行文本输入
QLineEdit 用于接收用户的单行文本输入（如用户名、密码、搜索关键词），支持输入验证和格式限制。
示例：登录窗口的用户名和密码输入
from PyQt6.QtWidgets import QApplication, QWidget, QLineEdit, QLabel, QVBoxLayout, QPushButton, QMessageBox
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("登录窗口")
window.resize(300, 250)
layout = QVBoxLayout(window)
layout.setSpacing(15)
layout.setContentsMargins(30, 30, 30, 30) # 内边距
# 用户名标签和输入框
user_label = QLabel("用户名：")
user_label.setStyleSheet("font-size: 14px;")
layout.addWidget(user_label)
user_edit = QLineEdit()
user_edit.setPlaceholderText("请输入用户名") # 提示文本
user_edit.setStyleSheet("font-size: 14px; padding: 8px;")
layout.addWidget(user_edit)
# 密码标签和输入框
pwd_label = QLabel("密码：")
pwd_label.setStyleSheet("font-size: 14px;")
layout.addWidget(pwd_label)
pwd_edit = QLineEdit()
pwd_edit.setPlaceholderText("请输入密码")
pwd_edit.setEchoMode(QLineEdit.EchoMode.Password) # 密码隐藏模式
pwd_edit.setStyleSheet("font-size: 14px; padding: 8px;")
layout.addWidget(pwd_edit)
# 登录按钮
def login():
username = user_edit.text().strip()
password = pwd_edit.text().strip()
if username == "admin" and password == "123456":
QMessageBox.information(window, "成功", "登录成功！")
else:
QMessageBox.warning(window, "错误", "用户名或密码错误！")
login_btn = QPushButton("登录")
login_btn.setStyleSheet("""
QPushButton {
font-size: 14px;
padding: 10px;
background-color: #2196F3;
color: white;
border: none;
border-radius: 4px;
}
""")
login_btn.clicked.connect(login)
layout.addWidget(login_btn)
window.show()
sys.exit(app.exec())
3.5 文本框（QTextEdit）：获取多行文本输入
QTextEdit 支持多行文本输入和编辑，可用于显示日志、编辑文档等场景，支持富文本格式。
示例：文本编辑与内容获取
from PyQt6.QtWidgets import QApplication, QWidget, QTextEdit, QPushButton, QVBoxLayout, QMessageBox
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QTextEdit示例")
window.resize(400, 300)
layout = QVBoxLayout(window)
# 创建文本框
text_edit = QTextEdit()
text_edit.setPlaceholderText("请输入多行文本…")
text_edit.setStyleSheet("font-size: 14px; padding: 10px;")
# 插入默认文本（支持富文本）
text_edit.insertHtml("<font color='blue'>这是默认的富文本内容</font>")
layout.addWidget(text_edit)
# 按钮：获取文本内容
def get_text():
# 获取纯文本
plain_text = text_edit.toPlainText()
# 获取富文本
html_text = text_edit.toHtml()
QMessageBox.information(window, "文本内容", f"纯文本：\\n{plain_text}\\n\\n富文本：\\n{html_text[:100]}…")
get_btn = QPushButton("获取文本")
get_btn.clicked.connect(get_text)
layout.addWidget(get_btn)
window.show()
sys.exit(app.exec())
3.6 复选框（QCheckBox）：多选功能
QCheckBox 用于实现多选功能，用户可勾选多个选项，常用于设置偏好、选择兴趣等场景。
示例：兴趣爱好选择
from PyQt6.QtWidgets import QApplication, QWidget, QCheckBox, QPushButton, QVBoxLayout, QLabel
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QCheckBox示例")
window.resize(300, 200)
layout = QVBoxLayout(window)
# 定义变量存储选择结果
hobbies = []
# 复选框：编程
cb1 = QCheckBox("编程")
cb1.setStyleSheet("font-size: 14px;")
layout.addWidget(cb1)
# 复选框：阅读
cb2 = QCheckBox("阅读")
cb2.setStyleSheet("font-size: 14px;")
layout.addWidget(cb2)
# 复选框：运动
cb3 = QCheckBox("运动")
cb3.setStyleSheet("font-size: 14px;")
layout.addWidget(cb3)
# 显示选择结果
result_label = QLabel("你的兴趣：")
result_label.setStyleSheet("font-size: 14px; margin-top: 10px;")
layout.addWidget(result_label)
def show_result():
hobbies.clear()
if cb1.isChecked():
hobbies.append(cb1.text())
if cb2.isChecked():
hobbies.append(cb2.text())
if cb3.isChecked():
hobbies.append(cb3.text())
result_label.setText(f"你的兴趣：{'、'.join(hobbies) if hobbies else '无'}")
# 绑定状态变化事件
cb1.stateChanged.connect(show_result)
cb2.stateChanged.connect(show_result)
cb3.stateChanged.connect(show_result)
window.show()
sys.exit(app.exec())
3.7 单选按钮（QRadioButton）：单选功能
QRadioButton 用于实现单选功能，同一组中只能勾选一个选项，常用于选择性别、学历等场景。
示例：性别选择
from PyQt6.QtWidgets import QApplication, QWidget, QRadioButton, QVBoxLayout, QLabel, QGroupBox
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QRadioButton示例")
window.resize(300, 200)
layout = QVBoxLayout(window)
# 创建分组框（将单选按钮分组，确保互斥）
group_box = QGroupBox("选择性别")
group_box.setStyleSheet("font-size: 14px;")
group_layout = QVBoxLayout(group_box)
# 单选按钮：男
rb1 = QRadioButton("男")
rb1.setStyleSheet("font-size: 14px;")
rb1.setChecked(True) # 默认勾选
group_layout.addWidget(rb1)
# 单选按钮：女
rb2 = QRadioButton("女")
rb2.setStyleSheet("font-size: 14px;")
group_layout.addWidget(rb2)
layout.addWidget(group_box)
# 显示选择结果
result_label = QLabel("你的性别：男")
result_label.setStyleSheet("font-size: 14px; margin-top: 10px;")
layout.addWidget(result_label)
def show_gender():
if rb1.isChecked():
result_label.setText("你的性别：男")
else:
result_label.setText("你的性别：女")
# 绑定状态变化事件
rb1.toggled.connect(show_gender)
rb2.toggled.connect(show_gender)
window.show()
sys.exit(app.exec())
3.8 下拉菜单（QComboBox）：选择预设选项
QComboBox 提供下拉选择列表，用户从预设选项中选择一个，常用于选择城市、年级、文件类型等场景。
示例：城市选择
from PyQt6.QtWidgets import QApplication, QWidget, QComboBox, QVBoxLayout, QLabel
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QComboBox示例")
window.resize(300, 200)
layout = QVBoxLayout(window)
# 创建下拉菜单
combo = QComboBox()
combo.setStyleSheet("font-size: 14px; padding: 8px;")
# 添加选项
combo.addItems(["北京", "上海", "广州", "深圳", "杭州"])
# 设置默认选项（索引从0开始）
combo.setCurrentIndex(0)
layout.addWidget(combo)
# 显示选择结果
result_label = QLabel(f"你选择的城市：{combo.currentText()}")
result_label.setStyleSheet("font-size: 14px; margin-top: 20px;")
layout.addWidget(result_label)
# 绑定选项变化事件
def on_combo_change(index):
result_label.setText(f"你选择的城市：{combo.itemText(index)}")
combo.currentIndexChanged.connect(on_combo_change)
window.show()
sys.exit(app.exec())
3.9 滑块（QSlider）：调节数值
QSlider 用于让用户通过拖动滑块调节数值，常用于调节音量、亮度、字体大小等场景。
示例：调节字体大小
from PyQt6.QtWidgets import QApplication, QWidget, QSlider, QVBoxLayout, QLabel
from PyQt6.QtCore import Qt
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QSlider示例")
window.resize(300, 200)
layout = QVBoxLayout(window)
# 创建滑块（水平方向）
slider = QSlider(Qt.Orientation.Horizontal)
slider.setRange(10, 30) # 数值范围
slider.setValue(14) # 默认值
slider.setSingleStep(1) # 步长
layout.addWidget(slider)
# 显示调节结果
label = QLabel("当前字体大小：14px")
label.setStyleSheet("font-size: 14px; margin-top: 20px;")
layout.addWidget(label)
# 绑定滑块值变化事件
def on_slider_change(value):
label.setText(f"当前字体大小：{value}px")
label.setStyleSheet(f"font-size: {value}px; margin-top: 20px;")
slider.valueChanged.connect(on_slider_change)
window.show()
sys.exit(app.exec())
3.10 列表框（QListWidget）：展示列表数据
QListWidget 用于展示单列列表数据，支持单选、多选和双击事件，常用于展示文件列表、选项列表等。
示例：文件列表展示与选择
from PyQt6.QtWidgets import QApplication, QWidget, QListWidget, QListWidgetItem, QVBoxLayout, QLabel
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QListWidget示例")
window.resize(300, 200)
layout = QVBoxLayout(window)
# 创建列表框
list_widget = QListWidget()
list_widget.setStyleSheet("font-size: 14px;")
# 设置选择模式：多选
list_widget.setSelectionMode(QListWidget.SelectionMode.MultiSelection)
# 添加列表项
items = ["文件1.txt", "文件2.jpg", "文件3.pdf", "文件4.exe"]
for item_text in items:
QListWidgetItem(item_text, list_widget)
layout.addWidget(list_widget)
# 显示选择结果
result_label = QLabel("你选择的文件：无")
result_label.setStyleSheet("font-size: 14px; margin-top: 10px;")
layout.addWidget(result_label)
# 绑定选择变化事件
def on_list_select():
selected_items = list_widget.selectedItems()
selected_texts = [item.text() for item in selected_items]
result_label.setText(f"你选择的文件：{'、'.join(selected_texts) if selected_texts else '无'}")
list_widget.itemSelectionChanged.connect(on_list_select)
window.show()
sys.exit(app.exec())
四、布局管理：让组件整齐排列
PyQt6 提供三种核心布局方式，用于控制组件在窗口中的位置和大小，避免手动计算坐标的繁琐，确保窗口大小变化时组件能自适应调整。
4.1 垂直布局（QVBoxLayout）：组件垂直排列
QVBoxLayout 将组件按垂直方向依次排列，适合需要上下布局的场景（如表单、列表）。
示例：垂直布局的表单
from PyQt6.QtWidgets import QApplication, QWidget, QLabel, QLineEdit, QPushButton, QVBoxLayout
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QVBoxLayout示例")
window.resize(300, 250)
# 创建垂直布局
layout = QVBoxLayout(window)
layout.setSpacing(15) # 组件之间的间距
layout.setContentsMargins(20, 20, 20, 20) # 布局与窗口的内边距
# 添加组件
layout.addWidget(QLabel("用户名："))
layout.addWidget(QLineEdit())
layout.addWidget(QLabel("密码："))
layout.addWidget(QLineEdit())
layout.addWidget(QLabel("邮箱："))
layout.addWidget(QLineEdit())
# 按钮：添加到布局底部，居中对齐
login_btn = QPushButton("注册")
layout.addWidget(login_btn, alignment=Qt.AlignmentFlag.AlignCenter)
window.show()
sys.exit(app.exec())
4.2 水平布局（QHBoxLayout）：组件水平排列
QHBoxLayout 将组件按水平方向依次排列，适合需要左右布局的场景（如工具栏、按钮组）。
示例：水平布局的按钮组
from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QHBoxLayout
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QHBoxLayout示例")
window.resize(300, 100)
# 创建水平布局
layout = QHBoxLayout(window)
layout.setSpacing(10)
layout.setContentsMargins(20, 20, 20, 20)
# 添加按钮
layout.addWidget(QPushButton("新建"))
layout.addWidget(QPushButton("打开"))
layout.addWidget(QPushButton("保存"))
layout.addWidget(QPushButton("退出"))
# 设置组件拉伸比例（让按钮自适应窗口宽度）
layout.setStretch(0, 1)
layout.setStretch(1, 1)
layout.setStretch(2, 1)
layout.setStretch(3, 1)
window.show()
sys.exit(app.exec())
4.3 网格布局（QGridLayout）：表格形式排列
QGridLayout 将组件按 “行 × 列” 的表格形式排列，适合复杂的界面布局（如登录窗口、数据表格）。
示例：网格布局的登录窗口
from PyQt6.QtWidgets import QApplication, QWidget, QLabel, QLineEdit, QPushButton, QGridLayout, QMessageBox
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QGridLayout示例")
window.resize(300, 200)
# 创建网格布局
layout = QGridLayout(window)
layout.setSpacing(15)
layout.setContentsMargins(30, 30, 30, 30)
# 添加组件（行索引，列索引，跨行数，跨列数）
layout.addWidget(QLabel("用户名："), 0, 0)
layout.addWidget(QLineEdit(), 0, 1, 1, 2) # 第0行第1列，跨2列
layout.addWidget(QLabel("密码："), 1, 0)
layout.addWidget(QLineEdit(), 1, 1, 1, 2)
# 登录按钮：第2行第1-2列，跨2列
login_btn = QPushButton("登录")
login_btn.clicked.connect(lambda: QMessageBox.information(window, "提示", "登录中…"))
layout.addWidget(login_btn, 2, 1, 1, 2)
window.show()
sys.exit(app.exec())
4.4 布局嵌套：实现复杂界面
实际开发中，常将多种布局嵌套使用，实现更灵活的界面布局。
示例：嵌套布局的综合示例
from PyQt6.QtWidgets import QApplication, QWidget, QLabel, QPushButton, QVBoxLayout, QHBoxLayout
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("布局嵌套示例")
window.resize(400, 300)
# 主布局：垂直布局
main_layout = QVBoxLayout(window)
# 顶部区域：水平布局（标题+按钮）
top_layout = QHBoxLayout()
top_layout.addWidget(QLabel("复杂界面布局示例"), alignment=Qt.AlignmentFlag.AlignLeft)
top_layout.addWidget(QPushButton("设置"), alignment=Qt.AlignmentFlag.AlignRight)
main_layout.addLayout(top_layout)
# 中间区域：网格布局（表单）
grid_layout = QGridLayout()
grid_layout.addWidget(QLabel("姓名："), 0, 0)
grid_layout.addWidget(QLineEdit(), 0, 1)
grid_layout.addWidget(QLabel("年龄："), 1, 0)
grid_layout.addWidget(QLineEdit(), 1, 1)
main_layout.addLayout(grid_layout)
# 底部区域：水平布局（功能按钮）
bottom_layout = QHBoxLayout()
bottom_layout.addWidget(QPushButton("确定"))
bottom_layout.addWidget(QPushButton("取消"))
main_layout.addLayout(bottom_layout, alignment=Qt.AlignmentFlag.AlignCenter)
window.show()
sys.exit(app.exec())
五、事件处理：PyQt6 的核心 —— 信号与槽机制
PyQt6 的交互核心是 “信号与槽（Signal and Slot）” 机制，组件的动作（如点击、输入、选择）会发出 “信号”，开发者通过绑定 “槽函数” 来响应这些信号，实现交互逻辑。
5.1 信号与槽的基本使用
方式 1：直接绑定槽函数
from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QVBoxLayout
import sys
app = QApplication(sys.argv)
window = QWidget()
window.resize(300, 200)
layout = QVBoxLayout(window)
# 定义槽函数
def on_click():
print("按钮被点击了！")
# 创建按钮，绑定信号与槽
btn = QPushButton("点击我")
btn.clicked.connect(on_click) # clicked是信号，connect绑定槽函数
layout.addWidget(btn)
window.show()
sys.exit(app.exec())
方式 2：带参数的槽函数
from PyQt6.QtWidgets import QApplication, QWidget, QSlider, QVBoxLayout, QLabel
import sys
app = QApplication(sys.argv)
window = QWidget()
window.resize(300, 200)
layout = QVBoxLayout(window)
label = QLabel("当前值：50")
layout.addWidget(label)
# 带参数的槽函数
def on_value_change(value):
label.setText(f"当前值：{value}")
# 滑块值变化信号（带参数）绑定槽函数
slider = QSlider(Qt.Orientation.Horizontal)
slider.setRange(0, 100)
slider.setValue(50)
slider.valueChanged.connect(on_value_change) # valueChanged信号传递数值参数
layout.addWidget(slider)
window.show()
sys.exit(app.exec())
方式 3：解除信号与槽的绑定
from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QVBoxLayout
import sys
app = QApplication(sys.argv)
window = QWidget()
window.resize(300, 200)
layout = QVBoxLayout(window)
def on_click():
print("按钮被点击了！")
# 解除绑定，后续点击不再触发
btn.clicked.disconnect(on_click)
btn = QPushButton("点击一次")
btn.clicked.connect(on_click)
layout.addWidget(btn)
window.show()
sys.exit(app.exec())
5.2 常用组件的核心信号
| QPushButton | clicked() | 按钮被点击时发出 |
| QLineEdit | textChanged(text) | 文本内容变化时发出（带文本参数） |
| QCheckBox | stateChanged(state) | 勾选状态变化时发出（带状态参数） |
| QRadioButton | toggled(checked) | 勾选状态变化时发出（带布尔参数） |
| QComboBox | currentIndexChanged(index) | 选择项变化时发出（带索引参数） |
| QSlider | valueChanged(value) | 滑块值变化时发出（带数值参数） |
| QListWidget | itemClicked(item) | 列表项被点击时发出（带项参数） |
5.3 自定义信号与槽
除了组件自带的信号，还可以自定义信号，实现更灵活的事件传递。
示例：自定义信号
from PyQt6.QtCore import QObject, pyqtSignal
from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QVBoxLayout
import sys
# 自定义信号类（必须继承QObject）
class MySignal(QObject):
# 定义自定义信号（可带参数）
custom_signal = pyqtSignal(str)
app = QApplication(sys.argv)
window = QWidget()
window.resize(300, 200)
layout = QVBoxLayout(window)
# 创建信号实例
signal = MySignal()
# 定义槽函数
def on_custom_signal(msg):
print(f"收到自定义信号：{msg}")
# 绑定自定义信号与槽
signal.custom_signal.connect(on_custom_signal)
# 按钮点击时发射自定义信号
def send_signal():
signal.custom_signal.emit("Hello, 自定义信号！")
btn = QPushButton("发射信号")
btn.clicked.connect(send_signal)
layout.addWidget(btn)
window.show()
sys.exit(app.exec())
六、进阶功能：打造专业级桌面应用
6.1 菜单与工具栏：应用功能导航
菜单和工具栏是桌面应用的标准组件，用于组织核心功能（如文件操作、编辑功能）。
示例：带菜单和工具栏的主窗口
from PyQt6.QtWidgets import QApplication, QMainWindow, QTextEdit, QAction, QFileDialog, QMessageBox
from PyQt6.QtGui import QIcon
import sys
class MainWindow(QMainWindow):
def __init__(self):
super().__init__()
self.setWindowTitle("菜单与工具栏示例")
self.resize(600, 400)
# 设置中心组件（文本编辑区）
self.text_edit = QTextEdit()
self.setCentralWidget(self.text_edit)
# 创建菜单
self.create_menu()
# 创建工具栏
self.create_toolbar()
def create_menu(self):
# 获取主菜单栏
menu_bar = self.menuBar()
# 文件菜单
file_menu = menu_bar.addMenu("文件")
# 新建动作
new_action = QAction(QIcon("new.png"), "新建", self)
new_action.setShortcut("Ctrl+N") # 快捷键
new_action.triggered.connect(self.new_file)
file_menu.addAction(new_action)
# 打开动作
open_action = QAction(QIcon("open.png"), "打开", self)
open_action.setShortcut("Ctrl+O")
open_action.triggered.connect(self.open_file)
file_menu.addAction(open_action)
# 保存动作
save_action = QAction(QIcon("save.png"), "保存", self)
save_action.setShortcut("Ctrl+S")
save_action.triggered.connect(self.save_file)
file_menu.addAction(save_action)
# 分隔线
file_menu.addSeparator()
# 退出动作
exit_action = QAction("退出", self)
exit_action.setShortcut("Ctrl+Q")
exit_action.triggered.connect(self.close)
file_menu.addAction(exit_action)
def create_toolbar(self):
# 创建工具栏
toolbar = self.addToolBar("工具栏")
# 添加动作（与菜单动作共用）
new_action = QAction(QIcon("new.png"), "新建", self)
new_action.triggered.connect(self.new_file)
toolbar.addAction(new_action)
open_action = QAction(QIcon("open.png"), "打开", self)
open_action.triggered.connect(self.open_file)
toolbar.addAction(open_action)
save_action = QAction(QIcon("save.png"), "保存", self)
save_action.triggered.connect(self.save_file)
toolbar.addAction(save_action)
def new_file(self):
self.text_edit.clear()
self.setWindowTitle("未命名文件")
def open_file(self):
file_path, _ = QFileDialog.getOpenFileName(self, "打开文件", "", "文本文件 (*.txt)")
if file_path:
with open(file_path, "r", encoding="utf-8") as f:
self.text_edit.setText(f.read())
self.setWindowTitle(file_path)
def save_file(self):
file_path, _ = QFileDialog.getSaveFileName(self, "保存文件", "", "文本文件 (*.txt)")
if file_path:
with open(file_path, "w", encoding="utf-8") as f:
f.write(self.text_edit.toPlainText())
self.setWindowTitle(file_path)
QMessageBox.information(self, "提示", "保存成功！")
if __name__ == "__main__":
app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())
6.2 对话框：交互提示与输入
PyQt6 提供多种内置对话框，用于显示提示、警告、确认信息，或获取用户输入、选择文件等。
示例：常用对话框
from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QVBoxLayout, QMessageBox, QFileDialog, QInputDialog
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("对话框示例")
window.resize(300, 200)
layout = QVBoxLayout(window)
# 1. 信息对话框
def show_info():
QMessageBox.information(window, "信息", "这是一条信息提示！")
# 2. 警告对话框
def show_warning():
QMessageBox.warning(window, "警告", "这是一条警告信息！")
# 3. 确认对话框
def show_confirm():
result = QMessageBox.question(window, "确认", "你确定要退出吗？", QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No)
if result == QMessageBox.StandardButton.Yes:
window.close()
# 4. 文件选择对话框
def select_file():
file_path, _ = QFileDialog.getOpenFileName(window, "选择文件", "", "所有文件 (*.*)")
QMessageBox.information(window, "选择结果", f"你选择的文件：{file_path}")
# 5. 输入对话框
def input_text():
text, ok = QInputDialog.getText(window, "输入", "请输入你的名字：")
if ok and text:
QMessageBox.information(window, "问候", f"你好，{text}！")
# 添加按钮
layout.addWidget(QPushButton("信息框", clicked=show_info))
layout.addWidget(QPushButton("警告框", clicked=show_warning))
layout.addWidget(QPushButton("确认框", clicked=show_confirm))
layout.addWidget(QPushButton("选择文件", clicked=select_file))
layout.addWidget(QPushButton("输入框", clicked=input_text))
window.show()
sys.exit(app.exec())
6.3 多线程：避免界面卡顿
当应用执行耗时操作（如文件下载、数据处理）时，若在主线程中执行，会导致界面冻结无响应。解决方法是将耗时操作放在子线程中执行。
示例：多线程处理耗时任务
from PyQt6.QtCore import QThread, pyqtSignal
from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QVBoxLayout, QProgressBar, QLabel
import sys
import time
# 自定义子线程类
class WorkerThread(QThread):
# 定义信号（传递进度值）
progress_signal = pyqtSignal(int)
# 任务完成信号
finish_signal = pyqtSignal()
def run(self):
# 模拟耗时任务（10秒完成，每1秒更新一次进度）
for i in range(1, 11):
time.sleep(1)
self.progress_signal.emit(i * 10) # 发送进度信号
self.finish_signal.emit() # 发送完成信号
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("多线程示例")
window.resize(300, 200)
layout = QVBoxLayout(window)
# 进度条
progress_bar = QProgressBar()
progress_bar.setRange(0, 100)
layout.addWidget(progress_bar)
# 状态标签
status_label = QLabel("等待任务开始…")
layout.addWidget(status_label)
# 开始按钮
def start_task():
btn.setEnabled(False)
status_label.setText("任务执行中…")
# 创建并启动子线程
thread = WorkerThread()
thread.progress_signal.connect(update_progress)
thread.finish_signal.connect(task_finish)
thread.start()
def update_progress(value):
progress_bar.setValue(value)
def task_finish():
status_label.setText("任务完成！")
btn.setEnabled(True)
btn = QPushButton("开始耗时任务")
btn.clicked.connect(start_task)
layout.addWidget(btn)
window.show()
sys.exit(app.exec())
6.4 界面美化：QSS 样式表
QSS（Qt Style Sheet）是 PyQt6 的样式表语言，类似 CSS，可自定义组件的外观，打造现代化界面。
示例：QSS 美化界面
from PyQt6.QtWidgets import QApplication, QWidget, QLabel, QPushButton, QVBoxLayout, QLineEdit
import sys
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QSS美化示例")
window.resize(300, 250)
# 设置全局QSS样式
window.setStyleSheet("""
QWidget {
background-color: #f5f5f5;
}
QLabel {
font-size: 14px;
color: #333;
}
QLineEdit {
font-size: 14px;
padding: 8px;
border: 1px solid #ddd;
border-radius: 4px;
background-color: white;
}
QLineEdit:focus {
border-color: #2196F3;
outline: none;
}
QPushButton {
font-size: 14px;
padding: 10px;
background-color: #2196F3;
color: white;
border: none;
border-radius: 4px;
}
QPushButton:hover {
background-color: #1976D2;
}
QPushButton:pressed {
background-color: #0D47A1;
}
""")
layout = QVBoxLayout(window)
layout.setSpacing(15)
layout.setContentsMargins(30, 30, 30, 30)
layout.addWidget(QLabel("用户名："))
layout.addWidget(QLineEdit())
layout.addWidget(QLabel("密码："))
layout.addWidget(QLineEdit())
layout.addWidget(QPushButton("登录"))
window.show()
sys.exit(app.exec())
6.5 自定义组件：扩展功能
当内置组件无法满足需求时，可通过继承现有组件自定义新组件，实现个性化功能。
示例：自定义计数器组件
from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QLabel, QHBoxLayout
import sys
# 自定义计数器组件
class CounterWidget(QWidget):
def __init__(self, parent=None):
super().__init__(parent)
self.count = 0
self.init_ui()
def init_ui(self):
# 布局
layout = QHBoxLayout(self)
layout.setSpacing(10)
# 减号按钮
self.minus_btn = QPushButton("-")
self.minus_btn.clicked.connect(self.decrement)
layout.addWidget(self.minus_btn)
# 计数标签
self.count_label = QLabel("0")
self.count_label.setStyleSheet("font-size: 16px; width: 40px; text-align: center;")
layout.addWidget(self.count_label)
# 加号按钮
self.plus_btn = QPushButton("+")
self.plus_btn.clicked.connect(self.increment)
layout.addWidget(self.plus_btn)
def increment(self):
self.count += 1
self.count_label.setText(str(self.count))
def decrement(self):
if self.count > 0:
self.count -= 1
self.count_label.setText(str(self.count))
# 测试自定义组件
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("自定义组件示例")
window.resize(200, 100)
layout = QHBoxLayout(window)
layout.addWidget(CounterWidget())
layout.addWidget(CounterWidget())
window.show()
sys.exit(app.exec())
七、实战案例：开发一个完整的计算器应用
结合前面的知识点，开发一个简易计算器应用，支持加减乘除四则运算，整合组件、布局、事件处理等核心功能。
7.1 功能需求
7.2 代码实现
from PyQt6.QtWidgets import QApplication, QMainWindow, QWidget, QLineEdit, QGridLayout, QPushButton
from PyQt6.QtCore import Qt
import sys
class Calculator(QMainWindow):
def __init__(self):
super().__init__()
self.setWindowTitle("简易计算器")
self.resize(300, 400)
self.setFixedSize(300, 400) # 禁止调整大小
# 初始化计算状态
self.current_text = "" # 当前输入文本
self.result = 0 # 计算结果
self.operator = "" # 运算符
self.reset_display = False # 是否重置显示
# 设置中心组件
central_widget = QWidget()
self.setCentralWidget(central_widget)
# 创建布局
self.layout = QGridLayout(central_widget)
self.layout.setSpacing(5)
self.layout.setContentsMargins(10, 10, 10, 10)
# 创建显示框
self.create_display()
# 创建按钮
self.create_buttons()
def create_display(self):
# 显示框（只读）
self.display = QLineEdit()
self.display.setReadOnly(True)
self.display.setStyleSheet("""
QLineEdit {
font-size: 24px;
padding: 10px;
text-align: right;
background-color: #f9f9f9;
border: 1px solid #ddd;
border-radius: 4px;
}
""")
self.display.setText("0")
# 显示框占第一行，跨4列
self.layout.addWidget(self.display, 0, 0, 1, 4)
def create_buttons(self):
# 按钮布局（5行4列）
buttons = [
["AC", "±", "%", "÷"],
["7", "8", "9", "×"],
["4", "5", "6", "-"],
["1", "2", "3", "+"],
["0", ".", "←", "="]
]
# 按钮样式
btn_style = """
QPushButton {
font-size: 18px;
padding: 15px;
border: none;
border-radius: 4px;
}
QPushButton:hover {
background-color: #e0e0e0;
}
"""
# 运算符按钮样式
op_btn_style = btn_style + "background-color: #ff9500; color: white;"
# 数字按钮样式
num_btn_style = btn_style + "background-color: #f2f2f2;"
# 等号按钮样式
eq_btn_style = btn_style + "background-color: #ff5722; color: white;"
# 添加按钮到布局
for row in range(len(buttons)):
for col in range(len(buttons[row])):
btn_text = buttons[row][col]
btn = QPushButton(btn_text)
# 设置按钮样式
if btn_text in ["+", "-", "×", "÷"]:
btn.setStyleSheet(op_btn_style)
elif btn_text == "=":
btn.setStyleSheet(eq_btn_style)
else:
btn.setStyleSheet(num_btn_style)
# 绑定点击事件
btn.clicked.connect(lambda checked, text=btn_text: self.on_button_click(text))
# 添加到布局
self.layout.addWidget(btn, row+1, col) # 行从1开始（第0行是显示框）
def on_button_click(self, text):
if text == "AC":
# 清空
self.current_text = ""
self.result = 0
self.operator = ""
self.display.setText("0")
elif text == "±":
# 正负号
if self.current_text.startswith("-"):
self.current_text = self.current_text[1:]
else:
self.current_text = "-" + self.current_text
if self.current_text:
self.display.setText(self.current_text)
elif text == "%":
# 百分比
if self.current_text:
value = float(self.current_text) / 100
self.current_text = str(value)
self.display.setText(self.current_text)
elif text == "←":
# 删除
self.current_text = self.current_text[:-1]
self.display.setText(self.current_text if self.current_text else "0")
elif text in ["+", "-", "×", "÷"]:
# 运算符
if self.current_text:
self.result = float(self.current_text)
self.operator = text
self.current_text = ""
self.reset_display = True
elif text == "=":
# 计算结果
if self.current_text and self.operator:
current_value = float(self.current_text)
if self.operator == "+":
self.result += current_value
elif self.operator == "-":
self.result -= current_value
elif self.operator == "×":
self.result *= current_value
elif self.operator == "÷":
if current_value != 0:
self.result /= current_value
else:
self.display.setText("错误")
return
# 结果转为字符串，去除末尾的.0
self.current_text = str(int(self.result)) if self.result.is_integer() else str(self.result)
self.display.setText(self.current_text)
self.operator = ""
self.reset_display = True
elif text == ".":
# 小数点
if "." not in self.current_text:
self.current_text += "."
self.display.setText(self.current_text)
else:
# 数字
if self.reset_display:
self.current_text = text
self.reset_display = False
else:
self.current_text += text
self.display.setText(self.current_text)
if __name__ == "__main__":
app = QApplication(sys.argv)
calculator = Calculator()
calculator.show()
sys.exit(app.exec())
7.3 功能演示
八、避坑指南：PyQt6 新手常犯的 6 个错误
忘记创建 QApplication 实例：每个 PyQt6 程序必须有且只有一个 QApplication 实例，否则会报错。解决：在创建窗口前先创建app = QApplication(sys.argv)。
组件未添加到布局或未设置父组件：组件未添加到布局，或未指定parent参数，会导致组件无法显示。解决：将组件添加到布局，或创建时指定parent=window。
主线程执行耗时操作导致界面卡顿：在主线程中执行 sleep、文件下载等耗时操作，会阻塞事件循环。解决：将耗时操作放在子线程中，通过信号传递结果。
信号与槽绑定错误：槽函数参数数量与信号传递的参数不匹配，或绑定已被删除的组件信号。解决：确保槽函数参数与信号一致，避免绑定无效组件。
QSS 样式不生效：样式语法错误，或组件未被样式表覆盖。解决：检查 QSS 语法，确保样式选择器正确，可通过setStyleSheet直接给组件设置样式。
窗口关闭后程序未退出：主窗口关闭后，应用事件循环未终止。解决：使用sys.exit(app.exec())启动事件循环，确保窗口关闭时程序退出。
九、总结：PyQt6 学习路径与进阶建议
核心知识点回顾
进阶学习建议
PyQt6 的学习核心是 “多动手实践”—— 从简单组件开始，逐步搭建复杂界面，结合实际需求开发工具，遇到问题时查阅官方文档（https://doc.qt.io/qtforpython/）。它虽然学习曲线比 Tkinter 陡，但掌握后能开发出专业级的桌面应用，是 Python 开发者提升竞争力的重要技能。
