告别AWT系统托盘菜单乱码：用JavaFX自定义窗口打造完美体验

对于 Java 桌面应用程序开发者来说，java.awt.SystemTray 提供了一个与操作系统原生托盘交互的标准方式，允许我们创建托盘图标并在用户点击时显示菜单。然而，标准的 PopupMenu 实现（同样基于 AWT）常常带来一系列令人头疼的问题，尤其是在跨平台和处理非 ASCII 字符（如中文）时。

你是否遇到过托盘菜单项显示为 乱码 或 空白方框？是否觉得 AWT 菜单的 样式单一，难以与你精心设计的 JavaFX 应用界面融合？是否厌倦了为不同操作系统处理 细微的行为差异？

如果你对以上任何一个问题点头，那么本文将为你介绍一种 优雅且强大的解决方案：彻底抛弃 AWT 的 PopupMenu，转而使用一个自定义的、无边框的 JavaFX Stage 来模拟托盘菜单！

问题根源：为何 AWT 托盘菜单如此“顽固”？

标准的 SystemTray 和 PopupMenu 依赖于底层的 AWT (Abstract Window Toolkit) 实现，而 AWT 本身是 Java 与操作系统原生 GUI 组件交互的一层封装。这导致了以下几个核心痛点：

1. 编码问题 (乱码/空白框的元凶):
   • Java 内部通常使用 UTF-16 处理字符串。
   • AWT 在将菜单文本传递给操作系统原生 API 时，需要进行编码转换。
   • 在非 UTF-8 为系统默认编码的环境下（尤其是 Windows，简体中文版默认可能是 GBK/GB2312），如果 JVM 启动参数（如 -Dsun.jnu.encoding）设置不当，或者 AWT 与特定操作系统版本的原生接口交互存在 Bug，就极易发生编码错误，导致中文等字符显示为乱码或无法渲染（显示为空白框）。即便尝试了各种 JVM 参数，有时问题依然存在。
2. 样式限制:
   • AWT 菜单的外观基本由操作系统决定，你几乎无法通过 Java 代码对其进行自定义样式设置（如字体、颜色、背景、图标等），难以实现与 JavaFX 应用统一的视觉风格。
3. 平台差异性:
   • 不同操作系统对托盘菜单的渲染和行为可能有细微差别，增加了跨平台测试和兼容性调整的负担。
4. 与 JavaFX 的“隔阂”:
   • 在 JavaFX 应用中混用 AWT 组件需要处理线程问题（AWT EDT vs JavaFX Application Thread），增加了代码复杂性。事件处理和 UI 更新需要在不同线程间小心切换。

解决方案：JavaFX 自定义窗口登场！

既然 AWT 的路不好走，何不另辟蹊径？我们的核心思路是：

• 保留 java.awt.TrayIcon： 我们仍然需要它来显示托盘图标和接收鼠标事件。
• 移除 java.awt.PopupMenu： 不再使用 AWT 的菜单。
• 监听鼠标事件： 给 TrayIcon 添加 MouseListener，捕获右键点击事件。
• 创建自定义 JavaFX Stage： 当检测到右键点击时，动态创建一个小巧的、无边框的 (StageStyle.UNDECORATED) JavaFX Stage。
• 模拟菜单项： 在这个自定义 Stage 内部，使用 JavaFX 的 Button 或其他控件来模拟菜单项，并为它们绑定相应的动作（如显示/隐藏主窗口、退出应用）。
• 精确定位： 将这个自定义 Stage 显示在鼠标点击的位置附近（通常在鼠标指针上方）。
• 自动隐藏： 当这个自定义 Stage 失去焦点时（例如用户点击了别处或菜单项），自动将其隐藏。

这样一来，菜单的创建、渲染、样式和交互逻辑完全由 JavaFX 接管，彻底摆脱了 AWT 的限制和潜在问题。

实现步骤详解

下面我们将通过关键代码片段展示如何实现这个方案。

第一步：创建自定义菜单窗口 (CustomTrayMenu.java)

这个类继承自 javafx.stage.Stage，负责呈现菜单本身。

import javafx.application.Platform;
import javafx.geometry.Insets;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.layout.VBox;
import javafx.stage.Stage;
import javafx.stage.StageStyle;

public class CustomTrayMenu extends Stage {

    private final Stage primaryStage; // 主窗口引用
    private final Runnable exitAction; // 退出应用的回调

    public CustomTrayMenu(Stage primaryStage, Runnable exitAction) {
        this.primaryStage = primaryStage;
        this.exitAction = exitAction;
        initUI();
        setupAutoHide();
    }

