Java 實現系統托盤功能完整指南：源碼解析與圖文詳解

系統托盤 是桌面應用常見的「最小化到托盤、後台常駐、右鍵菜單交互」功能。Java 自 JDK 6 起通過 java.awt.SystemTray、TrayIcon、PopupMenu 提供原生支持。本文提供完整可運行的 Maven 專案結構、核心邏輯解析、關鍵 API 詳解及常見坑點指南。

一、 專案結構與效果預覽

src/main/java/org/pdp/frame/
├── MainFrame.java          // 主窗體 + 托盤邏輯
└── resources/
    └── systray.jpg         // 托盤圖標 (16x16 或 24x24 建議)

運行效果：

• 啟動顯示主窗體「電話薄」
• 點擊菜單「置於托盤」 → 窗體隱藏，托盤區顯示圖標
• 右鍵托盤圖標 → 彈出菜單「顯示窗體」「退出系統」
• 點擊「顯示窗體」 → 窗體恢復顯示

二、 核心邏輯深度解析

1. 托盤支持性檢查 —— 必須首行

if (!SystemTray.isSupported()) {
    System.err.println("當前系統不支持 SystemTray！");
    return; // 或降級處理
}

注意：部分 Linux 桌面環境（如無托盤的 Window Manager）會返回 false，需做降級預案。

2. 圖標資源加載 —— 推薦 ClassLoader 方式

URL imgUrl = getClass().getResource("/systray.jpg"); // 放在 resources 根目錄
if (imgUrl == null) throw new IllegalStateException("找不到托盤圖標資源！");
Image image = new ImageIcon(imgUrl).getImage();

避免使用相對路徑 new File("...")，打包成 JAR 後會失效。

3. 彈出菜單構建 —— AWT 組件而非 Swing

PopupMenu popup = new PopupMenu(); // 必須用 java.awt.PopupMenu
MenuItem showItem = new MenuItem("顯示窗體");
MenuItem exitItem = new MenuItem("退出系統");
popup.add(showItem);
popup.add(exitItem);

關鍵點：TrayIcon 構造函數要求 PopupMenu (AWT)，而非 JPopupMenu (Swing)。混用會導致菜單不顯示或異常。

4. 托盤圖標註冊與異常處理

TrayIcon trayIcon = new TrayIcon(image, "電話薄系統", popup);
trayIcon.setImageAutoSize(true); // 自適應縮放

SystemTray tray = SystemTray.getSystemTray();
try {
    tray.add(trayIcon);
} catch (AWTException e) {
    logger.error("托盤圖標註冊失敗", e);
    // 降級：最小化到任務欄、通知用戶等
}

5. 窗體顯示/隱藏邏輯

// 菜單「置於托盤」→ 隱藏窗體
if ("置於托盤".equals(cmd)) setVisible(false);

// 托盤菜單「顯示窗體」→ 顯示並置頂
showItem.addActionListener(e -> {
    setVisible(true);
    toFront(); // 關鍵：確保窗體在最上層
});

6. 退出系統 —— 徹底銷毀資源

exitItem.addActionListener(e -> {
    tray.remove(trayIcon); // 移除托盤圖標，避免殘留
    System.exit(0);
});

三、 完整可運行源碼

package org.pdp.frame;

import java.awt.*;
import java.awt.event.*;
import java.net.URL;
import javax.swing.*;

public class MainFrame extends JFrame implements ActionListener {
    private static final long serialVersionUID = 1L;
    private JMenuBar menuBar;
    private JMenu sysMenu;
    private String[] menuNames = {"置於托盤", "系統退出"};

    public MainFrame() {
        super("電話薄");
        initUI();
        initSystemTray();
        setSize(500, 400);
        setLocationRelativeTo(null);
        setDefaultCloseOperation(JFrame.DO_NOTHING_ON_CLOSE); // 防止直接關閉繞過托盤
        addWindowListener(new WindowAdapter() {
            @Override public void windowClosing(WindowEvent e) { setVisible(false); }
        });
    }

    private void initUI() {
        sysMenu = new JMenu("系統窗體");
        for (String name : menuNames) {
            JMenuItem mi = new JMenuItem(name);
            mi.addActionListener(this);
            sysMenu.add(mi);
        }
        menuBar = new JMenuBar();
        menuBar.add(sysMenu);
        setJMenuBar(menuBar);
    }

    @Override
    public void actionPerformed(ActionEvent e) {
        String cmd = e.getActionCommand();
        if ("置於托盤".equals(cmd)) setVisible(false);
        else if ("系統退出".equals(cmd)) System.exit(0);
    }

    private void initSystemTray() {
        if (!SystemTray.isSupported()) return;
        URL imgUrl = getClass().getResource("/systray.jpg");
        if (imgUrl == null) return;
        Image image = new ImageIcon(imgUrl).getImage();

        PopupMenu popup = new PopupMenu();
        MenuItem show = new MenuItem("顯示窗體");
        MenuItem exit = new MenuItem("退出系統");
        show.addActionListener(ev -> { setVisible(true); toFront(); });
        exit.addActionListener(ev -> { SystemTray.getSystemTray().remove(trayIcon); System.exit(0); });
        popup.add(show); popup.add(exit);

        TrayIcon trayIcon = new TrayIcon(image, "電話薄系統", popup);
        trayIcon.setImageAutoSize(true);
        try { SystemTray.getSystemTray().add(trayIcon); }
        catch (AWTException ex) { ex.printStackTrace(); }
    }

    public static void main(String[] args) {
        SwingUtilities.invokeLater(() -> new MainFrame().setVisible(true));
    }
}

四、 常見坑點與最佳實踐

五、 進階擴展方向

• 托盤氣泡通知：trayIcon.displayMessage("標題", "內容", TrayIcon.MessageType.INFO)
• 雙擊托盤圖標恢復窗體：trayIcon.addMouseListener(new MouseAdapter() { public void mouseClicked(MouseEvent e) { if (e.getClickCount() == 2) { setVisible(true); toFront(); } } })
• 動態更新圖標/提示文本：trayIcon.setImage(newImage)、trayIcon.setToolTip("新提示")
• 跨平台統一體驗：引入 JTray 或 SystemTray 增強庫 彌補原生 API 差異。