Python PySide6 从入门到实战：打造专业跨平台桌面应用全指南

目录

引言：为什么选择 PySide6 做 GUI 开发？

一、环境搭建与基础认知

1.1 安装配置步骤

1.2 第一个 PySide6 程序

1.3 PySide6 与 PyQt 的核心区别

二、核心模块解析

2.1 QtCore 模块：无 GUI 依赖的核心功能

2.2 QtWidgets 模块：桌面 UI 组件核心

2.2.1 基础控件速览

2.2.2 容器与数据展示控件

2.3 QtGui 模块：图形与界面基础

三、布局管理：打造响应式界面

3.1 布局管理器类型与特点

3.2 布局使用实战

四、信号与槽：Qt 的核心事件机制

4.1 核心概念解析

4.2 信号与槽的多种使用方式

4.2.1 基础绑定

4.2.2 自定义信号

4.2.3 跨线程信号传递

五、实战项目：视频批量剪辑工具

5.1 项目需求分析

5.2 技术方案设计

5.3 完整代码实现

5.4 项目运行与打包

5.4.1 零依赖运行（推荐）

5.4.2 打包为可执行文件

六、避坑指南与最佳实践

6.1 常见错误与解决方案

6.2 开发最佳实践

总结与展望

---

 

class 卑微码农:
    def __init__(self):
        self.技能 = ['能读懂十年前祖传代码', '擅长用Ctrl+C/V搭建世界', '信奉"能跑就别动"的玄学']
        self.发量 = 100  # 初始发量
        self.咖啡因耐受度 = '极限'
        
    def 修Bug(self, bug):
        try:
            # 试图用玄学解决问题
            if bug.严重程度 == '离谱':
                print("这一定是环境问题！")
            else:
                print("让我看看是谁又没写注释...哦，是我自己。")
        except Exception as e:
            # 如果try块都救不了，那就...
            print("重启一下试试？")
            self.发量 -= 1  # 每解决一个bug，头发-1
 
 
# 实例化一个我
我 = 卑微码农()

引言：为什么选择 PySide6 做 GUI 开发？

在 Python GUI 开发领域，Tkinter 轻量但功能有限，PyQt 强大却受限于许可协议，而 PySide6 作为 Qt 官方推出的 Python 绑定库，完美平衡了功能、许可与跨平台特性。它基于 Qt 6 框架，不仅继承了 Qt 丰富的组件生态和高效的事件处理机制，更以 LGPL 开源协议提供了商业友好的授权方案 —— 允许闭源商业软件使用，无需公开源代码，仅需保留 Qt 相关版权声明。无论是开发开源工具还是商业应用，PySide6 都能满足从简单界面到复杂系统的全场景需求。

本文将从零基础开始，系统讲解 PySide6 的核心知识点与实战技巧，内容涵盖环境搭建、核心模块、组件使用、布局管理、信号与槽、多线程编程，最终通过完整项目案例实现知识落地。全程搭配可直接运行的代码示例和清晰对比表格，帮助你快速掌握 PySide6 开发能力。

---

一、环境搭建与基础认知

1.1 安装配置步骤

PySide6 的安装过程简洁高效，支持 Windows、macOS、Linux 全平台，只需确保 Python 版本在 3.6 以上（推荐 3.9+）：

# 基础安装命令
pip install pyside6

# 验证安装成功（运行无报错即正常）
python -c "from PySide6.QtWidgets import QWidget; print('安装成功')"

注意事项：

• Windows 系统若出现依赖缺失，需先安装 Visual C++ Build Tools；
• macOS 系统建议通过 Homebrew 先安装 Qt6 核心库，再执行 pip 安装；
• Linux 系统需提前安装 libxcb 库（Ubuntu：sudo apt-get install libxcb-xinerama0）。

1.2 第一个 PySide6 程序

所有 PySide6 GUI 程序都遵循固定的基础结构，核心需创建QApplication实例（管理应用生命周期）和窗口实例：

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

if __name__ == "__main__":
    # 1. 创建应用实例（必须是第一个创建的对象）
    app = QApplication(sys.argv)
    
    # 2. 创建主窗口
    window = QWidget()
    window.setWindowTitle("我的第一个PySide6程序")  # 设置窗口标题
    window.setGeometry(100, 100, 600, 400)  # 窗口位置（x,y）和大小（宽,高）
    
    # 3. 添加组件（标签）
    label = QLabel("Hello PySide6!", parent=window)
    label.move(250, 180)  # 组件在窗口内的位置
    
    # 4. 显示窗口
    window.show()
    
    # 5. 启动事件循环（确保程序正常退出并释放资源）
    sys.exit(app.exec())

