Qt for Python：PySide6 入门指南（上篇）
本文详细介绍 Qt Widgets 开发。
一、基础示例
import sysfrom PySide6.QtWidgets import QApplication, QLabelapp = QApplication(sys.argv)label = QLabel("Hello World!")label.show()app.exec()
运行效果：
对于使用 PySide6 的 Widget 应用程序，我们必须先从 PySide6.QtWidgets 模块中导入相应的类，导入完成后，需要创建一个 QApplication 实例。
由于 Qt 可以接收来自命令行的参数，我们可以将任何参数传递给 QApplication 对象，但通常不需要传递任何参数，因此可以保持默认，或者使用以下方法：
在创建 QApplication 对象之后，我们创建了一个 QLabel 对象，QLabel 是一个可以显示文本（简单文本或富文本，如 HTML）或者图像的控件：
# This HTML approach will be valid too!label = QLabel("<font color=red size=40>Hello World!</font>")
创建 QLabel 对象之后，调用了它的 show() 方法。
最后，我们调用 app.exec() 进入 Qt 主循环并开始执行 Qt 代码。
二、使用 .ui 文件
在 python 代码中使用 pyside6-designer 设计好的 .ui 文件：
1、生成 python 类
与 UI 文件交互的标准方式是从中生成一个 Python 类，这得益于 pyside6-uic 工具，在控制台上运行以下命令：
pyside6-uic mainwindow.ui -o ui_mainwindow.py
导入生成的文件ui_mainwindow.py：
from ui_mainwindow import Ui_MainWindow
示例代码如下：
import sysfrom PySide6.QtWidgets import QApplication, QMainWindowfrom PySide6.QtCore import QFilefrom ui_mainwindow import Ui_MainWindowclass MainWindow(QMainWindow): def __init__(self): super(MainWindow, self).__init__() self.ui = Ui_MainWindow() self.ui.setupUi(self)if __name__ == "__main__": app = QApplication(sys.argv) window = MainWindow() window.show() sys.exit(app.exec())
运行效果：
新的基本类 MainWindow 只包含两行新代码，用于从 UI 文件中加载生成的 Python 类：
self.ui = Ui_MainWindow()self.ui.setupUi(self)
2、直接加载
要直接加载 UI 文件，我们需要从 QtUiTools 模块引入一个类：
from PySide6.QtUiTools import QUiLoader
QUiLoader 让我们可以动态加载 .ui 文件并立即使用它：
ui_file = QFile("mainwindow.ui")ui_file.open(QFile.ReadOnly)loader = QUiLoader()window = loader.load(ui_file)window.show()
示例代码如下：
# File: main.pyimport sysfrom PySide6.QtUiTools import QUiLoaderfrom PySide6.QtWidgets import QApplicationfrom PySide6.QtCore import QFile, QIODeviceif __name__ == "__main__": app = QApplication(sys.argv) ui_file_name = "mainwindow.ui" ui_file = QFile(ui_file_name) if not ui_file.open(QIODevice.ReadOnly): print(f"Cannot open {ui_file_name}: {ui_file.errorString()}") sys.exit(-1) loader = QUiLoader() window = loader.load(ui_file) ui_file.close() if not window: print(loader.errorString()) sys.exit(-1) window.show() sys.exit(app.exec())
运行效果：
三、控件样式
1、setStyleSheet 方法
Qt Widgets 会根据不同的操作系统使用默认主题。然而，我们也可以为每个控件自定义样式，例如：
import sysfrom PySide6.QtCore import Qtfrom PySide6.QtWidgets import QApplication, QLabelif __name__ == "__main__": app = QApplication() w = QLabel("This is a placeholder text") w.setAlignment(Qt.AlignCenter) w.show() sys.exit(app.exec())
执行这段代码后，我们会看到一个简单的 QLabel 位于中心，并带有占位文本：
我们可以使用类似 CSS 的语法来为它设置样式，例如 background-color 和 font-family：
import sysfrom PySide6.QtCore import Qtfrom PySide6.QtWidgets import QApplication, QLabelif __name__ == "__main__": app = QApplication() w = QLabel("This is a placeholder text") w.setAlignment(Qt.AlignCenter) w.setStyleSheet(""" background-color: #262626; color: #FFFFFF; font-family: Titillium; font-size: 18px; """) w.show() sys.exit(app.exec())
2、QSS 文件
更简单的替代方法是使用 Qt 样式表，它是一个或多个 .qss 文件，用于定义 UI 元素的样式。qss 文件与 CSS 文件非常相似，但我们需要指定 Widget 控件，并可选择性地指定对象的名称：
QLabel { background-color: red;}QLabel#title { font-size: 20px;}
以上代码中，第一个样式为所有 QLabel 对象定义了背景颜色，而后一个样式仅为标题对象设置样式。
定义好样式文件后，使用 QApplication.setStyleSheet(str) 函数来应用它：
if __name__ == "__main__": app = QApplication() w = Widget() w.show() with open("style.qss", "r") as f: _style = f.read() app.setStyleSheet(_style) sys.exit(app.exec())
拥有一个通用的 qss 文件可以将代码的样式部分解耦，而不必将其混杂在整体功能中，并且我们可以轻松地启用或禁用它。
来看这个新的示例，包含更多的控件：
class Widget(QWidget): def __init__(self, parent=None): super(Widget, self).__init__(parent) menu_widget = QListWidget() for i in range(10): item = QListWidgetItem(f"Item {i}") item.setTextAlignment(Qt.AlignCenter) menu_widget.addItem(item) text_widget = QLabel(_placeholder) button = QPushButton("Something") content_layout = QVBoxLayout() content_layout.addWidget(text_widget) content_layout.addWidget(button) main_widget = QWidget() main_widget.setLayout(content_layout) layout = QHBoxLayout() layout.addWidget(menu_widget, 1) layout.addWidget(main_widget, 4) self.setLayout(layout)
这显示了一个两栏的控件，左边是一个 QListWidget，右边是一个 QLabel 和一个 QPushButton，代码运行效果如下：
向 style.qss 文件添加内容就可以修改它的外观效果：
QListWidget { color: #FFFFFF; background-color: #33373B;}QListWidget::item { height: 50px;}QListWidget::item:selected { background-color: #2ABf9E;}QLabel { background-color: #FFFFFF; qproperty-alignment: AlignCenter;}QPushButton { background-color: #2ABf9E; padding: 20px; font-size: 18px;}
四、信号与槽
1、示例
信号和槽是 Qt 的一个功能，允许图形控件与其他图形控件或 Python 代码进行通信。接下来我们创建一个 Qt 应用，它有一个按钮控件，每次点击它时，会将设定好的消息记录到 Python 控制台。
首先导入必要的 PySide6 类和 Python 的 sys 模块：
import sysfrom PySide6.QtWidgets import QApplication, QPushButtonfrom PySide6.QtCore import Slot
创建一个将消息记录到控制台的 Python 函数：
# Greetings@Slot()def say_hello(): print("Button clicked, Hello!")
现在，如前面的例子所示，我们必须创建 QApplication 来运行 PySide6 代码：
# Create the Qt Applicationapp = QApplication(sys.argv)
创建一个可点击的按钮，它是一个 QPushButton 实例：
# Create a buttonbutton = QPushButton("Click me")
在显示按钮之前，我们必须将其连接到之前定义的 say_hello() 函数。有两种方法可以做到这一点：使用老式方法或更符合 Python 风格的新方法，在这里，我们使用新方法。
QPushButton 有一个预定义的信号叫做 clicked，每次按钮被点击时都会触发，我们把这个信号连接到 say_hello() 函数：
# Connect the button to the functionbutton.clicked.connect(say_hello)
最后，我们显示按钮并启动 Qt 主循环：
# Show the buttonbutton.show()# Run the main Qt loopapp.exec()
运行效果：
完整代码如下：
import sysfrom PySide6.QtWidgets import QApplication, QPushButtonfrom PySide6.QtCore import Slot# Greetings@Slot()def say_hello(): print("Button clicked, Hello!")# Create the Qt Applicationapp = QApplication(sys.argv)# Create a buttonbutton = QPushButton("Click me")# Connect the button to the functionbutton.clicked.connect(say_hello)# Show the buttonbutton.show()# Run the main Qt loopapp.exec()
2、通信机制
由于 Qt 的特性，QObjects 需要一种通信方式，这就是该机制成为 Qt 核心功能的原因。
可以把信号和槽理解为我们与家里灯光的互动方式：当我们控制灯的开关（信号）时，得到的结果可能是灯泡被打开或关闭（槽）。
在开发界面时，我们可以通过点击按钮的效果得到一个实际的例子：点击是信号，而槽则是按钮被点击时发生的操作，比如关闭窗口、保存文档等。
所有继承自 QObject 或其子类（如 QWidget）的类都可以包含信号和槽。一个对象在它状态发生变化时会发出信号，该变化可能对其他对象有意义的，它并不关心或知道是否有任何对象接收了它发出的信号。
槽可以用于接收信号，但它们也是普通的成员函数，就像一个对象不知道是否有接收它的信号的其他对象一样，槽也不知道是否有信号与它连接。
我们可以将任意数量的信号连接到一个槽上，同时一个信号也可以连接到多个槽上，甚至可以将一个信号直接连接到另一个信号。（这将使第二个信号在第一个信号发出时立即被触发。）
Qt 的控件有许多预定义的信号和槽，例如，QAbstractButton（Qt 中按钮的基类）有一个 clicked() 信号，QLineEdit（单行输入框）有一个名为 clear() 的槽。因此，可以通过在 QLineEdit 右侧放置一个 QToolButton，并将其 clicked() 信号连接到 clear() 槽来实现带有清除按钮的文本输入框，这是通过信号的 connect() 方法完成的：
button = QToolButton()line_edit = QLineEdit()button.clicked.connect(line_edit.clear)
connect() 返回一个 Connection 对象，可以使用 disconnect() 方法来断开连接。
除了连接到槽，信号也可以连接到自由函数：
import sysfrom PySide6.QtWidgets import QApplication, QPushButtondef function(): print("The 'function' has been called!")app = QApplication()button = QPushButton("Call function")button.clicked.connect(function)button.show()sys.exit(app.exec())
connect() 函数接受一个可选的 ConnectionType 参数，该参数指定与线程和事件循环相关的行为。
连接可以通过代码明确指定，或者对于控件表单，在 Qt Widgets Designer 的信号槽编辑器中设计。
3、Signal 类
在 Python 中编写类时，信号被声明为 Signal 类的类级变量。一个基于 QWidget 的按钮发出 clicked() 信号的示例如下所示：
from PySide6.QtCore import Qt, Signalfrom PySide6.QtWidgets import QWidgetclass Button(QWidget): clicked = Signal(Qt.MouseButton) ... def mousePressEvent(self, event): self.clicked.emit(event.button())
Signal 的构造函数接受一个由 Python 类型和 C 类型组成的元组或列表：
signal1 = Signal(int) # Python typessignal2 = Signal(QUrl) # Qt Typessignal3 = Signal(int, str, int) # more than one typesignal4 = Signal((float,), (QDate,)) # optional types
除此之外，它还可以接收一个名为 name 的命名参数来定义信号名称，如果未传入任何值，新信号将与分配给它的变量同名：
# TODOsignal5 = Signal(int, name='rangeChanged')# ...rangeChanged.emit(...)
Signal 的另一个有用选项是 arguments name，对于 QML 应用程序来说，可以通过名称引用发出的值，这非常有用：
# TODOsumResult = Signal(int, arguments=['sum'])# ...Connections { target: ... function onSumResult(sum) { // do something with 'sum' }
4、Slot 类
QObject 派生类中的槽应该使用装饰器 @Slot 来标注，同样，要定义一个签名，只需像 Signal 类一样传递类型即可。
@Slot(str)def slot_function(self, s): ...
Slot() 也接受 name 和 result 关键字。result 关键字定义将返回的类型，可以是 C 类型或 Python 类型。name 关键字的行为与 Signal() 中的相同。如果 name 没有传值，则新槽的名称将与被装饰的函数名称相同。
建议对所有通过信号连接使用的方法添加 @Slot 装饰器。不添加会导致运行时开销，因为在创建连接时，该方法会被添加到 QMetaObject 中。这对于使用 QML 注册的 QObject 类尤其重要，缺少装饰器可能会引入 bug。
可以通过设置日志类别 qt.pyside.libpyside 的激活警告来诊断缺失的装饰器。例如，可以通过设置环境变量来实现：
export QT_LOGGING_RULES="qt.pyside.libpyside.warning=true"
5、线程相关
在多线程应用程序中，信号可能由属于不同于接收者的线程的发送者发出。对于非 Slot 类型的接收者，代码将在发送者的线程上下文中执行。
然而，对于使用 @Slot 装饰的 QObject 派生类的方法，这通常有所不同，因为它们与特定线程相关，这取决于 connect() 方法的最后一个参数，该参数的类型为 PySide6.QtCore.Qt.ConnectionType。
当传入 Qt.ConnectionType.AutoConnection（默认值）或 Qt.ConnectionType.QueuedConnection 时，接收者代码将在接收者对象的线程上下文中执行，这对于将后台线程的结果传递到需要使用主线程的 GUI 类非常有用。
6、重载信号和槽
实际上，可以使用相同名称的信号和槽，但参数类型列表不同，这是 Qt 5 的遗留特性，不推荐在新代码中使用。在 Qt 6 中，不同类型的信号具有不同的名称。
下面的示例使用两个处理程序来展示信号和槽的不同功能：
import sysfrom PySide6.QtWidgets import QApplication, QPushButtonfrom PySide6.QtCore import QObject, Signal, Slotclass Communicate(QObject): # create two new signals on the fly: one will handle # int type, the other will handle strings speak = Signal((int,), (str,)) def __init__(self, parent=None): super().__init__(parent) self.speak[int].connect(self.say_something) self.speak[str].connect(self.say_something) # define a new slot that receives a C 'int' or a 'str' # and has 'say_something' as its name @Slot(int) @Slot(str) def say_something(self, arg): if isinstance(arg, int): print("This is a number:", arg) elif isinstance(arg, str): print("This is a string:", arg)if __name__ == "__main__": app = QApplication(sys.argv) someone = Communicate() # emit 'speak' signal with different arguments. # we have to specify the str as int is the default someone.speak.emit(10) someone.speak[str].emit("Hello everybody!")
运行效果：
This is a number: 10This is a string: Hello everybody!
7、指定信号和槽
信号和槽也可以通过 SIGNAL() 和/或 SLOT() 函数传递的 C++ 方法签名字符串来指定：
from PySide6.QtCore import SIGNAL, SLOTbutton.connect(SIGNAL("clicked(Qt::MouseButton)"), action_handler, SLOT("action1(Qt::MouseButton)"))
通常不推荐这么做，仅在少数情况下需要，例如信号只能通过 QMetaObject 访问时（QAxObject、QAxWidget、QDBusInterface 或 QWizardPage::registerField()）。
wizard.registerField("text", line_edit, "text", SIGNAL("textChanged(QString)"))
在检查 QMetaObject 时，可以通过查询 QMetaMethod.methodSignature() 找到签名字符串：
mo = widget.metaObject()for m in range(mo.methodOffset(), mo.methodCount()): print(mo.method(m).methodSignature())
注意，槽应使用 @Slot 进行装饰。
参考资料
- https://doc.qt.io/qtforpython-6/tutorials/index.html
- https://doc.qt.io/qt-5/stylesheet-reference.html
10个月宝宝每天需要喝多少奶粉？
