PyQt5入门实战：安装、QtDesigner设计与PyUIC转换完整指南

PyQt5 入门实战安装、QtDesigner 设计与 PyUIC 转换完整指南环境说明Python 3.9 PyQt5 5.15.4 PyCharmCommunity/Professional 均适用一、什么是 PyQt5PyQt5是 Qt5 框架的 Python 绑定由 Riverbank Computing 基于 SIPC 桥接工具封装。它让 Python 开发者可以用纯 Python 代码构建功能完整的跨平台桌面 GUI 应用。1.1 核心特点特点说明跨平台一套代码运行在 Windows / macOS / Linux控件丰富数百种原生控件外观与操作系统一致可视化设计配套 Qt Designer 拖拽设计界面无需手写布局代码信号槽机制独特的事件通信系统松耦合易维护免费开源GPL 协议开源商业用途需购买授权1.2 PyQt5 架构总览架构分三层Python 应用层开发者编写的.py业务逻辑代码PyQt5 绑定层SIP 负责 Python 调用 C Qt 的桥接Qt5 底层C 实现的高性能 UI 引擎二、安装 PyQt52.1 相关包说明安装 PyQt5 时需要关注以下几个包以截图中实际版本为例包名版本作用pyqt55.15.4核心包包含所有 Qt 控件 Python 绑定pyqt5-tools5.15.4.3.2工具包含 Qt Designer 可执行文件pyqt5-qt55.15.2Qt5 运行时 C 动态库pyqt5-sip12.17.1SIP 桥接层Python 调用 C 的核心组件2.2 安装方法方法一PyCharm 图形界面安装推荐新手打开 PyCharm →文件→设置→项目→Python 解释器点击右侧号搜索pyqt5勾选后点击安装软件包同理搜索安装pyqt5-tools方法二pip 命令安装pipinstallpyqt5 pyqt5-tools提示若下载较慢可使用国内镜像加速pipinstallpyqt5 pyqt5-tools-ihttps://pypi.tuna.tsinghua.edu.cn/simple2.3 验证安装importPyQt5print(PyQt5.QtCore.PYQT_VERSION_STR)# 输出 5.15.4 表示安装成功三、在 PyCharm 中配置外部工具安装完成后需要在 PyCharm 中配置QtDesigner和PyUIC两个外部工具后续便可一键启动设计器和转换.ui文件。进入配置入口PyCharm → 文件 → 设置CtrlAltS→ 工具 → 外部工具 → 点击 号3.1 配置 QtDesigner在弹出的编辑工具对话框中填写以下内容字段填写内容名称QtDesigner程序Qt Designer 可执行文件路径实参留空工作目录$FileDir$如何找到 designer.exe 路径在 PyCharm 终端执行python-cimport qt5_applications; import os; print(os.path.dirname(qt5_applications.__file__))找到输出的目录后拼接路径输出目录\Qt\bin\designer.exe完整路径示例根据你的实际虚拟环境路径调整C:\Users\用户名\AppData\Local\Programs\Python\Python39\.venv\Lib\site-packages\qt5_applications\Qt\bin\designer.exe截图中显示的路径末尾为...\site-packages\qt5_applications\Qt\bin\designer.exe这是虚拟环境下的标准位置。配置完成后高级选项中勾选✅ 在执行后同步文件✅ 打开工具输出的控制台3.2 配置 PyUICPyUIC 用于将 Qt Designer 生成的.ui文件转换为 Python 代码.py。字段填写内容名称PyUIC程序当前虚拟环境的python.exe路径实参-m PyQt5.uic.pyuic $FileName$ -o $FileNameWithoutExtension$.py工作目录$FileDir$python.exe 路径示例C:\Users\用户名\AppData\Local\Programs\Python\Python39\.venv\Scripts\python.exe实参说明-m PyQt5.uic.pyuic以模块方式调用 pyuic5$FileName$当前选中的.ui文件名PyCharm 宏变量-o $FileNameWithoutExtension$.py输出为同名.py文件配置完成后效果如截图所示工具 → 外部工具 下会出现QtDesigner和PyUIC两个工具项。四、启动 QtDesigner 设计 UI4.1 启动方式配置完成后在 PyCharm 中工具 → 外部工具 → QtDesigner成功后将弹出如下界面Qt 设计师Qt Designer 界面组成区域说明左侧 Widget Box控件库包含布局/按钮/输入框/列表等数百种控件中央画布设计区域拖拽控件到此处右上 对象查看器显示界面中所有控件的树状结构右中 属性编辑器修改选中控件的属性大小/字体/颜色等右下 资源浏览器管理图片等资源文件上图为成功启动后的 Qt 设计师界面选择Main Window模板即可开始设计主窗口。4.2 基本操作流程启动 QtDesigner选择模板MainWindow / Dialog / Widget从左侧控件库拖拽控件到中央画布在右侧属性编辑器调整控件属性CtrlS保存为.ui文件保存到 PyCharm 项目目录五、PyUIC 转换 .ui 为 .py设计完 UI 后通过 PyUIC 将.ui转换为 Python 代码在 PyCharm 项目中右键点击.ui文件选择外部工具→PyUIC同目录下会自动生成同名.py文件转换后的 .py 文件结构# 由 PyUIC 自动生成不要手动修改fromPyQt5importQtCore,QtGui,QtWidgetsclassUi_MainWindow(object):defsetupUi(self,MainWindow):MainWindow.setObjectName(MainWindow)MainWindow.resize(800,600)# ... 所有控件的创建和布局代码defretranslateUi(self,MainWindow):# 文字内容设置支持国际化MainWindow.setWindowTitle(MainWindow)六、完整开发工作流程安装 PyQt5 pyqt5-tools ↓ 配置 PyCharm 外部工具QtDesigner / PyUIC ↓ 启动 QtDesigner 拖拽设计界面 ↓ 保存为 .ui 文件 ↓ 右键 → PyUIC → 生成同名 .py 文件 ↓ 在主程序中导入 .py绑定信号槽运行程序主程序调用示例importsysfromPyQt5.QtWidgetsimportQApplication,QMainWindowfromui_mainwindowimportUi_MainWindow# 导入 PyUIC 生成的文件classMainWindow(QMainWindow):def__init__(self):super().__init__()self.uiUi_MainWindow()self.ui.setupUi(self)# 在此绑定信号与槽self.ui.pushButton.clicked.connect(self.on_click)defon_click(self):print(按钮被点击)if__name____main__:appQApplication(sys.argv)winMainWindow()win.show()sys.exit(app.exec_())七、常见问题Q1找不到 designer.exe确认已安装pyqt5-tools然后执行pip show pyqt5-tools在Location路径下找qt5_applications\Qt\bin\designer.exe。Q2PyUIC 运行后没有生成 .py 文件确认实参格式正确注意-m PyQt5.uic.pyuic前后有空格确认程序路径指向的是虚拟环境的python.exe不是系统 PythonQ3QtDesigner 打开时报 DLL 错误重新安装pyqt5-qt5pipinstall--force-reinstall pyqt5-qt5Q4生成的 .py 里中文显示乱码在文件头添加# -*- coding: utf-8 -*-并确保 .ui 文件保存时使用 UTF-8 编码。八、总结工具用途关键路径/参数pyqt5核心 Python 绑定库pip install pyqt5pyqt5-tools含 Qt Designerpip install pyqt5-toolsQtDesigner可视化拖拽设计 UI...\qt5_applications\Qt\bin\designer.exePyUIC.ui → .py 自动转换-m PyQt5.uic.pyuic $FileName$ -o $FileNameWithoutExtension$.py核心理念PyQt5 将 UI 设计.ui与业务逻辑.py分离QtDesigner 专注界面Python 专注逻辑是桌面 GUI 开发的高效实践。下一篇预告PyQt5 信号与槽机制详解 —— 从按钮点击到自定义事件彻底理解 Qt 的事件驱动模型。\qt5_applications\Qt\bin\designer.exe| | **PyUIC** | .ui → .py 自动转换 |-m PyQt5.uic.pyuicFileNameFileNameFileName-oFileNameWithoutExtensionFileNameWithoutExtensionFileNameWithoutExtension.py |核心理念PyQt5 将 UI 设计.ui与业务逻辑.py分离QtDesigner 专注界面Python 专注逻辑是桌面 GUI 开发的高效实践。下一篇预告PyQt5 信号与槽机制详解 —— 从按钮点击到自定义事件彻底理解 Qt 的事件驱动模型。