QtFluentWidgets: 一套基于C++ Qt Widgets的Fluent Design风格控件库

QtFluentWidgets（也称QFluentWidgets ）是一套基于C++ Qt Widgets 的Fluent Design风格控件库，由 Type3limit 开发维护，提供统一的主题 / 色板管理与超过 150 个开箱即用的现代控件，旨在帮助开发者快速构建 Windows 11 风格的精美界面，无需编写复杂 QSS 样式表。

该库与 Python 版本的 PyQt-Fluent-Widgets 同源，共享设计理念但针对 C++ 生态优化，支持 Qt5/Qt6 无缝兼容，CMake 自动探测版本，提供完整的 Qt Designer 插件支持，让开发者可通过拖拽方式快速构建界面。

它的主要特性有：

Qt5 / Qt6 兼容（CMake 自动探测 Qt6，否则使用 Qt5）。
统一主题与色板：ThemeManager + ThemeColors。
Fluent 风格输入控件面板：通过 Style::paintControlSurface() 统一圆角/边框/focus ring。
内置日期范围选择器 FluentDateRangePicker，支持双面板范围选择与可配置 prefix / suffix / separator。
窗口层支持 FluentMainWindow 自定义标题栏插槽、Windows 11 风格 accent 描边 / trace 动画，以及菜单栏嵌入标题栏。
Demo 覆盖所有控件，并带侧边栏联动配置（含 CodeEditor 的 clang-format 路径配置）。
可选 Qt Designer 插件（默认开启构建）。

2.编译与集成

2.1.依赖

CMake >= 3.16
Qt Widgets（Qt5 或 Qt6）
Qt Svg、Qt UiPlugin（用于 Demo / Designer 插件）

2.2.构建方式（推荐 out-of-source）

cpp 复制代码

cmake -S . -B build
cmake --build build --config Release

如果你的 Qt 没有在默认搜索路径中，可传入 CMAKE_PREFIX_PATH（示例：Windows）：

cpp 复制代码

cmake -S . -B build -DCMAKE_PREFIX_PATH="C:/Qt/6.6.0/msvc2019_64"
cmake --build build --config Release

或

cmake -S . -B build -DQt6_DIR="C:/Qt/6.6.0/msvc2019_64"
cmake --build build --config Release

在执行 cmake --build build --config Release 的时候会报错，排查原因是有些源码文件的编码不对，改为下面格式的文件即可：

经过修改后的源码可通过下面的链接下载：

通过网盘分享的文件：QtFluentWidgets.zip

链接: https://pan.baidu.com/s/1N2POFDjbWvKmzCVhenk8sA?pwd=1234 提取码: 1234

最后编译成功，运行 Demo:

CMake target：QtFluentDemo
也可以使用仓库提供的自定义 target：run-QtFluentDemo（会设置少量 demo 用的 env）

2.3.项目集成方式

方式 A：add_subdirectory（最简单）

cpp 复制代码

add_subdirectory(path/to/QtFluent)

target_link_libraries(your_app PRIVATE QtFluentWidgets)

然后在代码里包含头文件（均位于 include/Fluent/）：

cpp 复制代码

#include "Fluent/FluentButton.h"
#include "Fluent/FluentDateRangePicker.h"
#include "Fluent/FluentTheme.h"

using namespace Fluent;

auto *rangePicker = new FluentDateRangePicker();
rangePicker->setDateRange(QDate::currentDate(), QDate::currentDate().addDays(7));
rangePicker->setStartPrefix(QStringLiteral("开始："));
rangePicker->setSeparator(QStringLiteral("  至  "));
rangePicker->setEndPrefix(QStringLiteral("结束："));

方式 B：作为源码依赖

直接把 include/、src/ 和 CMakeLists.txt 作为子模块/源码依赖引入即可。

2.4.Qt Designer 插件配置

默认会构建 Designer 插件，输出到build/designer/目录
将插件文件复制到 Qt Designer 的插件目录（如C:/Qt/6.6.0/msvc2019_64/plugins/designer/）
重启 Qt Designer 即可在左侧面板看到 "QFluentWidgets Components" 分组
关闭插件构建：

cpp 复制代码

cmake -S . -B build -DFLUENT_BUILD_DESIGNER_PLUGIN=OFF

