Qt 系統托盤圖標實現完整指南

Qt 系統托盤圖標實現完整指南

在桌面應用開發中，系統托盤圖標是常見需求，允許程式在最小化時駐留後台，提供快速訪問入口。本文詳細介紹如何使用 Qt 框架實現系統托盤功能，包括圖標設置、右鍵菜單、點擊事件處理以及關閉行為控制。

核心類與成員變量

首先在主視窗類中聲明兩個關鍵成員變量：

QSystemTrayIcon *trayIcon;
QMenu *trayIconMenu;

QSystemTrayIcon 負責托盤圖標的顯示與交互，QMenu 則提供右鍵彈出菜單。

槽函數聲明

新增一個槽函數處理托盤圖標的點擊事件：

void onSystemTrayIconClicked(QSystemTrayIcon::ActivationReason reason);

構造函數初始化

在構造函數中完成初始化：

trayIcon = new QSystemTrayIcon(this);
QIcon icon(":/images/tray_icon.png"); // 建議使用資源文件路徑
trayIconMenu = new QMenu(this);

// 添加退出動作到菜單
trayIconMenu->addAction(ui->action_quit);
trayIconMenu->addSeparator();

// 設置圖標與提示
trayIcon->setIcon(icon);
trayIcon->setToolTip(tr("托盤測試"));
trayIcon->setContextMenu(trayIconMenu);
trayIcon->show();

// 顯示氣泡提示
trayIcon->showMessage(tr("提示"), tr("程式已最小化到托盤"), QSystemTrayIcon::Information, 5000);

// 連接信號與槽
connect(trayIcon, &QSystemTrayIcon::activated, this, &MainWindow::onSystemTrayIconClicked);

注意：圖標路徑建議使用 Qt 資源系統（:/images/...），避免硬編碼絕對路徑導致部署問題。

點擊事件處理

實現槽函數響應單擊/雙擊恢復視窗：

void MainWindow::onSystemTrayIconClicked(QSystemTrayIcon::ActivationReason reason) {
    switch (reason) {
    case QSystemTrayIcon::Trigger:     // 單擊
    case QSystemTrayIcon::DoubleClick: // 雙擊
        setWindowState(Qt::WindowActive);
        show();
        break;
    default:
        break;
    }
}

關閉事件重寫

重寫 closeEvent 實現「關閉按鈕最小化到托盤」而非退出程式：

void MainWindow::closeEvent(QCloseEvent *event) {
    if (trayIcon->isVisible()) {
        hide();
        event->ignore(); // 忽略關閉事件，防止程式退出
    }
}

退出菜單處理

點擊托盤菜單「退出」時真正關閉程式：

void MainWindow::on_action_quit_triggered() {
    trayIcon->hide(); // 隱藏托盤圖標
    qApp->quit();     // 退出應用程式
}

完整代碼結構

mainwindow.h

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include 
#include 
#include 
#include 

namespace Ui { class MainWindow; }

class MainWindow : public QMainWindow {
    Q_OBJECT
public:
    explicit MainWindow(QWidget *parent = nullptr);
    ~MainWindow();

protected:
    void closeEvent(QCloseEvent *event) override;

private slots:
    void onSystemTrayIconClicked(QSystemTrayIcon::ActivationReason reason);
    void on_action_quit_triggered();

private:
    Ui::MainWindow *ui;
    QSystemTrayIcon *trayIcon;
    QMenu *trayIconMenu;
};
#endif // MAINWINDOW_H

main.cpp

#include 
#include "mainwindow.h"

int main(int argc, char *argv[]) {
    QApplication a(argc, argv);
    MainWindow w;
    w.show();
    return a.exec();
}

關鍵點總結

• 使用 QSystemTrayIcon 實現跨平台托盤功能
• 圖標建議放入資源文件（.qrc）確保部署一致性
• 重寫 closeEvent 配合 event->ignore() 實現最小化到托盤
• 新式信號槽語法（&Class::signal）提供編譯期類型檢查
• 退出時需先隱藏托盤圖標再調用 qApp->quit()

完整示例代碼可參考 Qt 官方文檔中的 System Tray Icon Example。