PyQt5是Python语言对Qt5框架的完整绑定,由Riverbank Computing开发并维护,是目前Python生态中最成熟、功能最全面的GUI开发框架之一。它不仅继承了Qt5跨平台、高性能、模块化的设计哲学,还通过Python的简洁语法大幅降低了GUI开发门槛。
与其他主流Python GUI框架(如Tkinter、wxPython、Kivy、PySide2)相比,PyQt5具备以下显著优势:
在工业控制、数据可视化、多媒体应用、科学计算、教育软件等领域,PyQt5已成为Python开发者的首选方案。例如:中国科学院自动化所的某些实验控制系统、国内某头部金融公司的量化分析平台桌面端、高校实验室的仪器数据采集系统,均采用PyQt5构建。
相比原生C++ Qt开发,Python语法更简洁,代码量通常减少30%~50%,调试更便捷。
核心模块(QtCore/QtGui/QtWidgets)+扩展模块(QtNetwork/QtSql/QtWebEngine)按需导入,轻量灵活。
无缝调用NumPy/Pandas/Matplotlib,实现科学计算与可视化一体化;支持NumPy数组与QImage互转。
PyQt5采用模块化设计,主要核心模块包括:QtCore、QtGui、QtWidgets、QtMultimedia、QtNetwork等。掌握这些模块的职责与协作关系,是构建健壮应用的基础。
QtCore提供核心非GUI功能,包括:
典型场景:在数据处理应用中,使用QTimer监控后台任务状态;通过QFile读取配置文件并解析为字典对象。
QtGui提供底层图形绘制与用户输入支持:
示例:绘制带渐变背景的自定义按钮,需重写paintEvent(),使用QPainter绘制圆角矩形并应用线性渐变:
def paintEvent(self, event):
painter = QPainter(self)
painter.setRenderHint(QPainter.Antialiasing)
grad = QLinearGradient(0, 0, self.width(), self.height())
grad.setColorAt(0, QColor(51, 126, 243))
grad.setColorAt(1, QColor(2, 91, 176))
painter.setBrush(QBrush(grad))
painter.setPen(Qt.NoPen)
painter.drawRoundedRect(self.rect(), 10, 10)
QtWidgets提供完整的桌面UI控件体系:
| 控件类别 | 典型控件 | 适用场景 |
|---|---|---|
| 基础控件 | QPushButton、QLabel、QLineEdit、QTextEdit | 表单输入、文本显示、交互按钮 |
| 容器控件 | QFrame、QGroupBox、QScrollArea、QTabWidget | 界面分区、可滚动区域、选项卡导航 |
| 数据展示 | QTableWidget、QTreeWidget、QListView、QTableView | 表格数据、树形结构、列表项展示 |
| 高级控件 | QCalendarWidget、QDateTimeEdit、QProgressBar | 日期选择、进度反馈、时间编辑 |
最佳实践:使用QStackedWidget构建多页向导界面,通过 setCurrentIndex() 实现页面切换;QTableWidget配合QTableWidgetItem可快速构建数据录入表格,支持编辑、排序、右键菜单。
QtMultimedia模块提供音频/视频播放、摄像头访问能力:
QtNetwork模块实现网络通信:
典型应用:开发带天气预报功能的桌面助手,通过QNetworkAccessManager调用OpenWeatherMap API,解析JSON响应后更新界面。
布局管理是GUI开发的核心挑战。PyQt5提供多种布局管理器,确保界面在不同屏幕尺寸下自适应:
| 布局类型 | 特点 | 适用场景 | 关键API |
|---|---|---|---|
| QVBoxLayout | 垂直堆叠控件 | 表单顶部标题+输入区 | addWidget(), addStretch() |
| QHBoxLayout | 水平排列控件 | 按钮组、工具栏 | addWidget(), addSpacing() |
| QGridLayout | 网格布局,支持跨行跨列 | 计算器、表单对齐 | addWidget(widget, row, col, rowspan, colspan) |
| QFormLayout | 标签-输入对齐布局 | 设置表单、注册表单 | addRow(label, input) |
| QStackedLayout | 多页面切换(仅显示一个) | 向导、选项卡容器 | setCurrentIndex(), addWidget() |
复杂界面需组合使用布局管理器。例如,构建一个包含工具栏、主编辑区、状态栏的文本编辑器:
# 主窗口布局
main_layout = QVBoxLayout()
toolbar = QHBoxLayout()
editor = QTextEdit()
statusbar = QHBoxLayout()
# 工具栏布局
btn_bold = QPushButton("粗体")
btn_italic = QPushButton("斜体")
toolbar.addWidget(btn_bold)
toolbar.addWidget(btn_italic)
toolbar.addStretch() # 右侧留空
# 状态栏布局
cursor_pos = QLabel("光标: 1:1")
word_count = QLabel("字数: 0")
statusbar.addWidget(cursor_pos)
statusbar.addWidget(word_count)
# 组合布局
main_layout.addLayout(toolbar)
main_layout.addWidget(editor) # 自动扩展
main_layout.addLayout(statusbar)
self.setLayout(main_layout)
关键技巧:
addStretch()在控件后插入弹性空间,实现右对齐或垂直居中当布局无法通过标准管理器满足需求时,可重写 resizeEvent() 动态调整:
def resizeEvent(self, event):
super().resizeEvent(event)
# 动态调整侧边栏宽度为窗口宽度的20%
sidebar_width = int(self.width() * 0.2)
self.sidebar.setFixedWidth(sidebar_width)
注意:避免在 resizeEvent() 中直接设置固定尺寸,应结合 QSizePolicy 使用,防止布局冲突。
信号槽(Signal-Slot)是Qt的核心设计模式,实现对象间松耦合通信。信号由对象发出,槽函数负责响应。其优势在于:
语法:sender.signal.connect(receiver.slot)
def on_button_clicked():
print("按钮被点击!")
button = QPushButton("提交")
button.clicked.connect(on_button_clicked)
信号可携带参数,槽函数需匹配参数类型:
class Counter(QObject):
valueChanged = pyqtSignal(int) # 定义信号:整型参数
def __init__(self):
super().__init__()
self._value = 0
def increment(self):
self._value += 1
self.valueChanged.emit(self._value) # 发送信号
counter = Counter()
counter.valueChanged.connect(lambda v: print(f"当前值: {v}"))
| 控件 | 典型信号 | 触发条件 |
|---|---|---|
| QPushButton | clicked() | 按钮被点击(鼠标按下并释放) |
| QLineEdit | textChanged(str) | 文本内容变化 |
| QTextEdit | textChanged() | 文本内容变化(无参数) |
| QComboBox | currentIndexChanged(int) | 当前选项索引变化 |
| QSlider | valueChanged(int) | 滑块值变化 |
| QTimer | timeout() | 定时器超时 |
当槽函数需额外参数时,使用lambda包装:
def update_status(index, label):
texts = ["欢迎", "设置", "关于"]
label.setText(f"当前页: {texts[index]}")
tabs = QTabWidget()
tabs.addTab(QWidget(), "首页")
tabs.addTab(QWidget(), "设置")
tabs.addTab(QWidget(), "关于")
status_label = QLabel("欢迎")
tabs.currentChanged.connect(lambda idx: update_status(idx, status_label))
避免内存泄漏:当对象销毁前,手动断开连接:
button.clicked.disconnect(on_button_clicked)
或使用 Qt.DirectConnection 确保同步调用(避免跨线程问题):
button.clicked.connect(on_button_clicked, Qt.DirectConnection)
PyQt5允许通过继承 QWidget 或 QMainWindow 创建自定义控件,实现个性化交互。典型场景包括:带图标按钮、自定义进度条、数据可视化图表控件。
from PyQt5.QtWidgets import QWidget
from PyQt5.QtGui import QPainter, QBrush, QColor
from PyQt5.QtCore import Qt
class CustomButton(QWidget):
def __init__(self, text="自定义按钮"):
super().__init__()
self.text = text
self.setFixedSize(120, 40)
def paintEvent(self, event):
painter = QPainter(self)
painter.setRenderHint(QPainter.Antialiasing)
# 绘制圆角矩形背景
painter.setBrush(QBrush(QColor(51, 126, 243)))
painter.setPen(Qt.NoPen)
painter.drawRoundedRect(self.rect(), 8, 8)
# 绘制文字
painter.setPen(QColor(255, 255, 255))
painter.drawText(self.rect(), Qt.AlignCenter, self.text)
重写 mousePressEvent / mouseReleaseEvent 实现交互:
def mousePressEvent(self, event):
if event.button() == Qt.LeftButton:
self.bg_color = QColor(3, 126, 243) # 按下颜色
self.update()
def mouseReleaseEvent(self, event):
self.bg_color = QColor(51, 126, 243) # 恢复颜色
self.update()
# 触发点击信号
self.clicked.emit()
# 添加自定义信号
clicked = pyqtSignal()
当需监控其他控件事件时,使用事件过滤器:
class MyWidget(QWidget):
def __init__(self):
super().__init__()
self.btn = QPushButton("按钮")
self.btn.installEventFilter(self)
def eventFilter(self, obj, event):
if obj == self.btn:
if event.type() == QEvent.MouseButtonPress:
print("按钮被按下!")
return True # 吞噬事件
return super().eventFilter(obj, event)
class IconBtn(QPushButton):
def __init__(self, icon_path, text=""):
super().__init__(text)
self.icon = QIcon(icon_path)
self.setIcon(self.icon)
self.setIconSize(QSize(24, 24))
self.setStyleSheet("""
QPushButton {
border: none;
padding: 8px 16px;
background: transparent;
}
QPushButton:hover {
background: #e6f4ff;
border-radius: 6px;
}
""")
优势:复用性强,可统一图标样式;通过样式表(QSS)实现主题切换。
GUI主线程(UI线程)负责事件循环,若执行耗时操作(如文件下载、数据处理),界面将冻结。PyQt5提供两种安全多线程方案:
from PyQt5.QtCore import QThread, pyqtSignal, QObject
class Worker(QObject):
finished = pyqtSignal()
result = pyqtSignal(str)
def do_work(self):
# 模拟耗时操作
time.sleep(3)
self.result.emit("任务完成!")
self.finished.emit()
class MainWindow(QMainWindow):
def __init__(self):
super().__init__()
self.thread = QThread()
self.worker = Worker()
self.worker.moveToThread(self.thread)
self.thread.started.connect(self.worker.do_work)
self.worker.finished.connect(self.thread.quit)
self.worker.finished.connect(self.worker.deleteLater)
self.thread.finished.connect(self.thread.deleteLater)
self.worker.result.connect(self.on_result)
def on_result(self, msg):
print(msg)
def start_task(self):
self.thread.start()
from PyQt5.QtCore import QRunnable, QThreadPool, pyqtSignal, QObject
class Task(QRunnable):
def __init__(self):
super().__init__()
self.signals = QObject()
self.result = pyqtSignal(str)
def run(self):
time.sleep(2)
self.result.emit("快速任务完成")
# 使用
pool = QThreadPool.globalInstance()
task = Task()
task.result.connect(lambda x: print(x))
pool.start(task)
典型应用:下载管理器中,每个下载任务运行在独立线程,进度通过信号实时更新进度条。
PyQt5通过 QtSql 模块提供数据库支持,支持 SQLite/MySQL/PostgreSQL/Oracle 等主流数据库。
from PyQt5.QtSql import QSqlDatabase, QSqlQuery
db = QSqlDatabase.addDatabase("QSQLITE")
db.setDatabaseName("app_data.db")
if db.open():
query = QSqlQuery()
query.exec_("""CREATE TABLE IF NOT EXISTS users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
email TEXT UNIQUE
)""")
query.prepare("INSERT INTO users (name, email) VALUES (?, ?)")
query.addBindValue("张三")
query.addBindValue("zhangsan@example.com")
query.exec_()
query.exec_("SELECT * FROM users")
while query.next():
print(query.value(1), query.value(2))
else:
print("数据库打开失败:", db.lastError().text())
需安装驱动:pip install PyQt5-sql 并确保系统有 MySQL 驱动。
db = QSqlDatabase.addDatabase("QMYSQL")
db.setHostName("localhost")
db.setDatabaseName("testdb")
db.setUserName("root")
db.setPassword("123456")
if not db.open():
raise Exception("连接失败:", db.lastError().text())
model = QSqlTableModel()
model.setTable("users")
model.select()
view = QTableView()
view.setModel(model)
view.setWindowTitle("用户列表")
db.transaction()
try:
query.exec_("INSERT INTO orders VALUES (101, '笔记本')")
query.exec_("UPDATE products SET stock=stock-1 WHERE id=1")
db.commit()
except:
db.rollback()
raise
生产建议:对复杂业务使用 SQLAlchemy + PyQt5,通过 ORM 管理数据库操作,提升可维护性。
将PyQt5应用打包为独立可执行文件,需解决以下问题:
安装:pip install pyinstaller
基础命令:pyinstaller --onefile --windowed main.py
关键参数:
| 参数 | 说明 |
|---|---|
--onefile |
打包为单个EXE |
--windowed |
无控制台窗口(GUI应用必需) |
--add-data "res;res" |
添加资源目录(Windows用`;`,Linux/macOS用`:`) |
--icon=app.ico |
设置图标 |
示例命令(Windows):
pyinstaller --onefile --windowed \
--add-data "res;res" \
--icon=app.ico \
--name="MyApp" \
main.py
import os, sys
os.environ['QT_QPA_PLATFORM_PLUGIN_PATH'] = os.path.join(sys._MEIPASS, 'plugins', 'platforms')
--onefile --noconsole --clean 清理缓存macOS:生成 .app 包后,可进一步打包为 .dmg 安装包(需 Codesign 签名)
Linux:推荐打包为 AppImage(便携式),使用 linuxdeployqt 工具:
linuxdeployqt MyApp.app -appimage
集成 QNetworkAccessManager 实现版本检查与静默更新:
def check_update(self):
url = "https://www.xservx.com/version.json"
reply = self.nam.get(QNetworkRequest(QUrl(url)))
reply.finished.connect(self.handle_version)
功能描述:实时监控服务器指标(CPU/内存/网络),每5秒刷新数据,支持历史趋势图与阈值告警。
技术栈:
关键代码片段:
def update_chart(self):
cpu = psutil.cpu_percent()
memory = psutil.virtual_memory().percent
self.cpu_series.append(QPointF(self.count, cpu))
self.mem_series.append(QPointF(self.count, memory))
self.count += 1
# 阈值告警
if cpu > 80:
QSound.play("alert.wav")
效果亮点:
功能描述:控制光谱仪采集数据,支持参数配置、实时波形显示、结果导出。
技术栈:
关键设计:
用户反馈:
“相比原LabVIEW方案,PyQt5界面更轻量,启动快3倍,且完全兼容Python数据分析生态!”
功能描述:支持同时打开多个文档,每个文档独立编辑,支持撤销/重做、查找替换、拼写检查。
技术栈:
核心逻辑:
def new_file(self):
editor = QTextEdit()
sub_window = self.mdi_area.addSubWindow(editor)
sub_window.setWindowTitle(f"文档 {self.doc_count+1}")
self.doc_count += 1
sub_window.show()
# 撤销/重做
undo_action = QAction("撤销", self)
undo_action.triggered.connect(self.undo_stack.undo)
扩展功能:
原因:Qt未启用高DPI缩放。PyQt5默认支持,但需在代码开头添加:
QApplication.setAttribute(Qt.AA_EnableHighDpiScaling)
QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps)
补充:确保图标资源使用 SVG 格式(矢量无损缩放)。
方案:
# 全局设置
table.setWordWrap(True)
table.resizeColumnsToContents()
# 或对特定列设置
table.setColumnWidth(1, 200)
table.item(row, col).setTextAlignment(Qt.AlignTop | Qt.AlignLeft)
高级技巧:重写 QStyledItemDelegate 的 paint() 方法,自定义换行逻辑。
黄金法则:所有UI操作必须在主线程执行!使用信号槽传递数据:
# 错误做法(跨线程直接调用UI)
# self.label.setText("更新") # ❌ 可能崩溃
# 正确做法
self.updateSignal.emit("更新")
# 主线程连接槽
self.updateSignal.connect(lambda text: self.label.setText(text))
解决方案:
--add-data 添加 Qt 插件目录import os, sys
if hasattr(sys, 'frozen'):
os.environ['PATH'] = sys._MEIPASS + os.pathsep + os.environ.get('PATH', '')
pyinstaller --debug all 查看详细错误实现步骤:
from PyQt5.QtWidgets import QSplashScreen
from PyQt5.QtGui import QPixmap
# 启动时显示
splash = QSplashScreen(QPixmap("splash.png"))
splash.show()
app.processEvents() # 允许事件处理
# 主窗口初始化
window = MainWindow()
window.show()
# 隐藏欢迎界面
splash.finish(window)
进阶:在 splash.show() 和 finish() 之间显示加载进度。