3.核心组件分类详解

3.1.基础控件

按钮与开关

FluentButton：Fluent 风格按钮，支持 hover/press/checked 状态动画，可设置图标与文本组合
FluentCheckBox：带行高亮与勾选淡入动画的复选框，支持三态选择
FluentRadioButton：单选按钮，优化选中指示器动画与焦点环显示
FluentSwitchButton：Win11 风格开关，支持平滑切换动画与状态提示

文本与标签

FluentLabel：自动跟随主题更新颜色的文本标签，保留自定义样式表能力
BodyLabel/CaptionLabel：预设字体大小的文本标签，符合 Fluent 设计规范

3.2.容器与布局

核心容器

FluentCard：支持折叠 / 展开的卡片容器，自动管理内容布局，折叠时有平滑动画

cpp 复制代码

auto *card = new Fluent::FluentCard();
card->setTitle("标题");
card->setCollapsible(true);
card->contentLayout()->addWidget(yourWidget); // 添加内容

FluentGroupBox：Fluent 风格分组框，自动适配主题边框与标题样式

布局系统

FluentFlowLayout：自适应换行布局，支持统一项宽、列数迟滞、几何动画与节流机制

cpp 复制代码

auto *flow = new Fluent::FluentFlowLayout(host, 0, 12, 12);
flow->setUniformItemWidthEnabled(true); // 统一项宽
flow->setMinimumItemWidth(320); // 最小项宽

FluentSplitter：自定义分割条，支持 hover 动效与 Win11 风格三点 grip，背景透明

滚动与导航

FluentScrollArea：带透明视口与 overlay 滚动条的滚动容器，支持自动隐藏滚动条
FluentAnnotatedScrollBar：分段标注滚动条，支持快速跳转与当前范围提示，类似 WinUI AnnotatedScrollBar

3.3.输入与编辑控件

文本输入

FluentLineEdit：单行输入框，统一绘制圆角表面 + 边框 + 焦点环，支持 hover/focus 动效
FluentTextEdit：多行文本编辑器，使用透明边框覆盖层确保边框始终在内容之上

选择与数值输入

FluentComboBox：下拉选择框，重写弹层与委托，支持圆角与 Fluent 风格 hover/selected 状态
FluentSpinBox/FluentDoubleSpinBox：数字输入框，自定义右侧步进器，支持 hover 反馈
FluentSlider：滑动条，支持点击轨道跳转 + 平滑动画过渡，handle hover 时放大并显示 accent 内点
FluentProgressBar：细条进度条，支持值变化平滑过渡，文本可显示在左 / 中 / 右或隐藏

专业输入控件

FluentDial：圆形角度旋钮，适合渐变角度、旋转角度选择，支持刻度显示
FluentAngleSelector：一体化角度编辑器，组合标签 + 旋钮 + 数值框，支持双向同步

3.4.窗口与导航系统

主窗口

FluentMainWindow：自定义标题栏，支持菜单栏嵌入、标题栏插槽、Windows 11 风格 accent 描边与无边框调整

导航控件

FluentNavigationView：层级导航视图，支持数据模型、父子项交互、glyph 图标，可配置自动折叠行为
FluentTabWidget：Win11 设置风格选项卡，包含切换动效、导航指示器动画与 frame overlay

对话框与弹出层

FluentDialog：Fluent 风格对话框，支持自定义按钮、圆角与阴影效果
Flyout：轻量级弹出层，支持多种位置与动画，适合显示上下文操作或简短信息
InfoBar：信息提示条，支持多种类型（信息 / 成功 / 警告 / 错误）与自动消失功能

3.5.选择器与日期控件

FluentDateRangePicker：日期范围选择器，支持双面板范围选择与可配置前缀 / 后缀 / 分隔符

cpp 复制代码

auto *rangePicker = new Fluent::FluentDateRangePicker();
rangePicker->setDateRange(QDate::currentDate(), QDate::currentDate().addDays(7));
rangePicker->setStartPrefix("开始：");
rangePicker->setSeparator(" 至 ");
rangePicker->setEndPrefix("结束：");

FluentCalendarPopup：日历弹出控件，支持范围选择与自定义日期格式

4.主题管理与样式定制

