网站导航
> 技术文档 > Python GUI 编程 | 界面美化 — QFluentWidgets 风格组件库介绍

Python GUI 编程 | 界面美化 — QFluentWidgets 风格组件库介绍

网友: 技术文档 2025-07-30 18:42:20

🌟想系统化学习 GUI 编程？看看这个：[Python GUI 编程] PySide & PyQt - 学习手册-CSDN博客

https://qfluentwidgets.com/https://qfluentwidgets.com/

0x01：QFluentWidgets 简介

QFluentWidgets 是一个基于 C++ Qt/PyQt/PySide 的 Fluent Design 风格组件库，里面包含了数以百计的流畅设计组件，为简化开发、提高效率而生。

以下是该组件库的特性：

  • 美观优雅： 内置 160+ 开源非商用 Fluent Design 组件，开箱即用，快速打造卓越应用。

  • 矢量图标： 内置 175 个 Fluent Design 矢量图标，随心缩放，依旧清晰。

  • 高度可定制： 支持无缝切换亮暗主题和主题色，满足用户的个性化需求。

  • 所见即所得： 搭载设计师插件，可以直接在 QtDesigner 中预览和使用组件。

  • 自由缩放： 支持自定义界面缩放，适配不同分辨率的屏幕。

  • 简单易学： 保留原生组件的 API，只需替换类名即可完成美化。

  • 国际化： 支持多国语言，满足不同用户群体的需求。

  • 跨平台： 支持 Windows、Linux 和 MacOS

0x02：QFluent Widgets 许可证

https://qfluentwidgets.com/zh/pages/pro/https://qfluentwidgets.com/zh/pages/pro/

QFluent Widgets 分为商用版和非商用版，商用版需要购买 商业许可证 （一次购买，永久有效），非商用版就需要遵循 GPLv3 许可证进行软件分发。关于 GPLv3 许可证可以参考下面这篇文章，笔者这里罗列几条笔者觉得重要的：

GPLv3 人话解读：理解GPLv3：核心条款解读与实战应用-CSDN博客

  1. 你可以免费使用、复制、修改、分发受保护的程序，但分发时一定要提供源码。

  2. 你可以收费。比如可以针对目标码、源码的分发收费，可以针对软件的维修保养（主要是提供技术支持）收费；但是不能收许可费、版税、专利许可费、授权费这类费用。

  3. GPL 程序的所有贡献者，自动免费提供了专利许可，承诺不会告人侵犯专利权（前提是你遵守了 GPL）。

  4. GPL 程序允许别人破解。如果是用在消费类硬件上，要允许别人修改并安装程序。

0x03：QFluent Widgets 环境搭建

QFluent Widgets 的安装十分简单，通过 PIP 一句话解决，但是在执行 QFluent Widgets 安装指令前建议先搭建一个新的虚拟环境（怕冲突），且 QFluent Widgets 要求 Python 最低版本为 3.7：

 PyQt5 QFluent Widgets 安装

# 安装轻量版pip install PyQt-Fluent-Widgets -i https://pypi.org/simple/​# 安装完整版 (支持亚克力组件)pip install \"PyQt-Fluent-Widgets[full]\" -i https://pypi.org/simple/

PyQt6 QFluent Widgets 安装

# 安装轻量版pip install PyQt6-Fluent-Widgets -i https://pypi.org/simple/​# 安装完整版 (支持亚克力组件)pip install \"PyQt6-Fluent-Widgets[full]\" -i https://pypi.org/simple/

PySide2 QFluent Widgets 安装

# 安装轻量版pip install PySide2-Fluent-Widgets -i https://pypi.org/simple/​# 安装完整版 (支持亚克力组件)pip install \"PySide2-Fluent-Widgets[full]\" -i https://pypi.org/simple/

PySide6 QFluent Widgets 安装

# 安装轻量版pip install PySide6-Fluent-Widgets -i https://pypi.org/simple/​# 安装完整版 (支持亚克力组件)pip install \"PySide6-Fluent-Widgets[full]\" -i https://pypi.org/simple/

警告

请勿同时安装 PyQt-Fluent-Widgets、PyQt6-Fluent-Widgets、PySide2-Fluent-Widgets 和 PySide6-Fluent-Widgets，因为它们的包名都是 qfluentwidgets。

如果混用 PyQt 和 PySide，会导致程序直接闪退。若遇到此类问题开发者需要自行检查安装的组件库是否对应所使用的 PyQt/PySide。

0x04：QFluent Widgets 快速入门

https://github.com/zhiyiYo/PyQt-Fluent-Widgets/tree/masterhttps://github.com/zhiyiYo/PyQt-Fluent-Widgets/tree/master

0x0401：运行示例

当我们通过 PIP 安装好 QFluentWidgets 包后，就可以去这个项目的仓库去下载对应的分支代码（演示案例）了（它有一条主分支，和其它几条子分支，主分支是针对 PyQt5 的）。

比如，笔者是使用下面这条语句进行安装的，即直接安装的它的主分支版本，即 PyQt5 版本的：

pip install \"PyQt-Fluent-Widgets[full]\" -i https://pypi.org/simple/p

那么此时，笔者来到 QFluent Widgets 的项目仓库中，就需要下载对应 PyQt5 的分支代码：

将对应分支的压缩包下载并解压后，我们就可以尝试运行 examples 目录下的任意示例程序，比如：

cd examples/gallerypython demo.py

如果遇到 ImportError: cannot import name \'XXX\' from \'qfluentwidgets\'，这表明安装的包版本过低，可以按照上面的安装指令将 pypi 源替换为 https://pypi.org/simple 并重新安装最新版本的包。

0x0402：如何入门

这里的入门其实是建立在你已经有了 PyQT or PySide 开发的基础上的，该库其实就是做了个封装，写了一堆实用好看的小组件，帮我们减少了写 QSS 的时间。下面是针对该组件库快速入门的一些小窍门：

  1. 掌握 Qt 的信号槽机制、事件机制、按钮和输入框等常用组件的实用。

  2. 安装组件库并下载 GitHub 仓库 源代码（上面一步我已经带你们做过了）。

  3. 阅读并运行 examples 文件夹中的示例。

  4. 阅读官网文档（包的，笔者后续会对官网进行详细的解读）。

提示

除了 InfoBar、Pivot 和 FluentWindow 等自定义组件需要阅读文档外，按钮、输入框和标签这种组件仅仅是修改了样式表或重写了 paintEvent，API 与 Qt 内置组件保持一致，只要修改类名为 QFluentWidgets 的组件名即可，没有任何额外的学习成本。

网络标签：

相关问题