1. 从.ui到.py：为什么会有两种调用方式这回事
刚接触PyQt5那会儿，我最困惑的一件事就是：用Qt Designer拖完控件、保存成.ui文件之后，到底该怎么把它变成能跑的Python程序？网上搜到的答案五花八门，有人说用pyuic5转成.py直接跑，有人说别转、运行时动态加载.ui就行。两种说法都对，但没人讲清楚它们各自适合什么场景，结果我一开始把两种方式混着用，改一次界面就要重新生成一次代码，自定义的逻辑全被覆盖，白干了大半天。
这篇内容就是把这个坑彻底讲透。核心围绕一个具体问题展开：Qt Designer设计出来的界面，转成.py文件之后，到底有哪两种调用方式，各自怎么写、怎么选、怎么避坑。适合已经会用Qt Designer拖界面、但被"生成代码"和"业务逻辑"搅在一起搞得头大的朋友。如果你还在纠结"我该不该用Qt Designer"，那这篇也能帮你判断——它适合快速搭原型、适合界面和逻辑分离，但不适合把复杂交互逻辑塞进设计器里。
先把结论摆前面：所谓"两种调用方式"，本质区别在于界面类是被继承，还是被实例化后组合进主窗口。一种是把生成的Ui_MainWindow类当父类继承下来，另一种是把它当普通类实例化、作为主窗口的一个属性。前者代码紧凑、写起来快，后者结构清晰、适合界面频繁改动。下面我会把两种方式都完整跑一遍，再讲清楚什么时候该用哪个。
在动手之前，先明确一个前提：无论哪种方式，你都得先用pyuic5把.ui转成.py。这个转换命令本身没什么玄机，但有几个参数值得记住：
pyuic5 -o main_window.py main_window.ui如果你用的是较新的PyQt5版本，命令名可能是pyuic5，也可能是python -m PyQt5.uic.pyuic。转换出来的.py文件里，核心就是一个Ui_MainWindow类，它的setupUi方法负责把所有控件挂到窗口上。这个文件是自动生成的，不要手动改，因为下次重新转换会全部覆盖。记住这一点，后面两种调用方式的所有设计，都是为了保护你的业务逻辑不被这个自动生成的文件冲掉。
2. 方式一：继承Ui类，把界面"长"在自己的窗口上
2.1 继承写法的完整代码骨架
第一种方式最直观：把pyuic5生成的Ui_MainWindow直接作为自己主窗口类的父类，然后在__init__里调用setupUi(self)。这样你的类就"是"那个界面，所有控件都成了自己的属性，直接self.pushButton就能访问。
import sys from PyQt5.QtWidgets import QApplication, QMainWindow from main_window import Ui_MainWindow class MyWindow(QMainWindow, Ui_MainWindow): def __init__(self): super().__init__() self.setupUi(self) self.pushButton.clicked.connect(self.on_button_click) def on_button_click(self): self.label.setText("按钮被点击了") if __name__ == "__main__": app = QApplication(sys.argv) window = MyWindow() window.show() sys.exit(app.exec_())这段代码里最关键的一行是super().__init__()。因为MyWindow同时继承了QMainWindow和Ui_MainWindow，而Ui_MainWindow本身是个普通object子类，它的__init__并不初始化Qt窗口。所以必须显式调用QMainWindow的初始化，否则窗口根本显示不出来。这是新手最容易踩的第一个坑——漏掉super().__init__()，程序不报错但窗口一片空白。
2.2 为什么继承方式访问控件这么方便
继承方式最大的好处是控件访问零成本。setupUi(self)执行时，会把所有控件的引用都挂到传入的对象上，也就是self。所以你在任何方法里都能直接写self.lineEdit.text()、self.tableWidget.setRowCount(5)，不需要任何中间层。
这种便利性在小型工具里体现得淋漓尽致。比如做一个串口调试助手，界面上就十来个控件，继承写法下整个类不到一百行，逻辑一目了然。我早期做的一批内部小工具全是这么写的，改起来也快，因为控件名和代码里的名字完全对应，看界面就知道代码在哪。
但便利是有代价的。继承方式下，你的业务逻辑和界面定义是强耦合的。一旦界面改动大，比如把某个按钮从pushButton改名成btn_start，重新生成.py之后，你代码里所有self.pushButton的引用全部失效，得手动一个个改。界面改得越勤，这种维护成本越高。
2.3 继承方式下信号槽连接的注意事项
信号槽连接在继承写法里很自然，但有个细节要注意：连接必须放在setupUi之后。因为控件是在setupUi里创建的，之前访问self.pushButton会直接抛AttributeError。
def __init__(self): super().__init__() self.setupUi(self) # 先建控件 self.pushButton.clicked.connect(self.on_button_click) # 再连信号另外，如果你在Qt Designer里已经通过"信号/槽编辑器"连了一些槽函数，pyuic5生成的代码里会自动带上QtCore.QMetaObject.connectSlotsByName(self)。这行代码的作用是按命名约定自动连接信号，比如控件叫pushButton、你定义了on_pushButton_clicked方法，它就会自动连上。这个机制在继承写法里能用，但很容易和手动连接冲突——同一个信号被连了两次，槽函数执行两遍。我的建议是：要么全用设计器连，要么全用代码连，别混着来。混用导致的重复触发问题，排查起来特别费劲，因为代码里看不到连接语句。
3. 方式二：实例化Ui类，把界面当"零件"装进窗口
3.1 组合写法的标准模板
第二种方式不继承，而是把Ui_MainWindow实例化成一个对象，作为主窗口的属性。标准写法是这样：
import sys from PyQt5.QtWidgets import QApplication, QMainWindow from main_window import Ui_MainWindow class MyWindow(QMainWindow): def __init__(self): super().__init__() self.ui = Ui_MainWindow() self.ui.setupUi(self) self.ui.pushButton.clicked.connect(self.on_button_click) def on_button_click(self): self.ui.label.setText("按钮被点击了") if __name__ == "__main__": app = QApplication(sys.argv) window = MyWindow() window.show() sys.exit(app.exec_())区别一眼可见：控件访问全部变成self.ui.xxx。多了一层ui前缀，看起来啰嗦，但换来的是界面和逻辑的彻底分离。self.ui这个对象只负责界面，你的MyWindow只负责业务逻辑，两者通过self.ui这个明确的接口通信。
3.2 组合方式为什么更适合界面频繁迭代
组合方式的核心价值在重新生成界面代码时不会破坏业务逻辑。因为你的业务代码全在MyWindow里，而MyWindow不继承Ui_MainWindow，所以无论main_window.py怎么重新生成、控件怎么改名，你的MyWindow类结构都不受影响。你只需要改self.ui.新控件名这一处引用，而不是满文件找旧控件名。
我后来做的一个数据采集上位机，界面前前后后改了十几版，从最初的几个按钮加到后来的多标签页、表格、图表。因为一开始就用了组合方式，每次改界面就是重新跑一遍pyuic5，然后调整self.ui下的引用，业务逻辑一行没动。如果当初用继承，光是控件重命名就能把我折腾疯。
3.3 组合方式里容易忽略的self.ui作用域问题
组合写法有个隐蔽的坑：self.ui必须在__init__里创建，且不能是局部变量。如果你写成ui = Ui_MainWindow()（少了self.），那ui就是个局部变量，__init__执行完就被回收，窗口上虽然显示了控件（因为setupUi已经执行过），但你后续任何方法里都访问不到self.ui，一访问就报AttributeError。
# 错误写法 def __init__(self): super().__init__() ui = Ui_MainWindow() # 局部变量，出了__init__就没了 ui.setupUi(self) # 正确写法 def __init__(self): super().__init__() self.ui = Ui_MainWindow() # 实例属性，全程可用 self.ui.setupUi(self)这个错误很典型，因为程序启动时界面正常显示，看不出问题，只有当你点击按钮触发槽函数、槽函数里访问self.ui时才崩。新手往往以为是信号槽没连上，其实是self.ui根本没保存下来。
4. 两种方式怎么选：一张表说清楚适用边界
光讲两种写法还不够，关键是知道什么场景用哪个。我按自己的经验整理了一张对照表，覆盖了最常见的几个判断维度：
| 判断维度 | 继承方式 | 组合方式 |
|---|---|---|
| 代码量 | 少，控件直接访问 | 略多，需self.ui.前缀 |
| 界面改动频繁度 | 低时合适 | 高时合适 |
| 业务逻辑复杂度 | 简单工具够用 | 复杂逻辑更清晰 |
| 多人协作 | 界面逻辑易混淆 | 界面逻辑边界清晰 |
| 控件重命名影响 | 全文件替换 | 只改引用处 |
| 学习曲线 | 直观，新手友好 | 需理解组合概念 |
| 适合项目规模 | 小型单文件工具 | 中大型多模块项目 |
从表里能看出一个清晰的规律：继承方式适合"一次成型、改动少"的小工具，组合方式适合"持续迭代、逻辑复杂"的正经项目。这不是绝对的，但按这个原则选，基本不会错。
举个具体例子。如果你只是写个批量重命名文件的小脚本，界面上就一个选择目录按钮、一个输入框、一个执行按钮，那继承方式完全够用，代码短、看得清。但如果你要做一个带登录、主界面、多个功能页、还要连数据库的桌面应用，那组合方式是唯一合理的选择，否则后期维护会变成灾难。
还有一个折中方案值得一提：用组合方式写，但把self.ui的引用在__init__里做一层转发。比如self.pushButton = self.ui.pushButton，这样后续代码里既能用self.pushButton的简洁写法，又保留了组合方式的可维护性。不过我不太推荐这么做，因为它把两种方式的缺点都沾上了——既有多余的转发代码，又让界面和逻辑的边界重新模糊。老老实实用self.ui.xxx，习惯之后并不觉得麻烦。
5. 转换与调用过程中的高频踩坑实录
5.1 pyuic5转换后文件里的隐藏陷阱
pyuic5生成的.py文件，表面看就是个普通的类定义，但有几个地方容易出问题。第一，文件顶部的import可能包含你环境里没有的模块。比如设计器里用了某个自定义控件或者QtChart，生成的代码会from PyQt5 import QtChart，而你环境里没装，一运行就ImportError。解决办法是装对应模块，或者在设计器里别用那些控件。
第二，生成的代码里控件名是设计器里设的objectName。很多人拖控件时不改objectName，结果一堆pushButton、pushButton_2、pushButton_3，代码里根本分不清哪个是哪个。我的习惯是拖完控件立刻改objectName，用有意义的名字，比如btn_open_file、edit_file_path、table_result。这个习惯能省掉后期大量猜测时间。
第三，生成的.py文件编码问题。如果设计器里控件文本用了中文，生成的代码里会有中文字符串。Python 3默认UTF-8，一般没问题，但如果你的编辑器或运行环境编码不对，会报SyntaxError。稳妥做法是在文件头加# -*- coding: utf-8 -*-，虽然Python 3不强制，但能避免一些边缘情况。
5.2 界面显示空白或控件错位的排查思路
界面跑起来一片空白，或者控件挤成一团，这是新手最常遇到的问题。排查顺序我总结成三步：
- 确认
setupUi被调用了。继承方式看__init__里有没有self.setupUi(self)，组合方式看有没有self.ui.setupUi(self)。漏掉这行，窗口就是个空壳。 - 确认
super().__init__()被调用了。继承方式下漏掉这行，QMainWindow没初始化，窗口显示异常。 - 确认布局用对了。Qt Designer里如果只拖控件不设布局，控件位置是绝对坐标，窗口一缩放就错位。正确做法是选中容器控件，点工具栏的"栅格布局"或"垂直/水平布局"，让布局管理器接管位置。
这三步能解决九成以上的显示问题。如果还不行，就在setupUi之后加一句self.resize(800, 600)强制设个初始尺寸，有时候是窗口默认尺寸太小导致控件被挤没了。
5.3 重新生成代码后逻辑丢失的预防手段
这是继承方式最大的痛点：重新跑pyuic5，main_window.py被覆盖，如果你把业务逻辑写在了这个文件里，全部丢失。预防手段有三条：
- 永远不要在生成的.py文件里写业务逻辑。这个文件是"编译产物"，不是源码。业务逻辑写在单独的
my_window.py里。 - 用版本控制。把.ui文件和业务代码都纳入git管理，生成的.py可以加进
.gitignore，因为它随时能重新生成。 - 如果非要在生成文件里加东西，用单独的扩展文件。比如生成
main_window.py后，再写个main_window_ext.py继承它，所有扩展写在这里。这样重新生成不影响扩展。
我见过有人直接在生成的.py里改代码，结果下次改界面重新生成，几百行逻辑瞬间蒸发，只能从回收站找。这种亏吃一次就够了。
6. 把两种方式用对的几个实战心得
6.1 信号槽在两种方式下的连接位置差异
继承方式下，信号连接写在__init__里setupUi之后即可。组合方式下也一样，但要注意连接的是self.ui.pushButton而不是self.pushButton。这个前缀差异看似小，但写错就是AttributeError。
另外，如果槽函数需要访问界面控件，继承方式直接self.xxx，组合方式self.ui.xxx。我建议在组合方式里，槽函数内部第一行就把需要的控件取出来，比如label = self.ui.label，后面用label，这样代码短一些，也避免反复写self.ui。
6.2 自定义信号在组合方式下的传递路径
组合方式下，如果你在MyWindow里定义自定义信号，界面控件触发后需要把信号转发出去，路径是：控件信号 →MyWindow的槽 →MyWindow的自定义信号 → 外部接收者。多了一层转发，但换来的是界面和业务解耦。继承方式下可以直接把控件信号连到外部，少一层，但耦合更紧。
这个差异在单窗口程序里不明显，但在多窗口、多模块的程序里，组合方式的信号转发路径更清晰，因为所有对外接口都集中在MyWindow这一层，不会让外部代码直接依赖某个具体控件。
6.3 从继承迁移到组合的实操步骤
如果你已经用继承写了个项目，后来发现维护困难想迁移到组合，步骤不复杂：
- 把
class MyWindow(QMainWindow, Ui_MainWindow)改成class MyWindow(QMainWindow)。 __init__里self.setupUi(self)改成self.ui = Ui_MainWindow()加self.ui.setupUi(self)。- 全文把所有
self.控件名替换成self.ui.控件名。用编辑器的正则替换，self\.(pushButton|label|lineEdit)这种模式批量处理。 - 信号连接里的控件引用同步加
self.ui.前缀。 - 跑一遍，看有没有漏网的
AttributeError。
整个过程半小时以内能搞定，迁移后维护成本立刻下降。我有个项目就是这么迁的，迁完当天就庆幸做了这个决定。
6.4 一个容易被忽视的细节：窗口关闭时的资源释放
无论哪种方式，窗口关闭时如果开了线程、数据库连接、串口等资源，都要在closeEvent里释放。组合方式下，closeEvent写在MyWindow里，访问self.ui没问题。继承方式下也一样。但要注意，如果用了QThread，必须在关闭前quit()并wait()，否则程序退出时可能报QThread: Destroyed while thread is still running。这个和调用方式无关，但两种方式下都容易忘，顺手提一句。
7. 关于选型，我自己的最终建议
绕了一圈，回到最开始的问题：两种调用方式到底选哪个？我的答案很明确——只要项目不是"写完就扔"的一次性脚本，就用组合方式。多写的那点self.ui.前缀，换来的是界面和逻辑的清晰边界、界面迭代时的零风险、以及多人协作时的低沟通成本。这些收益远超那点打字成本。
继承方式不是不能用，它在教学演示、快速原型、单文件小工具里依然有它的位置。但一旦你发现自己在反复重新生成界面代码、反复修控件引用，那就是该迁移的信号了。
最后留一个我常用的判断标准：如果你预计这个界面会改超过三次，就用组合；如果只是临时验证个想法，继承更快。按这个标准选，基本不会后悔。
