GFUIUtility

API Reference / Standard / 类索引

• 路径：addons/gf/standard/utilities/ui/gf_ui_utility.gd
• 模块：Standard
• 继承：GFUtility
• API：public
• 类别：运行时服务 (runtime_service)
• 首次版本：3.17.0

栈式 UI 管理器。 负责多层级界面的入栈、出栈与异步加载， 适合 HUD、弹窗和顶层遮罩等需要分层管理的 UI 场景。

成员概览

类型	名称	签名
信号	panel_opened	signal panel_opened(panel: Node, layer: int)
信号	panel_closed	signal panel_closed(panel: Node, layer: int)
信号	navigation_changed	signal navigation_changed(layer: int, top_panel: Node)
信号	panel_dismiss_requested	signal panel_dismiss_requested(panel: Node, layer: int, reason: String)
信号	panel_async_load_started	signal panel_async_load_started(path: String, layer: int, operation: StringName)
信号	panel_async_load_finished	signal panel_async_load_finished(path: String, layer: int, operation: StringName, status: int, panel: Node)
枚举	Layer	enum Layer
枚举	PanelMode	enum PanelMode
枚举	AsyncPanelLoadStatus	enum AsyncPanelLoadStatus
方法	init	func init() -> void:
方法	dispose	func dispose() -> void:
方法	configure	func configure(auto_hide_under: bool = true) -> void:
方法	push_panel_async	func push_panel_async(path: String, layer: Layer = Layer.POPUP, config_callback: Callable = Callable()) -> void:
方法	push_panel_async_with_options	func push_panel_async_with_options( path: String, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> void:
方法	push_panel	func push_panel(path: String, layer: Layer = Layer.POPUP, config_callback: Callable = Callable()) -> Node:
方法	push_panel_with_options	func push_panel_with_options( path: String, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> Node:
方法	replace_layer	func replace_layer(path: String, layer: Layer = Layer.POPUP, config_callback: Callable = Callable()) -> Node:
方法	replace_layer_with_options	func replace_layer_with_options( path: String, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> Node:
方法	replace_layer_async	func replace_layer_async(path: String, layer: Layer = Layer.POPUP, config_callback: Callable = Callable()) -> void:
方法	replace_layer_async_with_options	func replace_layer_async_with_options( path: String, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> void:
方法	push_panel_instance	func push_panel_instance( panel_instance: Node, layer: Layer = Layer.POPUP, config_callback: Callable = Callable() ) -> void:
方法	push_panel_instance_with_options	func push_panel_instance_with_options( panel_instance: Node, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> void:
方法	replace_layer_instance	func replace_layer_instance( panel_instance: Node, layer: Layer = Layer.POPUP, config_callback: Callable = Callable() ) -> void:
方法	replace_layer_instance_with_options	func replace_layer_instance_with_options( panel_instance: Node, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> void:
方法	pop_panel	func pop_panel(layer: Layer = Layer.POPUP, do_free: bool = true) -> void:
方法	pop_to_panel	func pop_to_panel(panel: Node, layer: Layer = Layer.POPUP, do_free: bool = true) -> bool:
方法	clear_layer	func clear_layer(layer: Layer) -> void:
方法	clear_all	func clear_all() -> void:
方法	get_top_panel	func get_top_panel(layer: Layer = Layer.POPUP) -> Node:
方法	get_panel_stack	func get_panel_stack(layer: Layer = Layer.POPUP) -> Array[Node]:
方法	get_stack_count	func get_stack_count(layer: Layer = Layer.POPUP) -> int:
方法	is_panel_open	func is_panel_open(panel: Node, layer: int = -1) -> bool:
方法	get_debug_snapshot	func get_debug_snapshot() -> Dictionary:
方法	get_layer_root	func get_layer_root(layer: Layer) -> CanvasLayer:
方法	set_panel_options	func set_panel_options(panel: Node, options: Dictionary) -> void:
方法	get_panel_options	func get_panel_options(panel: Node) -> Dictionary:
方法	is_panel_modal	func is_panel_modal(panel: Node) -> bool:
方法	has_modal_open	func has_modal_open(layer: int = -1) -> bool:
方法	has_pending_async_panel	func has_pending_async_panel(layer: int = -1, path: String = "") -> bool:
方法	get_pending_async_panel_requests	func get_pending_async_panel_requests(layer: int = -1) -> Array[Dictionary]:
方法	get_modal_count	func get_modal_count(layer: int = -1) -> int:
方法	request_dismiss_top	func request_dismiss_top(layer: int = -1, reason: String = "cancel") -> bool:
方法	keep_focus_inside_top_modal	func keep_focus_inside_top_modal(layer: Layer = Layer.POPUP) -> bool:

信号

panel_opened

• API：public

signal panel_opened(panel: Node, layer: int)

面板成功进入 UI 栈后发出。

参数：

名称	说明
panel	面板实例。
layer	目标层级。

panel_closed

• API：public

signal panel_closed(panel: Node, layer: int)

面板离开 UI 栈后发出。

参数：

名称	说明
panel	面板实例。
layer	原层级。

navigation_changed

• API：public

signal navigation_changed(layer: int, top_panel: Node)

指定层级的栈顶面板变化后发出。

参数：

名称	说明
layer	发生变化的层级。
top_panel	新栈顶面板；层级为空时为 null。

panel_dismiss_requested

• API：public

signal panel_dismiss_requested(panel: Node, layer: int, reason: String)

面板请求被取消或关闭时发出。

参数：

名称	说明
panel	请求关闭的面板。
layer	所在层级。
reason	关闭原因。

panel_async_load_started

• API：public

signal panel_async_load_started(path: String, layer: int, operation: StringName)

异步面板加载请求开始时发出。

参数：

名称	说明
path	面板场景路径。
layer	目标层级。
operation	打开操作，可能为 push 或 replace。

panel_async_load_finished

• API：public

signal panel_async_load_finished(path: String, layer: int, operation: StringName, status: int, panel: Node)

异步面板加载请求结束时发出。

参数：

名称	说明
path	面板场景路径。
layer	目标层级。
operation	打开操作，可能为 push 或 replace。
status	结束状态，使用 AsyncPanelLoadStatus。
panel	成功打开的面板；失败或取消时为 null。

枚举

Layer

• API：public

enum Layer { ## 基础信息层，如主界面、血条 HUD 等。 HUD = 0, ## 弹窗层，如背包、设置菜单、对话框等。 POPUP = 1, ## 顶层，如全屏遮罩、断线重连提示等。 TOP = 2, }

UI 层级，数值越大显示越靠前。

PanelMode

• API：public

enum PanelMode { ## 普通面板。 NORMAL, ## Modal 面板，通常会独占当前交互焦点。 MODAL, }

面板交互模式。

AsyncPanelLoadStatus

• API：public

enum AsyncPanelLoadStatus { ## 面板已完成加载并进入 UI 栈。 OPENED, ## 加载资源、实例化或入栈失败。 FAILED, ## 请求被弹出、清层、替换层或销毁 UI 工具取消。 CANCELLED, }

异步面板加载结束状态。

方法

init

• API：public

func init() -> void:

初始化 UI 层级根节点并激活管理器。

dispose

• API：public

func dispose() -> void:

释放 UI 层级、面板栈和未完成异步请求。

configure

• API：public

func configure(auto_hide_under: bool = true) -> void:

配置 UI 管理器。

参数：

名称	说明
auto_hide_under	压入新面板时是否自动隐藏下层面板。

push_panel_async

• API：public

func push_panel_async(path: String, layer: Layer = Layer.POPUP, config_callback: Callable = Callable()) -> void:

异步压入一个面板场景。

参数：

名称	说明
path	面板场景路径。
layer	目标层级。
config_callback	实例化后、入栈前的可选配置回调。

push_panel_async_with_options

• API：public

func push_panel_async_with_options( path: String, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> void:

异步压入一个带策略选项的面板场景。

参数：

名称	说明
path	面板场景路径。
layer	目标层级。
options	面板策略，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close、metadata。
config_callback	实例化后、入栈前的可选配置回调。

结构：

• options: Dictionary，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close 和 metadata。

push_panel

• API：public

func push_panel(path: String, layer: Layer = Layer.POPUP, config_callback: Callable = Callable()) -> Node:

同步压入一个面板场景。

参数：

名称	说明
path	面板场景路径。
layer	目标层级。
config_callback	实例化后、入栈前的可选配置回调。

返回：成功时返回面板实例，失败时返回 null。

push_panel_with_options

• API：public

func push_panel_with_options( path: String, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> Node:

同步压入一个带策略选项的面板场景。

参数：

名称	说明
path	面板场景路径。
layer	目标层级。
options	面板策略，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close、metadata。
config_callback	实例化后、入栈前的可选配置回调。

返回：成功时返回面板实例，失败时返回 null。

结构：

• options: Dictionary，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close 和 metadata。

replace_layer

• API：public

func replace_layer(path: String, layer: Layer = Layer.POPUP, config_callback: Callable = Callable()) -> Node:

同步替换指定层级的面板栈。

参数：

名称	说明
path	面板场景路径。
layer	目标层级。
config_callback	实例化后、入栈前的可选配置回调。

返回：成功时返回面板实例，失败时返回 null。

replace_layer_with_options

• API：public

func replace_layer_with_options( path: String, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> Node:

同步替换指定层级为带策略选项的面板。

参数：

名称	说明
path	面板场景路径。
layer	目标层级。
options	面板策略，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close、metadata。
config_callback	实例化后、入栈前的可选配置回调。

返回：成功时返回面板实例，失败时返回 null。

结构：

• options: Dictionary，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close 和 metadata。

replace_layer_async

• API：public

func replace_layer_async(path: String, layer: Layer = Layer.POPUP, config_callback: Callable = Callable()) -> void:

异步替换指定层级的面板栈。

参数：

名称	说明
path	面板场景路径。
layer	目标层级。
config_callback	实例化后、入栈前的可选配置回调。

replace_layer_async_with_options

• API：public

func replace_layer_async_with_options( path: String, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> void:

异步替换指定层级为带策略选项的面板。

参数：

名称	说明
path	面板场景路径。
layer	目标层级。
options	面板策略，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close、metadata。
config_callback	实例化后、入栈前的可选配置回调。

结构：

• options: Dictionary，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close 和 metadata。

push_panel_instance

• API：public

func push_panel_instance( panel_instance: Node, layer: Layer = Layer.POPUP, config_callback: Callable = Callable() ) -> void:

压入一个已实例化的面板节点。

参数：

名称	说明
panel_instance	面板实例。
layer	目标层级。
config_callback	入栈前的可选配置回调。

push_panel_instance_with_options

• API：public

func push_panel_instance_with_options( panel_instance: Node, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> void:

压入一个已实例化且带策略选项的面板节点。

参数：

名称	说明
panel_instance	面板实例。
layer	目标层级。
options	面板策略，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close、metadata。
config_callback	入栈前的可选配置回调。

结构：

• options: Dictionary，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close 和 metadata。

replace_layer_instance

• API：public

func replace_layer_instance( panel_instance: Node, layer: Layer = Layer.POPUP, config_callback: Callable = Callable() ) -> void:

用已实例化面板替换指定层级的面板栈。

参数：

名称	说明
panel_instance	面板实例。
layer	目标层级。
config_callback	入栈前的可选配置回调。

replace_layer_instance_with_options

• API：public

func replace_layer_instance_with_options( panel_instance: Node, layer: Layer = Layer.POPUP, options: Dictionary = {}, config_callback: Callable = Callable() ) -> void:

用已实例化且带策略选项的面板替换指定层级的面板栈。

参数：

名称	说明
panel_instance	面板实例。
layer	目标层级。
options	面板策略，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close、metadata。
config_callback	入栈前的可选配置回调。

结构：

• options: Dictionary，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close 和 metadata。

pop_panel

• API：public

func pop_panel(layer: Layer = Layer.POPUP, do_free: bool = true) -> void:

弹出指定层级的顶部面板。

参数：

名称	说明
layer	目标层级。
do_free	是否在弹出后释放面板。

pop_to_panel

• API：public

func pop_to_panel(panel: Node, layer: Layer = Layer.POPUP, do_free: bool = true) -> bool:

弹出面板直到指定面板成为栈顶。

参数：

名称	说明
panel	目标面板实例。
layer	目标层级。
do_free	是否释放被弹出的面板。

返回：找到目标面板并完成回退时返回 true。

clear_layer

• API：public

func clear_layer(layer: Layer) -> void:

清空指定层级的所有面板。

参数：

名称	说明
layer	目标层级。

clear_all

• API：public

func clear_all() -> void:

清空所有层级的所有面板。

get_top_panel

• API：public

func get_top_panel(layer: Layer = Layer.POPUP) -> Node:

获取指定层级的顶部面板。

参数：

名称	说明
layer	目标层级。

返回：栈顶面板；为空时返回 null。

get_panel_stack

• API：public

func get_panel_stack(layer: Layer = Layer.POPUP) -> Array[Node]:

获取指定层级当前面板栈的副本。

参数：

名称	说明
layer	目标层级。

返回：从底到顶排列的面板列表。

get_stack_count

• API：public

func get_stack_count(layer: Layer = Layer.POPUP) -> int:

获取指定层级当前面板数量。

参数：

名称	说明
layer	目标层级。

返回：面板数量。

is_panel_open

• API：public

func is_panel_open(panel: Node, layer: int = -1) -> bool:

检查面板是否已进入 UI 栈。

参数：

名称	说明
panel	面板实例。
layer	指定层级；小于 0 时检查所有层级。

返回：面板已打开时返回 true。

get_debug_snapshot

• API：public

func get_debug_snapshot() -> Dictionary:

获取 UI 管理器诊断快照。

返回：包含各层级栈数量和栈顶名称的字典。

结构：

• return: Dictionary，包含 active、auto_hide_under、pending_async_panel_count 和 layers；layers 按 Layer 值索引，每项包含 count、top_panel 和 top_modal。

get_layer_root

• API：public

func get_layer_root(layer: Layer) -> CanvasLayer:

获取指定层级的 CanvasLayer。

参数：

名称	说明
layer	目标层级。

返回：对应的 CanvasLayer 实例。

set_panel_options

• API：public

func set_panel_options(panel: Node, options: Dictionary) -> void:

设置已打开面板的策略选项。

参数：

名称	说明
panel	面板实例。
options	面板策略，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close、metadata。

结构：

• options: Dictionary，支持 mode、modal、dismiss_on_cancel、focus_on_open、restore_focus_on_close 和 metadata。

get_panel_options

• API：public

func get_panel_options(panel: Node) -> Dictionary:

获取面板策略选项。

参数：

名称	说明
panel	面板实例。

返回：策略选项副本。

结构：

• return: Dictionary，包含 mode、dismiss_on_cancel、focus_on_open、restore_focus_on_close 和 metadata。

is_panel_modal

• API：public

func is_panel_modal(panel: Node) -> bool:

判断面板是否按 modal 策略管理。

参数：

名称	说明
panel	面板实例。

返回：是 modal 面板时返回 true。

has_modal_open

• API：public

func has_modal_open(layer: int = -1) -> bool:

检查是否存在打开的 modal 面板。

参数：

名称	说明
layer	指定层级；小于 0 时检查所有层级。

返回：存在 modal 面板时返回 true。

has_pending_async_panel

• API：public

func has_pending_async_panel(layer: int = -1, path: String = "") -> bool:

检查是否存在仍在等待资源回调的异步面板请求。

参数：

名称	说明
layer	指定层级；小于 0 时检查所有层级。
path	指定面板路径；为空时不按路径过滤。

返回：存在匹配请求时返回 true。

get_pending_async_panel_requests

• API：public

func get_pending_async_panel_requests(layer: int = -1) -> Array[Dictionary]:

获取仍在等待资源回调的异步面板请求快照。

参数：

名称	说明
layer	指定层级；小于 0 时返回所有层级。

返回：请求快照数组，每项包含 path、layer、operation 和 serial。

结构：

• return: Array，元素为 Dictionary，包含 path、layer、operation 和 serial。

get_modal_count

• API：public

func get_modal_count(layer: int = -1) -> int:

获取打开的 modal 面板数量。

参数：

名称	说明
layer	指定层级；小于 0 时统计所有层级。

返回：modal 面板数量。

request_dismiss_top

• API：public

func request_dismiss_top(layer: int = -1, reason: String = "cancel") -> bool:

按顶层优先顺序处理取消请求。

参数：

名称	说明
layer	指定层级；小于 0 时从最高层级开始查找。
reason	关闭原因。

返回：找到可取消面板并处理时返回 true。

keep_focus_inside_top_modal

• API：public

func keep_focus_inside_top_modal(layer: Layer = Layer.POPUP) -> bool:

尝试把焦点保持在指定层级栈顶 modal 面板内。

参数：

名称	说明
layer	目标层级。

返回：发生焦点修正时返回 true。