Qt Quick 系统托盘完整实践

Qt Quick 系统托盘完整实践：最小化到托盘、恢复最大化、右键退出与 QApplication 选择

一、需求简述

在 Qt Quick 桌面应用里实现：

关闭时可选"最小化到系统托盘"而不是退出；
从托盘恢复时保持之前的窗口状态（例如最大化）；
托盘图标右键菜单中有"退出"项，可真正退出程序；
避免 QML 报错（如 Menu 类型冲突、visible/visibility 冲突）。

过程中会涉及：用 QApplication 还是 QGuiApplication ，以及 Qt.labs.platform 的用法。

二、为什么推荐用 QApplication（而不仅是 QGuiApplication）

2.1 官方说明

Qt 文档里写得很清楚：Qt.labs.platform 的很多功能（包括系统托盘）在"没有原生实现的平台"上会走 Qt Widgets 的 fallback。因此：

需要链接 Qt Widgets；
在 main() 里应使用 QApplication，而不是 QGuiApplication。

这样在 Windows 上，托盘图标和右键菜单才能稳定工作。

2.2 二者区别与影响

QApplication 继承自 QGuiApplication，因此原来基于 QGuiApplication 的 QML/Quick 用法都能继续用。
若项目已经因为 UI 库（如 Fluent 等）链接了 Qt Widgets，把 QGuiApplication 换成 QApplication 通常不会带来明显副作用，只是满足托盘菜单的运行环境要求。
若坚持只用 QGuiApplication，在 Windows 上可能出现：托盘图标能显示，但右键菜单不弹出或行为异常。

结论：要做"带菜单的系统托盘"，在 Windows 上建议使用 QApplication + 链接 Qt Widgets。

三、main 入口与 QML 的修改要点

3.1 C++：改用 QApplication

在 main.cpp 中：

#include <QApplication>（替代或补充 QGuiApplication）；
QApplication app(argc, argv);（替代 QGuiApplication app(argc, argv);）；
若存在接收 QGuiApplication& 的初始化函数，可改为接收 QApplication&（因 QApplication 继承 QGuiApplication，兼容）。

若同时 import QtQuick.Controls 和 import Qt.labs.platform，未加前缀时 Menu 会被解析成 QtQuick.Controls 的 Menu，而 SystemTrayIcon.menu 需要的是 Qt.labs.platform 的 Menu，会报错：

text 复制代码

无法分配类型为"Menu"的对象给"QQuickLabsPlatformMenu*"类型的属性

做法：给 Qt.labs.platform 加别名，全部用"平台"类型：

qml 复制代码

import Qt.labs.platform 1.1 as Platform

Platform.SystemTrayIcon {
    id: systemTrayIcon
    visible: true
    icon.source: "qrc:/toolbox.svg"

    menu: Platform.Menu {
        id: trayMenu
        Platform.MenuItem {
            id: exitItem
            text: qsTr("Exit")
            onTriggered: {
                systemTrayIcon.visible = false
                Qt.quit()
            }
        }
    }

    onActivated: (reason) => {
        if (reason === Platform.SystemTrayIcon.Trigger) {
            window.show()
            window.visibility = window._visibilityBeforeTray
            window.raise()
            window.requestActivate()
        } else if (reason === Platform.SystemTrayIcon.Context) {
            trayMenu.open(exitItem)
        }
    }
}

这样 menu 绑定的是正确的平台 Menu，右键会弹出菜单。

3.3 解决 ApplicationWindow 的 visible / visibility 冲突

若同时设置 visible: true 和 visibility: Window.xxx，可能报"Conflicting properties 'visible' and 'visibility'"。

做法：只使用 visibility ，不用 visible。例如：

初始：visibility: Window.Windowed；
最小化到托盘前：保存 _visibilityBeforeTray = visibility，再 hide()；
从托盘恢复时：window.visibility = window._visibilityBeforeTray。

这样既能恢复最大化，又避免冲突。

四、功能实现汇总

4.1 最小化到托盘（不退出）

在 ApplicationWindow 的 onClosing 里根据设置决定是"隐藏到托盘"还是"真正退出"：

若勾选"最小化到托盘"：
close.accepted = false，保存 _visibilityBeforeTray = visibility，显示托盘图标并 hide()。
否则：隐藏托盘图标，close.accepted = true，Qt.quit()。

4.2 恢复时保持最大化

用属性保存隐藏前的状态：property int _visibilityBeforeTray: Window.Windowed；
在 onClosing （在 hide() 前）写：_visibilityBeforeTray = visibility；
托盘 onActivated(Trigger) 里：window.show() 后执行 window.visibility = window._visibilityBeforeTray，再 raise()、requestActivate()。

这样用户最大化后最小化到托盘，再双击托盘图标会恢复为最大化。

4.3 右键"退出"

给 SystemTrayIcon 设置 menu 为 Platform.Menu ，内加 Platform.MenuItem "Exit"，onTriggered 里隐藏托盘并 Qt.quit()；
在 onActivated 里对 Platform.SystemTrayIcon.Context 调用 trayMenu.open(exitItem)，保证右键能弹出菜单（在部分环境下需显式处理 Context）。

五、不用 Qt.labs.platform 的替代方案

若不想用 Qt.labs.platform：

可在 C++ 里使用 QSystemTrayIcon + QMenu （Qt Widgets），在 QApplication 下创建托盘和菜单；
通过 QObject 暴露"显示/隐藏主窗口""退出"等接口给 QML 调用；
这样 QML 侧不再使用 SystemTrayIcon/Menu，完全由 C++ 控制托盘和菜单。

适合希望减少 QML 与 labs 模块依赖、或需要更细粒度控制的场景。

六、小结

系统托盘 + 右键菜单 在 Windows 上建议：QApplication + Qt Widgets，否则菜单可能不工作。
QML 里用 Qt.labs.platform 时，建议 as Platform 并统一使用 Platform.SystemTrayIcon / Menu / MenuItem，避免与 QtQuick.Controls 的 Menu 冲突。
窗口状态用 visibility 保存与恢复，避免 visible 与 visibility 冲突。
若遇到"自动登录/刷新 token 报 499"，实际可能是 502 等 HTTP 状态，可在 C++ 里打印 reply->error() 和 HttpStatusCodeAttribute 确认，并优先排查服务端或网关。

Qt Quick 系统托盘完整实践