运行上述代码，将看到一个居中显示 "Hello PySide6!" 的窗口，这标志着你的 PySide6 开发环境已完全就绪。

1.3 PySide6 与 PyQt 的核心区别

很多开发者会混淆 PySide6 与 PyQt，两者功能高度相似，但在授权、维护等方面存在关键差异，选择时需重点关注：

对比维度	PySide6	PyQt（以 PyQt6 为例）
开发主体	Qt 官方（The Qt Company）	第三方公司（Riverbank Computing）
授权协议	LGPL 协议，商业友好，闭源可用	GPL 协议（开源）/ 商业授权（付费）
版本对应	与 Qt 版本完全同步（PySide6 对应 Qt6）	独立版本号，需手动匹配 Qt 版本
信号槽语法	使用 Signal 和 Slot 装饰器	使用 pyqtSignal 和 pyqtSlot 装饰器
社区支持	官方维护，更新及时，文档同步 Qt	历史悠久，早期资源丰富

选择建议：新项目优先使用 PySide6，尤其是商业项目；若需兼容旧有代码，可继续使用 PyQt。

---

二、核心模块解析

PySide6 的功能由多个模块协同提供，其中三大核心模块支撑了绝大多数 GUI 开发场景：

2.1 QtCore 模块：无 GUI 依赖的核心功能

QtCore 是 PySide6 的基础模块，不依赖 GUI 组件，可独立用于控制台程序，提供核心功能支持：

• 信号与槽：对象间通信的核心机制，支持多种类型参数传递；
• 事件循环：通过QEventLoop处理用户输入和系统事件；
• 定时器：QTimer实现定时任务执行；
• 基础工具：文件操作（QFile/QDir）、日期时间（QDateTime）、线程（QThread）等。

代码示例：定时器使用

import sys
from PySide6.QtWidgets import QApplication, QWidget, QLabel
from PySide6.QtCore import QTimer

class TimerDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()
        
    def init_ui(self):
        self.setWindowTitle("定时器示例")
        self.resize(300, 200)
        self.label = QLabel("倒计时：5", self)
        self.label.move(130, 80)
        
        # 创建定时器，每隔1秒触发一次
        self.timer = QTimer(self)
        self.timer.timeout.connect(self.update_countdown)
        self.timer.start(1000)  # 单位：毫秒
        
        self.count = 5
        
    def update_countdown(self):
        self.count -= 1
        self.label.setText(f"倒计时：{self.count}")
        if self.count == 0:
            self.timer.stop()
            self.label.setText("时间到！")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    demo = TimerDemo()
    demo.show()
    sys.exit(app.exec())

2.2 QtWidgets 模块：桌面 UI 组件核心

QtWidgets 提供了丰富的可视化组件，是传统桌面应用开发的核心模块，涵盖基础控件、容器控件、数据展示控件等：

2.2.1 基础控件速览

控件类名	功能描述	常用场景
QPushButton	可点击按钮，支持文本 / 图标	触发操作（登录、提交等）
QRadioButton	单选按钮，需配合 QButtonGroup 分组	单一选项选择（性别、类型等）
QLineEdit	单行文本输入框	用户名、密码输入
QTextEdit	多行文本编辑框	内容编辑、日志显示
QSpinBox	数字微调框	整数参数调整（数量、大小等）
QSlider	滑动条	连续值调整（音量、亮度等）
QDateTimeEdit	日期时间编辑框	日期 / 时间选择输入

代码示例：基础控件组合使用

import sys
from PySide6.QtWidgets import (QApplication, QWidget, QLabel, QPushButton,
                               QLineEdit, QRadioButton, QButtonGroup, QVBoxLayout)

class BasicWidgetsDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()
        
    def init_ui(self):
        self.setWindowTitle("基础控件示例")
        self.resize(400, 300)
        
        # 创建布局（后续章节详细讲解，此处用于组件排列）
        layout = QVBoxLayout()
        
        # 1. 文本输入与按钮
        layout.addWidget(QLabel("用户名："))
        self.username_input = QLineEdit()
        layout.addWidget(self.username_input)
        
        # 2. 单选按钮组
        gender_group = QButtonGroup()
        male_radio = QRadioButton("男")
        female_radio = QRadioButton("女")
        gender_group.addButton(male_radio)
        gender_group.addButton(female_radio)
        layout.addWidget(QLabel("性别："))
        layout.addWidget(male_radio)
        layout.addWidget(female_radio)
        
        # 3. 功能按钮
        self.submit_btn = QPushButton("提交")
        self.submit_btn.clicked.connect(self.on_submit)  # 绑定点击事件
        layout.addWidget(self.submit_btn)
        
        self.setLayout(layout)
        
    def on_submit(self):
        # 获取输入内容并打印
        username = self.username_input.text()
        print(f"用户名：{username}")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    demo = BasicWidgetsDemo()
    demo.show()
    sys.exit(app.exec())

2.2.2 容器与数据展示控件

容器控件用于组织界面结构，数据展示控件用于呈现复杂数据：

• 容器控件：QGroupBox（分组容器）、QTabWidget（标签页）、QStackedWidget（堆叠容器）；
• 数据展示控件：QListWidget（列表）、QTableWidget（表格）、QTreeWidget（树形）、QProgressBar（进度条）。

代码示例：QTabWidget 标签页使用

import sys
from PySide6.QtWidgets import (QApplication, QMainWindow, QTabWidget,
                               QWidget, QVBoxLayout, QLabel)

class TabWidgetDemo(QMainWindow):
    def __init__(self):
        super().__init__()
        self.init_ui()
        
    def init_ui(self):
        self.setWindowTitle("标签页示例")
        self.resize(500, 300)
        
        # 创建标签页容器
        tab_widget = QTabWidget()
        
        # 创建第一个标签页
        tab1 = QWidget()
        tab1_layout = QVBoxLayout()
        tab1_layout.addWidget(QLabel("这是首页内容"))
        tab1.setLayout(tab1_layout)
        tab_widget.addTab(tab1, "首页")  # 添加标签页并设置标题
        
        # 创建第二个标签页
        tab2 = QWidget()
        tab2_layout = QVBoxLayout()
        tab2_layout.addWidget(QLabel("这是设置页面"))
        tab2.setLayout(tab2_layout)
        tab_widget.insertTab(1, tab2, "设置")  # 插入到指定位置
        
        # 设置主窗口中心部件
        self.setCentralWidget(tab_widget)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    demo = TabWidgetDemo()
    demo.show()
    sys.exit(app.exec())

2.3 QtGui 模块：图形与界面基础

QtGui 模块为界面提供图形支持，是 QtWidgets 的底层依赖，核心功能包括：

• 窗口外观设置（图标、样式）；
• 字体、颜色管理；
• 2D 绘图（QPainter、QPainterPath）；
• 图像处理（QPixmap、QImage）。

代码示例：简单绘图

import sys
from PySide6.QtWidgets import QApplication, QWidget
from PySide6.QtGui import QPainter, QColor, QPen
from PySide6.QtCore import Qt

class DrawingDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("绘图示例")
        self.resize(400, 300)
        
    # 重写绘图事件
    def paintEvent(self, event):
        painter = QPainter(self)
        painter.begin(self)
        
        # 设置画笔（红色、2px宽度）
        pen = QPen(QColor(255, 0, 0), 2, Qt.SolidLine)
        painter.setPen(pen)
        
        # 绘制直线
        painter.drawLine(50, 50, 350, 50)
        
        # 绘制矩形
        painter.drawRect(50, 100, 300, 100)
        
        painter.end()

if __name__ == "__main__":
    app = QApplication(sys.argv)
    demo = DrawingDemo()
    demo.show()
    sys.exit(app.exec())

---

三、布局管理：打造响应式界面

手动设置组件位置（move()/setGeometry()）无法适应窗口缩放，PySide6 提供 4 种核心布局管理器，实现组件自动排列和响应式适配：

3.1 布局管理器类型与特点

布局类型	功能描述	适用场景
QVBoxLayout	垂直布局，组件自上而下排列	表单、列表等垂直结构
QHBoxLayout	水平布局，组件自左向右排列	按钮组、工具栏等水平结构
QGridLayout	网格布局，组件按行列排列	登录表单、数据表格等结构化界面
QFormLayout	表单布局，标签 - 输入框成对排列	配置页面、信息录入界面

