PyQt5 综合教程：构建专业级 Python GUI 应用

什么是 PyQt？

PyQt 是 Qt 框架的 Python 绑定，Qt 是跨平台 C++ 库，用于在 Windows、macOS、Linux、Android、iOS、树莓派等创建原生 GUI 应用。绑定由 Riverbank Computing (英国) 维护，Qt 本身由 The Qt Company (芬兰) 开发。PyQt 让 Python 开发者访问 Qt 丰富的控件、网络、数据库、3D、多媒体能力。

本教程你将学习：

• PyQt5 核心特性
• 可用 PyQt 版本
• Windows、macOS、Linux 安装 PyQt5
• PyQt 基础概念与示例程序
• 核心组件与控件
• 布局策略与主题定制

PyQt5 核心特性

PyQt5 暴露 600 多个类，覆盖：

• 图形用户界面
• SQL 数据库集成 (SQLite、MySQL、PostgreSQL、Oracle、ODBC)
• QtWebEngine Web 渲染
• XML 解析与操作
• 健壮网络 (TCP/UDP、SSL、DNS)
• 多媒体与 3D 图形 (QtMultimedia、Qt3D)

这些能力使开发者能构建复杂、高性能的桌面和嵌入式应用。LG、梅赛德斯-奔驰、AMD、松下、Harman 等大企业依赖 Qt 构建 UI 技术栈。

PyQt 版本

Riverbank Computing 提供两个主要绑定：

• PyQt4 —— 支持 Qt 4.x 和 Qt 5.x 模块（不向后兼容）
• PyQt5 —— 专为 Qt 5.x 绑定

此外，PyQt3D 提供 Qt3D 框架的 Python 绑定，适用于实时 3D 渲染和仿真。

安装 PyQt5

介绍两种常用安装方式。推荐使用 wheel 包，因其包含编译好的 C++ 二进制文件，避免漫长构建过程。

方法 1：通过 Wheel 安装（推荐）

1. 打开终端或命令提示符。
2. 运行 pip install PyQt5 下载 wheel（约 50 MB）。
3. 验证安装成功完成。

Windows 示例：

pip install PyQt5

安装后即可导入 PyQt5.QtWidgets 开始构建应用。

方法 2：从源码构建

源码构建更复杂，需编译 C++ 代码。仅在需要自定义修改或平台无 wheel 时使用。

PyQt5 编程基础

下面最小示例打开 300×300 窗口，标题 “Guru99”。每行附注释：

import sys
from PyQt5.QtWidgets import QApplication, QWidget
if __name__ == "__main__":
    app = QApplication(sys.argv)
    w = QWidget()
    w.resize(300, 300)
    w.setWindowTitle("Guru99")
    w.show()
    sys.exit(app.exec_())

解释：

• QApplication —— 核心事件循环。
• QWidget —— 所有 UI 组件基类。
• resize() —— 设置窗口尺寸。
• setWindowTitle() —— 定义标题栏文本。
• show() —— 显示控件。
• app.exec_() —— 启动事件循环，阻塞直到窗口关闭。

添加交互

下例添加标签、按钮、点击弹出消息框，演示信号与槽——Qt 事件系统核心。

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QLabel, QPushButton, QMessageBox
def dialog():
    mbox = QMessageBox()
    mbox.setText("Your allegiance has been noted")
    mbox.setDetailedText("You are now a disciple and subject of the all‑knowing Guru")
    mbox.setStandardButtons(QMessageBox.Ok | QMessageBox.Cancel)
    mbox.exec_()
if __name__ == "__main__":
    app = QApplication(sys.argv)
    w = QWidget()
    w.resize(300, 300)
    w.setWindowTitle("Guru99")
    label = QLabel("Behold the Guru, Guru99", w)
    label.move(100, 130)
    btn = QPushButton("Beheld", w)
    btn.move(110, 150)
    btn.clicked.connect(dialog)
    w.show()
    sys.exit(app.exec_())

点击按钮触发 dialog()，创建模态 QMessageBox。

核心组件与控件

PyQt5 架构组织为多个模块，理解层级有助于按需导入。

模块概览

• Qt —— 聚合所有子模块，适合小脚本。
• QtCore —— 核心非 GUI 类（信号、槽、定时器）。
• QtWidgets —— 标准 GUI 控件（按钮、标签等）。
• QtGui —— 图形基元与高级绘图。
• QtNetwork —— TCP/UDP 套接字、SSL、DNS。
• QtMultimedia —— 音视频支持。
• QtSql —— 数据库集成。

常用控件

• QLineEdit —— 单行文本输入。
• QRadioButton —— 单选按钮。
• QComboBox —— 下拉选择器。
• QCheckBox —— 复选框。
• QMenuBar —— 水平菜单栏。
• QToolBar —— 工具栏按钮。
• QTabWidget —— 标签页界面。
• QScrollBar —— 滚动条控件。
• QSplitter —— 可调整分割视图。
• QDockWidget —— 可分离停靠面板。

布局管理

不手动用 move() 和 resize() 定位，Qt 提供布局管理器根据窗口大小自动排列控件。

盒布局 (HBox & VBox)

QHBoxLayout 水平排列；QVBoxLayout 垂直排列。

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QPushButton, QHBoxLayout, QVBoxLayout
app = QApplication([])
win = QWidget()
win.setWindowTitle("Musketeers")
btn1 = QPushButton("Athos")
btn2 = QPushButton("Porthos")
btn3 = QPushButton("Aramis")
hbox = QHBoxLayout(win)
hbox.addWidget(btn1)
hbox.addWidget(btn2)
hbox.addWidget(btn3)
win.show()
app.exec_()

将 QHBoxLayout 替换为 QVBoxLayout 即垂直堆叠按钮。

网格布局

二维网格排列控件。addWidget() 接受行列索引及可选跨行跨列参数。

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QPushButton, QGridLayout
app = QApplication([])
win = QWidget()
layout = QGridLayout(win)
for i in range(3):
    for j in range(3):
        layout.addWidget(QPushButton(f"Button {i},{j}"), i, j)
win.show()
app.exec_()

自定义主题与样式

PyQt5 支持原生主题和自定义样式表。

内置主题

用 app.setStyle("Fusion") 或其他可用样式设置应用风格。

app = QApplication([])
app.setStyle("Fusion")

调色板定制

用 QPalette 程序化修改控件颜色。

from PyQt5.QtGui import QPalette
from PyQt5.QtCore import Qt
palette = QPalette()
palette.setColor(QPalette.ButtonText, Qt.black)
palette.setColor(QPalette.Window, Qt.black)
palette.setColor(QPalette.Button, Qt.gray)
app.setPalette(palette)

Qt 样式表 (CSS-like)

高级样式直接应用样式表到控件或整个应用。

btn.setStyleSheet("background-color: #4CAF50; color: white; padding: 5px;")

核心要点

• PyQt5 是强大的 Qt Python 绑定，适合跨平台桌面、嵌入式、移动应用。
• 推荐通过 wheel 安装；源码构建可选。
• 核心模块：QtCore、QtGui、QtWidgets、QtNetwork、QtMultimedia、QtSql。
• 控件涵盖按钮、标签、文本框、单选、复选、菜单、工具栏、标签页、分割器、停靠面板。
• 交互依赖 Qt 信号槽机制。
• 布局——盒布局和网格布局——自动化控件放置，提升响应式能力。
• 主题可通过内置样式、调色板、Qt 样式表实现。
• Qt Designer 和 Qt Creator 简化 UI 设计和应用打包。