PyQt-Fluent-Widgets 与 PySide 兼容性指南：从 PyQt5 迁移到 PySide6 全攻略-优快云博客

PyQt-Fluent-Widgets 与 PySide 兼容性指南：从 PyQt5 迁移到 PySide6 全攻略

【免费下载链接】PyQt-Fluent-Widgets A fluent design widgets library based on C++ Qt/PyQt/PySide. Make Qt Great Again. 项目地址: https://gitcode.com/gh_mirrors/py/PyQt-Fluent-Widgets

引言：为何需要迁移到 PySide6？

在 Python GUI 开发领域，PyQt 和 PySide 是两大主流框架。PyQt5 虽然功能强大，但受限于 GPL 协议，而 PySide6 作为 Qt 官方推出的 Python 绑定，采用更为宽松的 LGPL 协议，更适合商业项目开发。本指南将详细介绍如何将基于 PyQt-Fluent-Widgets 的项目从 PyQt5 平稳迁移到 PySide6，充分利用两者的优势。

兼容性概览

PyQt-Fluent-Widgets 最初是基于 PyQt5 开发的，如 qfluentwidgets/init.py 中所述："A fluent design widgets library based on PyQt5."。但通过适当的调整，我们可以使其与 PySide6 兼容。

核心差异对比

特性	PyQt5	PySide6	迁移注意事项
许可协议	GPL	LGPL	商业项目更适合 PySide6
模块命名	PyQt5.QtWidgets	PySide6.QtWidgets	需要统一模块导入路径
信号槽语法	@pyqtSlot, pyqtSignal	@Slot, Signal	装饰器和信号类名变更
资源文件处理	pyrcc5	pyside6-rcc	资源编译工具不同

迁移准备工作

环境配置

首先，确保已安装 PySide6 和相关依赖。可以通过修改 setup.py 中的依赖项来实现：

# setup.py 中修改依赖
install_requires=[
    "PySide6>=6.2.0",  # 替换 PyQt5
    "PyQt-Frameless-Window>=0.4.0",
    "darkdetect",
]

项目结构分析

在开始迁移前，建议先了解项目中使用到的 PyQt-Fluent-Widgets 组件。主要组件位于以下目录：

qfluentwidgets/components/：核心控件实现
qfluentwidgets/window/：窗口相关类
qfluentwidgets/common/：通用工具函数

代码迁移步骤

1. 模块导入替换

将所有 PyQt5 的导入替换为 PySide6。例如：

# 替换前
from PyQt5.QtWidgets import QApplication, QMainWindow

# 替换后
from PySide6.QtWidgets import QApplication, QMainWindow

2. 信号槽语法调整

PySide6 使用 Signal 和 Slot 替代 PyQt5 的 pyqtSignal 和 pyqtSlot：

# 替换前
from PyQt5.QtCore import pyqtSignal, pyqtSlot

class MyWidget(QWidget):
    value_changed = pyqtSignal(int)
    
    @pyqtSlot(int)
    def on_value_changed(self, value):
        pass

# 替换后
from PySide6.QtCore import Signal, Slot

class MyWidget(QWidget):
    value_changed = Signal(int)
    
    @Slot(int)
    def on_value_changed(self, value):
        pass

3. 资源文件处理

PySide6 使用 pyside6-rcc 编译资源文件，替代 PyQt5 的 pyrcc5：

# 编译资源文件
pyside6-rcc resources.qrc -o resources.py

兼容性问题解决方案

样式表兼容性

PyQt-Fluent-Widgets 的样式表在 PySide6 下可能需要微调。样式表文件位于 qfluentwidgets/_rc/qss/，包含浅色和深色两种主题。

示例程序迁移

以 examples/gallery/demo.py 为例，展示迁移后的效果：

# 迁移后的示例代码
from PySide6.QtWidgets import QApplication
from qfluentwidgets import FluentWindow

if __name__ == "__main__":
    app = QApplication([])
    window = FluentWindow()
    window.show()
    app.exec()