3.2 布局使用实战

布局支持嵌套组合，可实现复杂界面的灵活排版，以下是登录表单的网格布局实现：

import sys
from PySide6.QtWidgets import (QApplication, QWidget, QLabel, QLineEdit,
                               QPushButton, QGridLayout, QVBoxLayout)
from PySide6.QtGui import QFont

class LoginForm(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()
        
    def init_ui(self):
        self.setWindowTitle("登录表单")
        self.resize(400, 200)
        
        # 主布局（垂直布局，实现整体居中）
        main_layout = QVBoxLayout()
        self.setLayout(main_layout)
        
        # 网格布局（用于表单内容排版）
        grid_layout = QGridLayout()
        main_layout.addLayout(grid_layout)
        
        # 用户名行（第0行）
        username_label = QLabel("用户名：")
        username_label.setFont(QFont("SimHei", 12))  # 设置中文支持字体
        self.username_input = QLineEdit()
        self.username_input.setFont(QFont("SimHei", 12))
        # 添加到网格：行0，列0，占1行1列；行0，列1，占1行1列
        grid_layout.addWidget(username_label, 0, 0, 1, 1)
        grid_layout.addWidget(self.username_input, 0, 1, 1, 1)
        
        # 密码行（第1行）
        password_label = QLabel("密码：")
        password_label.setFont(QFont("SimHei", 12))
        self.password_input = QLineEdit()
        self.password_input.setEchoMode(QLineEdit.Password)  # 密码隐藏模式
        self.password_input.setFont(QFont("SimHei", 12))
        grid_layout.addWidget(password_label, 1, 0, 1, 1)
        grid_layout.addWidget(self.password_input, 1, 1, 1, 1)
        
        # 登录按钮（第2行，跨2列显示）
        login_btn = QPushButton("登录")
        login_btn.setFont(QFont("SimHei", 12))
        grid_layout.addWidget(login_btn, 2, 0, 1, 2)
        
        # 设置布局间距（优化界面美观度）
        grid_layout.setHorizontalSpacing(10)  # 列间距
        grid_layout.setVerticalSpacing(15)    # 行间距
        grid_layout.setContentsMargins(50, 30, 50, 30)  # 外间距（上右下左）

if __name__ == "__main__":
    app = QApplication(sys.argv)
    form = LoginForm()
    form.show()
    sys.exit(app.exec())

布局使用注意事项：

1. 避免混合使用布局与绝对定位，会导致界面错乱；
2. 可通过addLayout()实现布局嵌套，灵活构建复杂界面；
3. 布局会自动适应窗口缩放，无需手动调整组件位置。

---

四、信号与槽：Qt 的核心事件机制

信号与槽是 PySide6 的灵魂，用于实现组件间的解耦通信，是处理用户交互的核心方式。

4.1 核心概念解析

• 信号（Signal）：组件状态变化时发出的通知（如按钮点击、文本改变）；
• 槽（Slot）：接收信号并处理的函数或方法；
• 连接（Connect）：通过signal.connect(slot)将信号与槽绑定，信号触发时槽函数自动执行。

4.2 信号与槽的多种使用方式

4.2.1 基础绑定

直接将组件的内置信号绑定到自定义槽函数：

import sys
from PySide6.QtWidgets import (QApplication, QWidget, QLabel,
                               QLineEdit, QPushButton, QVBoxLayout)

class SignalSlotBasic(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()
        
    def init_ui(self):
        self.setWindowTitle("信号与槽基础示例")
        self.resize(400, 200)
        
        layout = QVBoxLayout()
        self.label = QLabel("请输入文本：")
        self.input = QLineEdit()
        self.btn = QPushButton("获取输入内容")
        
        # 绑定信号与槽
        self.input.textChanged.connect(self.on_text_change)  # 文本改变时触发
        self.btn.clicked.connect(self.on_btn_click)          # 按钮点击时触发
        
        layout.addWidget(self.label)
        layout.addWidget(self.input)
        layout.addWidget(self.btn)
        self.setLayout(layout)
        
    # 文本改变的槽函数
    def on_text_change(self, text):
        self.label.setText(f"当前输入：{text}")
        
    # 按钮点击的槽函数
    def on_btn_click(self):
        print(f"最终输入：{self.input.text()}")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    demo = SignalSlotBasic()
    demo.show()
    sys.exit(app.exec())

4.2.2 自定义信号

当内置信号无法满足需求时，可自定义信号并指定参数类型：

import sys
from PySide6.QtWidgets import QApplication, QWidget, QPushButton, QVBoxLayout
from PySide6.QtCore import Signal, QObject

# 自定义信号类（需继承QObject）
class CustomSignals(QObject):
    # 定义无参数信号
    signal1 = Signal()
    # 定义带字符串参数的信号
    signal2 = Signal(str)
    # 定义带多类型参数的信号
    signal3 = Signal(int, str)

class CustomSignalDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()
        self.custom_signals = CustomSignals()
        # 绑定自定义信号与槽
        self.custom_signals.signal1.connect(self.on_signal1)
        self.custom_signals.signal2.connect(self.on_signal2)
        self.custom_signals.signal3.connect(self.on_signal3)
        
    def init_ui(self):
        self.setWindowTitle("自定义信号示例")
        self.resize(300, 150)
        
        layout = QVBoxLayout()
        self.btn1 = QPushButton("触发无参数信号")
        self.btn2 = QPushButton("触发字符串参数信号")
        self.btn3 = QPushButton("触发多参数信号")
        
        self.btn1.clicked.connect(self.emit_signal1)
        self.btn2.clicked.connect(self.emit_signal2)
        self.btn3.clicked.connect(self.emit_signal3)
        
        layout.addWidget(self.btn1)
        layout.addWidget(self.btn2)
        layout.addWidget(self.btn3)
        self.setLayout(layout)
        
    # 发射信号的方法
    def emit_signal1(self):
        self.custom_signals.signal1.emit()
        
    def emit_signal2(self):
        self.custom_signals.signal2.emit("Hello 自定义信号！")
        
    def emit_signal3(self):
        self.custom_signals.signal3.emit(2025, "Python PySide6")
        
    # 处理信号的槽函数
    def on_signal1(self):
        print("无参数信号被触发！")
        
    def on_signal2(self, msg):
        print(f"字符串参数信号：{msg}")
        
    def on_signal3(self, num, msg):
        print(f"多参数信号：数字{num}，消息{msg}")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    demo = CustomSignalDemo()
    demo.show()
    sys.exit(app.exec())

4.2.3 跨线程信号传递

信号与槽机制的核心优势之一是支持线程安全的跨线程通信，无需手动处理锁机制：

import sys
import time
from PySide6.QtWidgets import (QApplication, QWidget, QLabel,
                               QPushButton, QVBoxLayout, QProgressBar)
from PySide6.QtCore import Signal, QThread, QObject

# 后台任务类（执行耗时操作）
class Worker(QObject):
    # 进度更新信号
    progress_update = Signal(int)
    # 任务完成信号
    finished = Signal()
    
    def run(self):
        # 模拟耗时任务（0-100%进度）
        for i in range(101):
            time.sleep(0.05)
            self.progress_update.emit(i)  # 发射进度信号
        self.finished.emit()  # 发射完成信号

class ThreadSignalDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()
        
    def init_ui(self):
        self.setWindowTitle("跨线程信号传递示例")
        self.resize(400, 150)
        
        layout = QVBoxLayout()
        self.progress_bar = QProgressBar()
        self.start_btn = QPushButton("开始任务")
        self.start_btn.clicked.connect(self.start_task)
        
        layout.addWidget(self.progress_bar)
        layout.addWidget(self.start_btn)
        self.setLayout(layout)
        
    def start_task(self):
        # 创建线程和任务对象
        self.worker = Worker()
        self.thread = QThread()
        
        # 将任务移到线程中
        self.worker.moveToThread(self.thread)
        
        # 绑定信号与槽
        self.thread.started.connect(self.worker.run)
        self.worker.progress_update.connect(self.update_progress)
        self.worker.finished.connect(self.task_finished)
        self.worker.finished.connect(self.thread.quit)  # 任务完成后退出线程
        self.worker.finished.connect(self.worker.deleteLater)  # 释放任务对象
        self.thread.finished.connect(self.thread.deleteLater)  # 释放线程对象
        
        # 禁用按钮防止重复点击
        self.start_btn.setEnabled(False)
        
        # 启动线程
        self.thread.start()
        
    def update_progress(self, value):
        self.progress_bar.setValue(value)
        
    def task_finished(self):
        self.start_btn.setEnabled(True)
        print("任务完成！")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    demo = ThreadSignalDemo()
    demo.show()
    sys.exit(app.exec())

---

五、实战项目：视频批量剪辑工具

结合前面的知识点，我们开发一个实用的视频批量剪辑工具，支持根据字幕文件自动剪辑视频片段，实现界面响应式操作。

5.1 项目需求分析

• 支持选择视频文件和字幕文件；
• 解析字幕文件中的时间轴信息；
• 批量剪辑视频片段并保存；
• 显示剪辑进度，确保界面不卡顿；
• 支持异常处理和结果提示。

5.2 技术方案设计

• UI 组件：使用 QFileDialog 选择文件，QProgressBar 显示进度，QTextEdit 显示日志；
• 核心逻辑：通过 ffmpeg 实现视频剪辑，QThreadPool 管理后台任务；
• 线程通信：自定义信号传递进度和结果信息；
• 依赖管理：使用 uv 工具实现零依赖运行。

5.3 完整代码实现

import sys
import subprocess
import os
from dataclasses import dataclass
from typing import List, Optional
from PySide6.QtWidgets import (QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout,
                               QPushButton, QLabel, QLineEdit, QFileDialog, QProgressBar,
                               QTextEdit, QGroupBox, QMessageBox)
from PySide6.QtCore import Qt, Signal, QObject, QRunnable, QThreadPool, QMetaObject, Q_ARG
from PySide6.QtGui import QFont

# 字幕片段数据类
@dataclass
class SubtitleSegment:
    start_time: str  # 开始时间（格式：HH:MM:SS.ms）
    end_time: str    # 结束时间
    text: str        # 字幕文本

# 信号定义类
class ClipSignals(QObject):
    progress = Signal(int)  # 进度更新（0-100）
    log = Signal(str)       # 日志输出
    finished = Signal()     # 全部完成
    error = Signal(str)     # 错误提示

# 视频剪辑任务类
class ClipTask(QRunnable):
    def __init__(self, video_path: str, output_dir: str, segments: List[SubtitleSegment], signals: ClipSignals):
        super().__init__()
        self.video_path = video_path
        self.output_dir = output_dir
        self.segments = segments
        self.signals = signals
        self.is_running = True

    def run(self):
        try:
            total = len(self.segments)
            for idx, segment in enumerate(self.segments):
                if not self.is_running:
                    break
                # 构建输出文件名
                output_filename = f"clip_{idx+1}_{segment.start_time.replace(':', '-').replace('.', '_')}.mp4"
                output_path = os.path.join(self.output_dir, output_filename)
                
                # 构建ffmpeg命令
                cmd = [
                    "ffmpeg",
                    "-i", self.video_path,
                    "-ss", segment.start_time,
                    "-to", segment.end_time,
                    "-c:v", "copy",
                    "-c:a", "copy",
                    "-y",  # 覆盖已存在文件
                    output_path
                ]
                
                # 执行命令
                self.signals.log.emit(f"正在剪辑片段 {idx+1}/{total}：{segment.text}")
                subprocess.run(cmd, check=True, capture_output=True, text=True)
                
                # 更新进度
                progress = int(((idx + 1) / total) * 100)
                self.signals.progress.emit(progress)
                
            if self.is_running:
                self.signals.log.emit("所有片段剪辑完成！")
            else:
                self.signals.log.emit("剪辑任务已取消！")
        except Exception as e:
            self.signals.error.emit(f"剪辑失败：{str(e)}")
        finally:
            self.signals.finished.emit()

    def stop(self):
        self.is_running = False

# 主窗口类
class VideoClipWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("视频批量剪辑工具")
        self.resize(800, 600)
        self.clip_task: Optional[ClipTask] = None
        self.signals = ClipSignals()
        self.init_ui()
        self.bind_signals()

    def init_ui(self):
        # 设置全局字体
        font = QFont("SimHei", 10)
        QApplication.setFont(font)

        # 中心部件
        central_widget = QWidget()
        self.setCentralWidget(central_widget)
        main_layout = QVBoxLayout(central_widget)

        # 1. 文件选择区域
        file_group = QGroupBox("文件设置")
        file_layout = QVBoxLayout(file_group)

        # 视频文件选择
        video_layout = QHBoxLayout()
        self.video_label = QLabel("视频文件：")
        self.video_edit = QLineEdit()
        self.video_btn = QPushButton("选择")
        self.video_btn.clicked.connect(self.select_video)
        video_layout.addWidget(self.video_label)
        video_layout.addWidget(self.video_edit)
        video_layout.addWidget(self.video_btn)
        file_layout.addLayout(video_layout)

        # 字幕文件选择
        subtitle_layout = QHBoxLayout()
        self.subtitle_label = QLabel("字幕文件：")
        self.subtitle_edit = QLineEdit()
        self.subtitle_btn = QPushButton("选择")
        self.subtitle_btn.clicked.connect(self.select_subtitle)
        subtitle_layout.addWidget(self.subtitle_label)
        subtitle_layout.addWidget(self.subtitle_edit)
        subtitle_layout.addWidget(self.subtitle_btn)
        file_layout.addLayout(subtitle_layout)

        # 输出目录选择
        output_layout = QHBoxLayout()
        self.output_label = QLabel("输出目录：")
        self.output_edit = QLineEdit()
        self.output_btn = QPushButton("选择")
        self.output_btn.clicked.connect(self.select_output_dir)
        output_layout.addWidget(self.output_label)
        output_layout.addWidget(self.output_edit)
        output_layout.addWidget(self.output_btn)
        file_layout.addLayout(output_layout)

        main_layout.addWidget(file_group)

        # 2. 控制区域
        control_layout = QHBoxLayout()
        self.start_btn = QPushButton("开始剪辑")
        self.start_btn.clicked.connect(self.start_clipping)
        self.stop_btn = QPushButton("取消剪辑")
        self.stop_btn.clicked.connect(self.stop_clipping)
        self.stop_btn.setEnabled(False)
        control_layout.addWidget(self.start_btn)
        control_layout.addWidget(self.stop_btn)
        main_layout.addLayout(control_layout)

        # 3. 进度显示
        self.progress_bar = QProgressBar()
        self.progress_bar.setRange(0, 100)
        main_layout.addWidget(self.progress_bar)

        # 4. 日志区域
        log_group = QGroupBox("操作日志")
        log_layout = QVBoxLayout(log_group)
        self.log_edit = QTextEdit()
        self.log_edit.setReadOnly(True)
        log_layout.addWidget(self.log_edit)
        main_layout.addWidget(log_group, 1)  # 占满剩余空间

    def bind_signals(self):
        # 绑定信号到槽函数（确保在主线程执行）
        self.signals.progress.connect(self.update_progress)
        self.signals.log.connect(self.update_log)
        self.signals.error.connect(self.show_error)
        self.signals.finished.connect(self.clipping_finished)

    def select_video(self):
        path, _ = QFileDialog.getOpenFileName(self, "选择视频文件", "", "视频文件 (*.mp4 *.avi *.mov *.mkv)")
        if path:
            self.video_edit.setText(path)

    def select_subtitle(self):
        path, _ = QFileDialog.getOpenFileName(self, "选择字幕文件", "", "字幕文件 (*.srt)")
        if path:
            self.subtitle_edit.setText(path)

    def select_output_dir(self):
        path = QFileDialog.getExistingDirectory(self, "选择输出目录")
        if path:
            self.output_edit.setText(path)

    def parse_subtitle(self, path: str) -> List[SubtitleSegment]:
        """解析SRT字幕文件"""
        segments = []
        try:
            with open(path, "r", encoding="utf-8") as f:
                content = f.read().strip().split("\n\n")
                for block in content:
                    lines = block.split("\n")
                    if len(lines) >= 3:
                        # 解析时间轴（格式：00:00:10,000 --> 00:00:15,000）
                        time_line = lines[1].strip().replace(",", ".")
                        start_time, end_time = time_line.split(" --> ")
                        # 解析文本
                        text = "\n".join(lines[2:])
                        segments.append(SubtitleSegment(start_time, end_time, text))
            self.signals.log.emit(f"成功解析 {len(segments)} 个字幕片段")
        except Exception as e:
            self.signals.error.emit(f"字幕解析失败：{str(e)}")
        return segments

    def start_clipping(self):
        # 验证输入
        video_path = self.video_edit.text().strip()
        subtitle_path = self.subtitle_edit.text().strip()
        output_dir = self.output_edit.text().strip()

        if not all([video_path, subtitle_path, output_dir]):
            QMessageBox.warning(self, "警告", "请完善所有文件路径设置！")
            return

        if not os.path.exists(video_path):
            QMessageBox.warning(self, "警告", "视频文件不存在！")
            return

        if not os.path.exists(subtitle_path):
            QMessageBox.warning(self, "警告", "字幕文件不存在！")
            return

        # 解析字幕
        segments = self.parse_subtitle(subtitle_path)
        if not segments:
            QMessageBox.warning(self, "警告", "未解析到有效字幕片段！")
            return

        # 初始化任务
        self.progress_bar.setValue(0)
        self.start_btn.setEnabled(False)
        self.stop_btn.setEnabled(True)

        # 提交任务到线程池
        self.clip_task = ClipTask(video_path, output_dir, segments, self.signals)
        QThreadPool.globalInstance().start(self.clip_task)

    def stop_clipping(self):
        if self.clip_task:
            self.clip_task.stop()
            self.signals.log.emit("正在取消剪辑任务...")

    def update_progress(self, value):
        self.progress_bar.setValue(value)

    def update_log(self, msg):
        self.log_edit.append(msg)

    def show_error(self, msg):
        QMessageBox.critical(self, "错误", msg)
        self.clipping_finished()

    def clipping_finished(self):
        self.start_btn.setEnabled(True)
        self.stop_btn.setEnabled(False)
        self.clip_task = None

# 零依赖运行支持（需安装uv：https://github.com/astral-sh/uv）
# /// script
# dependencies = [
#     "pyside6>=6.6.0",
# ]
# ///

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = VideoClipWindow()
    window.show()
    sys.exit(app.exec())

5.4 项目运行与打包

5.4.1 零依赖运行（推荐）

1. 下载 uv 工具（https://github.com/astral-sh/uv/releases）；
2. 将 uv.exe 与代码文件（app.py）放在同一目录；
3. 执行命令：uv run app.py，自动安装依赖并启动程序。

5.4.2 打包为可执行文件

使用 PyInstaller 将代码打包为 exe（Windows）或 app（macOS）：

# 安装PyInstaller
pip install pyinstaller

# 打包命令（Windows）
pyinstaller -w -F -n VideoClipTool --add-data "ffmpeg.exe;." app.py

# 打包命令（macOS/Linux）
pyinstaller -w -F -n VideoClipTool --add-data "ffmpeg:." app.py

注意：需提前下载 ffmpeg 可执行文件，与代码放在同一目录。

---

六、避坑指南与最佳实践

6.1 常见错误与解决方案

错误类型	常见原因	解决方案
中文乱码	未设置支持中文的字体	使用QFont("SimHei", 12)或QFont("Microsoft YaHei", 12)
组件不显示	未使用布局管理器或未添加到父组件	统一使用布局管理，确保组件设置 parent 属性
界面卡顿	耗时操作在主线程执行	将耗时任务移到后台线程（QThread/QThreadPool）
线程安全问题	后台线程直接操作 UI 组件	通过信号与槽机制更新 UI，禁止线程内直接操作控件
程序退出异常	未正确释放线程资源	绑定线程 finished 信号到 deleteLater ()

6.2 开发最佳实践

1. 代码组织结构：将 UI 布局、业务逻辑、数据处理分离，采用面向对象设计；
2. 样式美化：使用 QSS（Qt Style Sheet）统一设置界面样式，提升美观度；
3. 异常处理：对文件操作、网络请求、外部命令执行等场景添加异常捕获；
4. 性能优化：大量数据展示使用 Model/View 架构（QTableView+QStandardItemModel），避免频繁刷新界面；
5. 兼容性处理：针对不同操作系统适配字体、路径分隔符等细节。

---

总结与展望

PySide6 作为 Qt 官方的 Python 绑定库，凭借其强大的组件生态、灵活的授权协议和优秀的跨平台特性，已成为 Python GUI 开发的优选框架。本文从基础环境搭建到核心模块解析，再到实战项目落地，系统覆盖了 PySide6 开发的关键知识点，帮助你快速掌握从入门到精通的完整路径。

随着 Qt 6 的持续更新，PySide6 将不断引入新特性，如更好的 WebAssembly 支持、更高效的图形渲染等。未来开发中，可进一步探索自定义控件开发、3D 图形集成、数据库交互等高级功能，打造更专业的桌面应用。