    private void initUI() {
        // 设置为无边框窗口
        initStyle(StageStyle.UNDECORATED);
        setAlwaysOnTop(true); // 保持在最前

        // 使用 VBox 垂直排列按钮
        VBox root = new VBox(2); // 间距为 2
        root.setPadding(new Insets(5));
        // 设置背景和边框，模仿菜单外观
        root.setStyle("-fx-background-color: #f4f4f4; -fx-border-color: #a0a0a0; -fx-border-width: 1;");

        // 创建菜单按钮
        Button showHideButton = createMenuButton("显示/隐藏窗口"); // \u显\u示...
        showHideButton.setOnAction(e -> {
            togglePrimaryWindow();
            hide(); // 点击后隐藏菜单
        });

        Button exitButton = createMenuButton("退出"); // \u9000\u51fa
        exitButton.setOnAction(e -> {
            if (exitAction != null) exitAction.run();
        });

        root.getChildren().addAll(showHideButton, exitButton);
        setScene(new Scene(root));
    }

    // 辅助方法：创建按钮并设置基础样式
    private Button createMenuButton(String text) {
        Button button = new Button(text);
        button.setMaxWidth(Double.MAX_VALUE);
        button.setStyle("-fx-background-color: transparent; -fx-border-color: transparent; -fx-alignment: center-left;");
        // 可选：添加悬停效果 (最好用 CSS)
        button.setOnMouseEntered(e -> button.setStyle("-fx-background-color: #d0d0d0; -fx-border-color: transparent; -fx-alignment: center-left;"));
        button.setOnMouseExited(e -> button.setStyle("-fx-background-color: transparent; -fx-border-color: transparent; -fx-alignment: center-left;"));
        return button;
    }

    // 辅助方法：切换主窗口可见性
    private void togglePrimaryWindow() {
         if (primaryStage == null) return;
        if (primaryStage.isShowing()) {
            primaryStage.hide();
        } else {
            Platform.runLater(() -> { primaryStage.show(); primaryStage.toFront(); });
        }
    }

    // 辅助方法：设置失去焦点时自动隐藏
    private void setupAutoHide() {
        focusedProperty().addListener((obs, wasFocused, isNowFocused) -> {
            if (!isNowFocused) {
                hide();
            }
        });
    }

    // 显示菜单在指定屏幕坐标 (鼠标指针上方)
    public void showMenu(double screenX, double screenY) {
         setOpacity(0); // 先透明显示，用于计算尺寸
         show();
         Platform.runLater(()->{ // 在下一帧定位
             double adjustedY = screenY - getHeight();
             if (adjustedY < 0) adjustedY = screenY; // 防止超出屏幕顶部
             setX(screenX - 5); // 稍微左移
             setY(adjustedY);
             setOpacity(1); // 恢复不透明
             toFront();
             requestFocus(); // 请求焦点以实现自动隐藏
         });
    }
}

第二步：修改托盘管理器 (TrayManager.java)

此类负责创建 TrayIcon 并处理其事件。

import javafx.application.Platform;
import javafx.stage.Stage;
import java.awt.*;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import javax.swing.SwingUtilities; // 用于可靠地判断鼠标按键

public class TrayManager {
    // ... (iconPath, appName, primaryStage, exitAction 定义)
    private TrayIcon trayIcon;
    private CustomTrayMenu customMenu; // 持有自定义菜单的引用

    public TrayManager(Stage primaryStage, Runnable exitAction) {
        this.primaryStage = primaryStage;
        this.exitAction = exitAction;
    }

    public void addAppToTray() {
        // ... (检查 SystemTray.isSupported(), 加载图标 Image)

        // 创建 TrayIcon，不再传入 PopupMenu
        trayIcon = new TrayIcon(image, appName);
        trayIcon.setImageAutoSize(true);

        // 添加鼠标监听器
        trayIcon.addMouseListener(new MouseAdapter() {
            @Override
            public void mousePressed(MouseEvent e) {
                // 判断是否是右键点击
                if (SwingUtilities.isRightMouseButton(e)) {
                    final double screenX = e.getXOnScreen();
                    final double screenY = e.getYOnScreen();
                    // 在 JavaFX 线程中显示自定义菜单
                    Platform.runLater(() -> showCustomMenu(screenX, screenY));
                } else if (e.getClickCount() == 2 && SwingUtilities.isLeftMouseButton(e)) {
                    // 处理双击左键 (例如，切换主窗口)
                    Platform.runLater(TrayManager.this::togglePrimaryWindowInternal); // 新增内部方法
                }
            }
        });

        // 添加到系统托盘
        try {
            SystemTray.getSystemTray().add(trayIcon);
        } catch (AWTException e) { /* ... 处理错误 ... */ }
    }

