PyQt5 入门教程：基础与常用控件详解

1. 初识 PyQt5 和安装

1.1 什么是 PyQt5？

PyQt5 是 Python 的图形用户界面 (GUI) 框架，基于强大的 Qt C++ 库。通过它，我们可以用 Python 轻松构建跨平台的桌面应用程序，支持 Windows、macOS 和 Linux。

1.2 在 PyCharm 中安装 PyQt5

1. 打开 PyCharm：确保已创建或打开一个项目。
2. 安装 PyQt5：
   • 方法 1（设置）：点击 File -> Settings，选择 Project -> Python Interpreter，点击右侧 + 号搜索 PyQt5 并安装。
   • 方法 2（终端）：打开底部 Terminal，运行命令：

   pip install PyQt5
   

3. 验证安装：在终端输入 pip list 查看是否包含 PyQt5。

1.3 编写第一个 PyQt5 应用程序

创建一个简单的窗口显示 "Hello, World!"。

1. 新建文件：右键项目文件夹，选择 New -> Python File，命名为 main.py。
2. 编写代码：

import sys
from PyQt5.QtWidgets import QApplication, QLabel, QMainWindow

# 定义主窗口类，继承自 QMainWindow
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("PyQt5 第一个窗口")
        
        # 创建标签控件
        label = QLabel("Hello, World!", self)
        self.setCentralWidget(label)

# 创建应用程序对象
app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

1.4 代码详细解释

• import sys：用于处理命令行参数及退出程序。
• QApplication：每个 PyQt5 程序必须有一个实例，管理应用生命周期和事件循环。
• QMainWindow：主窗口基类，可包含菜单栏、工具栏等。
• QLabel：用于显示文本或图片的基础控件。
• setCentralWidget()：设置中央控件，填充窗口中间区域。
• sys.exit(app.exec_())：启动事件循环，保持程序运行直到关闭。

1.5 常见问题排查

• 未安装：检查 pip list 确认 PyQt5 存在。
• 解释器错误：确保 PyCharm 使用的 Python 版本与安装环境一致。
• 窗口不显示：确认调用了 window.show()。

2. 创建 PyQt5 应用程序与布局管理

2.1 基本窗口结构

窗口是 GUI 的核心。除了基础窗口，我们还需要学习如何组织多个控件，使界面更具交互性。

2.2 QWidget 与 QMainWindow 的区别

• QWidget：所有控件的基类，最基础的窗口控件。
• QMainWindow：高级窗口控件，继承自 QWidget，支持菜单栏、状态栏等功能。

2.3 布局管理器

布局管理器自动调整控件位置和大小，常见类型包括：

1. QVBoxLayout：垂直排列（从上到下）。
2. QHBoxLayout：水平排列（从左到右）。
3. QGridLayout：网格排列。
4. QFormLayout：表单排列。

2.4 使用布局管理器示例

以下代码演示了如何在窗口中组合垂直和水平布局：

import sys
from PyQt5.QtWidgets import QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout, QPushButton, QLabel

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("PyQt5 布局示例")
        
        # 设置中央控件
        central_widget = QWidget(self)
        self.setCentralWidget(central_widget)
        
        # 垂直布局
        vbox_layout = QVBoxLayout()
        label = QLabel("这是一个标签")
        vbox_layout.addWidget(label)
        
        # 水平布局
        hbox_layout = QHBoxLayout()
        button1 = QPushButton("按钮 1")
        button2 = QPushButton("按钮 2")
        hbox_layout.addWidget(button1)
        hbox_layout.addWidget(button2)
        
        # 嵌套布局
        vbox_layout.addLayout(hbox_layout)
        central_widget.setLayout(vbox_layout)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

说明：

• QMainWindow 需要设置中央控件 (QWidget)。
• 先添加标签到垂直布局，再将水平布局添加到垂直布局中，实现灵活排版。

2.5 QGridLayout 网格布局

适合表单或矩阵式布局，指定行和列放置控件。

from PyQt5.QtWidgets import QApplication, QWidget, QGridLayout, QLabel, QPushButton
import sys

class MainWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QGridLayout 示例")
        layout = QGridLayout()
        
        # 添加控件到特定行列
        layout.addWidget(QLabel("标签 1"), 0, 0)
        layout.addWidget(QPushButton("按钮 1"), 0, 1)
        layout.addWidget(QLabel("标签 2"), 1, 0)
        layout.addWidget(QPushButton("按钮 2"), 1, 1)
        
        self.setLayout(layout)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

3. 常用控件详解

3.1 QLabel（标签）

用于显示静态文本或图片。

from PyQt5.QtWidgets import QApplication, QLabel, QMainWindow
from PyQt5.QtCore import Qt
import sys

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QLabel 示例")
        label = QLabel("这是一个标签", self)
        label.setAlignment(Qt.AlignCenter)  # 居中对齐
        self.setCentralWidget(label)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

3.2 QPushButton（按钮）

触发事件的常用控件。

from PyQt5.QtWidgets import QApplication, QMainWindow, QPushButton
import sys

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QPushButton 示例")
        button = QPushButton("点击我", self)
        button.clicked.connect(self.button_clicked)  # 连接信号
        self.setCentralWidget(button)

    def button_clicked(self):
        print("按钮被点击！")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

3.3 QLineEdit（单行文本框）

用于输入文本。

from PyQt5.QtWidgets import QApplication, QMainWindow, QLineEdit
import sys

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QLineEdit 示例")
        self.line_edit = QLineEdit(self)
        self.line_edit.setPlaceholderText("请输入文本")
        self.setCentralWidget(self.line_edit)
        
        # 回车键触发
        self.line_edit.returnPressed.connect(self.return_pressed)

    def return_pressed(self):
        text = self.line_edit.text()
        print(f"用户输入：{text}")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

3.4 QCheckBox（复选框）

用于勾选选项。

from PyQt5.QtWidgets import QApplication, QMainWindow, QCheckBox
from PyQt5.QtCore import Qt
import sys

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QCheckBox 示例")
        self.checkbox = QCheckBox("同意条款", self)
        self.checkbox.stateChanged.connect(self.checkbox_changed)
        self.setCentralWidget(self.checkbox)

    def checkbox_changed(self, state):
        if state == Qt.Checked:
            print("复选框被勾选")
        else:
            print("复选框未被勾选")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

3.5 QComboBox（下拉列表）

用于从选项中选择。

from PyQt5.QtWidgets import QApplication, QMainWindow, QComboBox
import sys

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QComboBox 示例")
        self.combobox = QComboBox(self)
        self.combobox.addItems(["选项 1", "选项 2", "选项 3"])
        self.combobox.currentIndexChanged.connect(self.combobox_changed)
        self.setCentralWidget(self.combobox)

    def combobox_changed(self, index):
        text = self.combobox.currentText()
        print(f"当前选中：{text}")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

总结

本教程涵盖了 PyQt5 的安装、基础窗口结构、布局管理以及常用控件的使用。掌握了这些内容，你就具备了开发跨平台桌面应用的基础能力。后续可以深入学习信号槽机制、自定义样式及复杂业务逻辑的实现。