企业官网建设流程全解析

• 文档
• 教程
• 游戏开发

StatusIndicator 是 Godot 引擎中用于创建应用程序状态指示器（即系统托盘/通知区域图标）的核心节点。本文以 class_statusindicator.rst 为骨架，结合 creating_applications.rst 的实战教程、NativeMenu与DisplayServer的底层接口，系统讲解托盘图标节点的属性、信号、原生弹出菜单，以及经典的"最小化到托盘"（minimize on close）实现方案，帮助你为基于 Godot 的桌面应用补齐系统托盘集成能力。

StatusIndicator 是什么

StatusIndicator是一个直接继承自Node（继承链为Node < Object）的节点，官方文档对它的定义是：

Application status indicator (aka notification area icon)。

它让应用在操作系统的通知区域（Windows 任务栏右侧的"系统托盘"、macOS 菜单栏右侧的状态栏区域）显示一个图标。需要注意的关键限制是：

Note:Status indicator is implemented on macOS and Windows.

也就是说，托盘图标目前仅在macOS 和 Windows上实现，Linux 等其他平台暂不支持。编写代码时务必做特性检测（见下文"特性检测"一节），避免在不受支持的平台上报错。

在 creating_applications.rst 的"Creating an icon in the system tray"一节中，官方明确说明该功能"only supported on Windows and macOS"，并指出可以创建一个或多个托盘图标，每个图标由独立的StatusIndicator节点承载。

快速上手：创建托盘图标节点

在编辑器中新建一个节点，类型选择StatusIndicator即可。最小化的托盘图标只需要两件事：

1. 为icon属性指定一张Texture2D（建议使用小尺寸图标，如 16×16 或 22×22，并按需提供高 DPI 版本）；
2. 设置tooltip文本（鼠标悬停时系统显示的提示文字）。

随后将节点加入场景树即可生效。根据官方教程，即使不需要任何脚本，一个带图标和 tooltip 的StatusIndicator节点就能在系统托盘中正常显示。

也可以直接用 GDScript 创建并配置：

extends Node func _ready(): var indicator := StatusIndicator.new() indicator.icon = preload("res://icon_tray.png") indicator.tooltip = "My Godot App" add_child(indicator)

属性详解

StatusIndicator共暴露 4 个属性，下表完整罗列（类型、默认值均来自官方类文档）：

icon

状态指示器图标，类型为Texture2D。通过set_icon(value)/get_icon()访问。托盘图标尺寸很小，建议提供轮廓清晰、在深浅色系统主题下都可辨识的图标。

menu：原生弹出菜单

menu是NodePath类型，指向一个弹出菜单节点（通常是PopupMenu）。它的行为有一个重要转折：

Status indicator native popup menu. If this is set, thepressedsignal is not emitted.

一旦设置了menu，点击托盘图标将弹出该菜单，pressed信号便不再发出。这意味着"弹出菜单"和"自定义按下响应"是互斥的两种交互模式，你需要按需二选一。

另外，官方对该属性补充了平台约束：

Note:Native popup is only supported ifNativeMenusupportsNativeMenu.FEATURE_POPUP_MENUfeature.

即原生弹出菜单只有在NativeMenu支持FEATURE_POPUP_MENU特性时才可用。在 class_nativemenu.rst 中，FEATURE_POPUP_MENU = 1，定义为 "NativeMenusupports native popup menus."，可通过NativeMenu.has_feature(NativeMenu.FEATURE_POPUP_MENU)在运行时查询。

tooltip

悬停在托盘图标上时显示的工具提示文本，通过set_tooltip(value)/get_tooltip()访问，默认空字符串。

visible

布尔值，true时指示器可见。默认值为true。通过set_visible(value)/is_visible()访问。在"最小化到托盘"场景中，通常初始隐藏、关闭窗口时再显示（见下文实战）。

信号与方法

pressed 信号

pressed(mouse_button: int, mouse_position: Vector2i)

当状态指示器被按下时发出。参数含义：

• mouse_button：按下的鼠标按键（对应MOUSE_BUTTON_*常量，如MOUSE_BUTTON_LEFT、MOUSE_BUTTON_RIGHT）；
• mouse_position：按下时鼠标在屏幕上的位置。

官方教程特别提到，可以利用该信号在不弹出下拉菜单的情况下执行动作，或根据按下的鼠标按键区分行为（例如左键打开主界面、右键弹出自定义菜单）。注意：当menu属性被设置后，该信号不再发出。

get_rect() 方法

get_rect() -> Rect2 # const

返回状态指示器在屏幕坐标下的矩形区域（Rect2）。如果指示器当前不可见，则返回一个空的Rect2。该方法为const，不修改任何实例成员变量。可用于定位（比如配合自定义弹出层时计算锚点）。

给托盘图标添加右键菜单

方案一：设置 menu 属性（推荐）

在场景中创建PopupMenu子节点，把StatusIndicator.menu的NodePath指向它。系统会用原生弹出菜单显示该PopupMenu，体验与操作系统其他托盘图标一致。

值得注意的联动行为记录在 class_popupmenu.rst 的prefer_native_menu属性描述中：