    // 显示自定义菜单的方法
    private void showCustomMenu(double screenX, double screenY) {
        if (customMenu == null) {
            // 延迟创建，确保在 JavaFX 线程
            customMenu = new CustomTrayMenu(primaryStage, exitAction);
        }
        if (customMenu.isShowing()) {
            customMenu.hide(); // 如果已显示，先隐藏
        }
        customMenu.showMenu(screenX, screenY);
    }

    // 内部使用的切换窗口方法 (也可被 CustomTrayMenu 间接调用)
    private void togglePrimaryWindowInternal() {
         if (primaryStage == null) return;
        if (primaryStage.isShowing()) {
            primaryStage.hide();
            updateTooltip("主窗口已隐藏"); // 更新提示
        } else {
            primaryStage.show();
            primaryStage.toFront();
            updateTooltipBasedOnServiceStatus(); // 更新提示
        }
    }

    // ... (removeFromTray, updateTooltip, loadImage 等方法)

     // 根据服务状态更新提示信息 (需要从别处获取状态)
    public void updateTooltipBasedOnServiceStatus() {
        // String currentStatus = ... ; // 获取当前状态
        // updateTooltip(currentStatus);
        updateTooltip("状态正常"); // 示例
    }

     public void updateTooltip(String tooltip) {
         if (trayIcon != null) {
             String finalTooltip = appName + " - " + tooltip;
             if (primaryStage != null && !primaryStage.isShowing()) {
                 finalTooltip += " (已隐藏)";
             }
             trayIcon.setToolTip(finalTooltip);
         }
     }

     public void removeFromTray() {
         if (trayIcon != null) {
             SystemTray.getSystemTray().remove(trayIcon);
             trayIcon = null;
             if (customMenu != null && customMenu.isShowing()) {
                 Platform.runLater(customMenu::hide);
             }
             customMenu = null;
         }
     }
}

第三步：（可选）使用 CSS 美化菜单

在你的 JavaFX CSS 文件中添加样式，让按钮看起来更像菜单项。

/* styles.css */
.tray-menu-button { /* 在 CustomTrayMenu.createMenuButton 中添加这个类 */
    -fx-background-color: transparent;
    -fx-background-radius: 0;
    -fx-border-color: transparent;
    -fx-text-fill: black;
    -fx-alignment: center-left;
    -fx-padding: 5 10 5 10; /* 上下 5，左右 10 */
}

.tray-menu-button:hover {
    -fx-background-color: #e0e0e0; /* 悬停效果 */
}

.tray-menu-button:pressed {
    -fx-background-color: #c0c0c0; /* 按下效果 */
}

别忘了在 CustomTrayMenu 的 initUI 方法中加载这个 CSS 文件到 Scene 上。

这种方法的优势

• 告别乱码/空白框： 菜单文本完全由 JavaFX 渲染，只要你的 JavaFX 环境能正常显示中文，菜单就能正常显示。
• 完全的样式控制： 使用 CSS 可以轻松定制菜单的字体、颜色、背景、边框、间距，甚至添加图标，实现与主应用完美统一的视觉风格。
• 一致的交互体验： 菜单项的行为（点击、悬停等）由 JavaFX 事件处理，更加可靠和一致。
• 纯粹的 JavaFX： 减少了对 AWT 的依赖，简化了线程管理，代码逻辑更清晰。
• 跨平台更可靠： JavaFX 本身的跨平台性比 AWT 的原生依赖更好，这种方法有助于减少平台相关的菜单问题。

注意事项

• 非原生外观： 这种菜单的外观是你自己定义的，可能与操作系统自带的原生菜单看起来不同（但这通常是优点）。
• 焦点处理： setupAutoHide() 中的焦点丢失检测是关键，需要确保其行为在各种交互下都符合预期。
• 首次显示延迟（极小）： showMenu 中利用 Platform.runLater 来确保窗口尺寸计算正确后再定位，可能会有几乎无法察觉的微小延迟。
• 初始设置： 相较于直接使用 PopupMenu，这种方法需要编写更多的代码来创建和管理自定义窗口。

总结

当标准的 java.awt.SystemTray 菜单因编码、样式或平台兼容性问题让你头疼时，使用一个自定义的、无边框的 JavaFX Stage 来模拟菜单是一个非常有效且灵活的解决方案。它不仅能彻底解决乱码等顽固问题，还能让你完全掌控菜单的外观和行为，提升应用程序的整体质量和用户体验。

虽然需要一些额外的开发工作，但由此带来的稳定性、可定制性和一致性是完全值得的。下次当你需要为 JavaFX 应用添加系统托盘菜单时，不妨试试这个方法吧！

---