4.1.主题基础操作

cpp 复制代码

#include "Fluent/FluentTheme.h"

// 切换亮暗模式
ThemeManager::instance()->setThemeMode(ThemeMode::LIGHT);
ThemeManager::instance()->setThemeMode(ThemeMode::DARK);

// 自动跟随系统主题
ThemeManager::instance()->setThemeMode(ThemeMode::AUTO);

// 设置自定义主题色
ThemeManager::instance()->setThemeColor(QColor("#0078D4")); // Windows默认蓝色

4.2.主题监听与自定义

cpp 复制代码

// 监听主题变化
connect(ThemeManager::instance(), &ThemeManager::themeChanged, this, [this]() {
    // 自定义主题响应逻辑
    updateStyle();
});

// 获取当前主题颜色
QColor accentColor = ThemeManager::instance()->themeColors().accent;
QColor textColor = ThemeManager::instance()->themeColors().text;

4.3.样式定制最佳实践

避免直接修改控件 styleSheet：使用 ThemeManager 统一管理颜色
自定义控件继承：继承 Fluent::FluentWidget，重写 paintEvent 使用 ThemeColors 绘制
动画参数调整：通过控件的 hoverLevel、focusLevel 等 Q_PROPERTY 定制动画效果

5.高级用法

1.窗口定制示例

cpp 复制代码

#include "Fluent/FluentMainWindow.h"

class MyMainWindow : public Fluent::FluentMainWindow
{
    Q_OBJECT
public:
    MyMainWindow(QWidget *parent = nullptr) : FluentMainWindow(parent)
    {
        // 启用Fluent标题栏
        setFluentTitleBarEnabled(true);
        
        // 自定义标题栏内容
        auto *titleLabel = new Fluent::FluentLabel("我的应用");
        titleBar()->addWidget(titleLabel, Qt::AlignCenter);
        
        // 启用accent描边
        setAccentBorderEnabled(true);
        
        // 初始化导航
        initNavigation();
    }
    
private:
    void initNavigation()
    {
        // 添加导航项
        addSubInterface(new HomeInterface(), QIcon(":/icons/home.svg"), "首页");
        addSubInterface(new SettingsInterface(), QIcon(":/icons/settings.svg"), "设置");
        
        // 添加分隔符
        navigationInterface()->addSeparator();
    }
};

2.性能优化建议

动画优化：
- 复杂界面可禁用非关键动画：setAnimationEnabled(false)
- 布局动画启用节流机制：setAnimationThrottle(50)（默认 50ms）
内存管理：
- 重用动画对象：FluentFlowLayout 等控件会缓存 QPropertyAnimation 减少频繁创建销毁
- 避免过度使用亚克力效果：在低端设备上可能影响性能
绘制优化：
- 自定义控件使用QPainter::setRenderHint(QPainter::Antialiasing)时注意性能平衡
- 利用 FluentWidget 的 BackgroundRole 统一管理背景绘制

3.跨平台注意事项

Windows：完美支持 Fluent Design 所有特性，包括 accent 颜色、亚克力效果
Linux/macOS：部分系统特有效果（如亚克力）会自动降级为等效视觉效果
Qt 版本兼容：建议使用 Qt 5.15 + 或 Qt 6.2 + 以获得最佳体验

6.总结

QtFluentWidgets 为 C++ Qt 开发者提供了一套完整的 Fluent Design 解决方案，通过统一的主题管理、丰富的控件库和流畅的动画系统，大幅降低了现代 UI 开发的门槛。无论是开发企业级应用、科研工具还是个人项目，都能快速构建出符合 Windows 11 设计语言的精美界面。

QtFluentWidgets: 一套基于C++ Qt Widgets的Fluent Design风格控件库

1.简介

2.编译与集成

2.1.依赖

2.2.构建方式（推荐 out-of-source）

2.3.项目集成方式

2.4.Qt Designer 插件配置

3.核心组件分类详解

3.1.基础控件

3.2.容器与布局

3.3.输入与编辑控件

3.4.窗口与导航系统

3.5.选择器与日期控件

4.主题管理与样式定制

4.1.主题基础操作

4.2.主题监听与自定义

4.3.样式定制最佳实践

5.高级用法

6.总结

相关资源与链接