在 Windows 上分发基于 Qt Quick 的桌面程序时,这个体积不大的 DLL 往往是“界面能不能出来”的关键一环。它是 Qt Quick Controls 2 样式体系中的一块拼图,平时不显眼,一旦缺失却会让程序直接“失声”。
1. 样式插件注册。它遵循 Qt 的插件加载机制,通过 Q_PLUGIN_METADATA 与 QML 扩展插件接口,把“Fusion”注册为一个可用的样式名,使 QQuickStyle::setStyle("Fusion") 或 qml 中的 style 参数能够被正确解析。
2. 提供控件实现。内部实现 FusionStyle 单例、Fusion 主题的调色板,以及 Button、CheckBox、Slider、ScrollBar、ComboBox 等控件的 QML 组件与 C++ 绘制逻辑,负责边框、圆角、渐变、焦点框、阴影等视觉细节。
3. 主题与度量定义。规定默认的高亮色、背景色、禁用态颜色,以及控件最小尺寸、内边距与行高,保证不同平台上获得统一的桌面级观感。
4. 与主模块协同。依赖 qtquickcontrols2.dll、qtquickcontrols2plugin.dll 与 Qt5QuickTemplates2.dll,共同对外暴露 QtQuick.Controls 模块的完整能力。
5. 运行时按需加载。当应用或系统指定 Fusion 样式时被动态载入;未指定时则按平台默认样式(Windows 通常为 Windows 样式)加载,两者可互为替换。
启动阶段:控制台或日志抛出 Failed to load plugin、module "QtQuick.Controls.Fusion" is not installed、cannot load library 一类错误,QML 引擎无法完成模块解析。
界面层面:控件回退到 Basic 或其它样式,出现配色、尺寸、圆角与设计稿明显不符,甚至出现空白窗口、控件不可见、布局塌陷。
显式指定 Fusion 时:进程可能在启动瞬间崩溃或直接退出,用户侧只能看到程序一闪而过,几乎没有可读的错误提示。
部署环节:打包工具未收集 styles 目录下的插件文件,造成开发机运行正常、客户机一打开就失败的经典问题。
排查思路:核对 Qt 安装目录 qml/QtQuick/Controls.2/Fusion/ 下的 DLL 与 plugins.qmltypes 是否齐全,确认运行库与编译器(MSVC / MinGW)版本一致,避免不同 Qt 版本的文件混用。