IfPopupMenuis linked toStatusIndicator,MenuBar, or anotherPopupMenuitem it can use native menu regardless of this property, useis_native_menu()to check it.

即：只要PopupMenu被链接到StatusIndicator，它无需开启prefer_native_menu也会使用原生菜单（前提是NativeMenu支持FEATURE_POPUP_MENU），可用PopupMenu.is_native_menu()确认当前是否生效。

方案二：监听 pressed 信号 + 手动弹出

如果你希望完全掌控交互（例如按不同鼠标按键做不同处理），可以不设置menu，转而连接pressed信号，再结合NativeMenu手动弹出菜单：

func _on_pressed(mouse_button: int, mouse_position: Vector2i): if mouse_button == MOUSE_BUTTON_RIGHT: NativeMenu.popup(menu_rid, mouse_position)

NativeMenu是 OS 原生菜单的底层接口（见 class_nativemenu.rst），用create_menu()创建菜单、add_item()添加条目、popup(rid, position)在指定屏幕位置弹出，并在_exit_tree()中free_menu()释放。

实战：最小化到托盘（minimize on close）

官方教程给出了一套完整的"关闭窗口时最小化到托盘"实现，这也是托盘图标最典型的应用场景。思路是：当用户点击窗口关闭按钮（X）时，不退出应用，而是最小化窗口并显示托盘图标；点击托盘图标时恢复窗口。

把下面的脚本挂到Autoload（单例）场景上，该场景以StatusIndicator为根节点：

extends StatusIndicator # 禁用游戏嵌入(编辑器)模式下的此行为，因为二者配合不佳。 var tray_icon_supported = ( DisplayServer.has_feature(DisplayServer.FEATURE_STATUS_INDICATOR) and not Engine.is_embedded_in_editor() ) func _ready(): visible = false if tray_icon_supported: get_tree().auto_accept_quit = false get_window().focus_entered.connect( func(): # 当窗口重新获得焦点时隐藏托盘图标， # 说明它已从最小化状态恢复。 visible = false ) pressed.connect( func(_mouse_button, _position): # 点击托盘图标时恢复应用窗口。 get_window().mode = Window.MODE_WINDOWED ) func _notification(what): if not tray_icon_supported: return match what: NOTIFICATION_WM_CLOSE_REQUEST: get_window().mode = Window.MODE_MINIMIZED # 显示托盘图标。 visible = true

脚本要点拆解：

1. 平台特性检测：DisplayServer.has_feature(DisplayServer.FEATURE_STATUS_INDICATOR)判断当前显示服务器是否支持状态指示器。在 class_displayserver.rst 中，FEATURE_STATUS_INDICATOR = 22，描述为 "Display server supports application status indicators."，与本文档"仅 macOS / Windows"的平台约束相互印证。
2. 编辑器嵌入检测：Engine.is_embedded_in_editor()用于排除"游戏嵌入（game embedding）"模式——在该模式下托盘行为与编辑器配合不佳，应整体禁用。官方教程在多处（原生文件对话框、全局菜单等）都强调嵌入模式下要手动关闭Embed Game on Next Play后再测试。
3. 拦截退出：get_tree().auto_accept_quit = false使应用不再自动响应退出请求，配合NOTIFICATION_WM_CLOSE_REQUEST通知接管关闭流程（详见官方"handling quit requests"章节）。这里选择最小化Window.MODE_MINIMIZED并显示托盘图标。
4. 恢复窗口：连接pressed信号，点击托盘图标时把窗口模式切回Window.MODE_WINDOWED；同时监听focus_entered，窗口恢复焦点后隐藏托盘图标。

官方教程特别提醒：接管关闭流程时，若用户有未保存的更改，应妥善处理以避免数据丢失。

特性检测与平台注意事项

StatusIndicator的可用性由DisplayServer的特性位决定，运行时建议统一使用：

DisplayServer.has_feature(DisplayServer.FEATURE_STATUS_INDICATOR)

• 返回true：当前平台支持状态指示器（macOS、Windows）；
• 返回false：应优雅降级（如隐藏相关 UI、改用其他退出方式）。

此外还有两点官方明确记录的注意事项：

• 多个托盘图标：当场景中存在多个StatusIndicator节点时，它们在系统托盘中的排列顺序由加入场景树的先后顺序决定（见 creating_applications.rst）；
• 原生弹出菜单：menu属性依赖NativeMenu.FEATURE_POPUP_MENU特性（class_nativemenu.rst），且一旦设置menu，pressed信号不再发出。

总结

StatusIndicator为 Godot 桌面应用提供了跨 macOS / Windows 的系统托盘集成能力：通过icon、tooltip、visible控制外观与显隐，通过menu接入原生弹出菜单（依托NativeMenu.FEATURE_POPUP_MENU），通过pressed信号与get_rect()实现自定义点击行为与坐标查询。配合DisplayServer.FEATURE_STATUS_INDICATOR特性检测和"最小化到托盘"脚本，即可为应用提供桌面级、符合系统交互习惯的托盘体验。更多上下文可继续阅读官方应用开发指南 creating_applications.rst 及 class_nativemenu.rst 完整类文档。

• 文档
• 教程
• 游戏开发