1. 环境搭建与第一个混合程序

任务目标

本案例完成两项工作：一是配置Python与Qt混合开发所需的环境依赖；二是创建一个最小可运行的混合程序——在Qt窗口中显示文本“Hello Qt+Python”，并验证程序能够正常启动与退出。

环境依赖与安装

本案例基于 Python 3.9+ 与 PySide6（Qt官方Python绑定）。安装命令如下：

pip install PySide6

安装完成后，可通过以下命令验证环境是否就绪：

python -c "from PySide6.QtWidgets import QApplication; print('PySide6 OK')"

若输出 PySide6 OK，说明Qt库已正确安装并可被Python调用。

完整实现代码

创建文件 hello_qt.py，内容如下：

import sys
from PySide6.QtWidgets import QApplication, QLabel, QVBoxLayout, QWidget

def main():
    # 创建QApplication实例（每个Qt程序必须有且仅有一个）
    app = QApplication(sys.argv)

    # 创建主窗口部件
    window = QWidget()
    window.setWindowTitle("Qt + Python 混合编程")

    # 创建并配置标签
    label = QLabel("Hello Qt+Python")
    label.setAlignment(Qt.AlignmentFlag.AlignCenter)

    # 将标签放入垂直布局并设置到窗口
    layout = QVBoxLayout()
    layout.addWidget(label)
    window.setLayout(layout)

    # 显示窗口
    window.resize(400, 200)
    window.show()

    # 进入事件循环，等待用户关闭窗口
    sys.exit(app.exec())

if __name__ == "__main__":
    main()

注意：代码中使用了 Qt.AlignmentFlag.AlignCenter，因此需要在文件顶部补充导入 from PySide6.QtCore import Qt。完整代码如下：

import sys
from PySide6.QtWidgets import QApplication, QLabel, QVBoxLayout, QWidget
from PySide6.QtCore import Qt

def main():
    app = QApplication(sys.argv)

    window = QWidget()
    window.setWindowTitle("Qt + Python 混合编程")

    label = QLabel("Hello Qt+Python")
    label.setAlignment(Qt.AlignmentFlag.AlignCenter)

    layout = QVBoxLayout()
    layout.addWidget(label)
    window.setLayout(layout)

    window.resize(400, 200)
    window.show()

    sys.exit(app.exec())

if __name__ == "__main__":
    main()

运行方式

在终端中执行以下命令启动程序：

python hello_qt.py

验证方法与通过条件

程序启动后，应出现一个标题为“Qt + Python 混合编程”的窗口，窗口中央显示文本“Hello Qt+Python”。通过以下步骤确认程序运行正常：

1. 窗口正常弹出且无报错输出；
2. 窗口标题与标签文本内容与代码设置一致；
3. 点击窗口右上角关闭按钮，程序立即退出，终端无异常堆栈信息。

满足以上三点，即判定环境搭建成功且第一个混合程序运行通过。

常见问题

• ModuleNotFoundError: No module named 'PySide6'：说明未安装PySide6，执行 pip install PySide6 后重试。
• Qt平台插件错误（如xcb缺失）：Linux环境下常见，安装系统依赖 libxcb-cursor0 或使用 QT_QPA_PLATFORM=offscreen 临时测试（仅验证导入，不显示窗口）。
• 窗口一闪而过：检查是否调用了 app.exec()，缺少该调用会导致程序立即退出。