GFUIRouterUtility

API Reference / Standard / 类索引

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

基于路由 ID 的 UI 导航工具。 作为 GFUIUtility 之上的轻量路由层，负责把稳定 route_id 映射到面板场景、 打开参数、层级和历史记录，不接管具体页面业务或动画表现。

成员概览

类型	名称	签名
信号	route_open_requested	signal route_open_requested(route_id: StringName, operation: Operation, params: Dictionary)
信号	route_opened	signal route_opened(route_id: StringName, panel: Node, operation: Operation)
信号	route_open_failed	signal route_open_failed(route_id: StringName, reason: String)
信号	route_back_completed	signal route_back_completed(route_id: StringName, layer: int)
枚举	Operation	enum Operation
属性	max_history	var max_history: int = 64
方法	init	func init() -> void:
方法	dispose	func dispose() -> void:
方法	configure	func configure(routes: Array[GFUIRoute] = [], ui_utility: GFUIUtility = null) -> void:
方法	set_ui_utility	func set_ui_utility(ui_utility: GFUIUtility) -> void:
方法	register_route	func register_route(route: GFUIRoute) -> bool:
方法	register_routes	func register_routes(routes: Array[GFUIRoute]) -> void:
方法	unregister_route	func unregister_route(route_id: StringName) -> void:
方法	clear_routes	func clear_routes() -> void:
方法	get_route	func get_route(route_id: StringName) -> GFUIRoute:
方法	has_route	func has_route(route_id: StringName) -> bool:
方法	get_route_ids	func get_route_ids() -> PackedStringArray:
方法	push_route	func push_route( route_id: StringName, params: Dictionary = {}, option_overrides: Dictionary = {}, config_callback: Callable = Callable() ) -> Node:
方法	replace_route	func replace_route( route_id: StringName, params: Dictionary = {}, option_overrides: Dictionary = {}, config_callback: Callable = Callable() ) -> Node:
方法	push_route_async	func push_route_async( route_id: StringName, params: Dictionary = {}, option_overrides: Dictionary = {}, config_callback: Callable = Callable() ) -> void:
方法	replace_route_async	func replace_route_async( route_id: StringName, params: Dictionary = {}, option_overrides: Dictionary = {}, config_callback: Callable = Callable() ) -> void:
方法	back	func back(layer: int = -1, do_free: bool = true) -> bool:
方法	get_current_route_id	func get_current_route_id(layer: int = -1) -> StringName:
方法	get_route_history	func get_route_history() -> Array[Dictionary]:
方法	clear_history	func clear_history() -> void:
方法	get_debug_snapshot	func get_debug_snapshot() -> Dictionary:

信号

route_open_requested

• API：public

signal route_open_requested(route_id: StringName, operation: Operation, params: Dictionary)

路由打开请求发出时触发。

参数：

名称	说明
route_id	路由标识。
operation	打开操作。
params	路由参数。

结构：

• params: Dictionary，本次打开路由携带的项目自定义参数。

route_opened

• API：public

signal route_opened(route_id: StringName, panel: Node, operation: Operation)

路由面板成功打开后触发。

参数：

名称	说明
route_id	路由标识。
panel	面板实例。
operation	打开操作。

route_open_failed

• API：public

signal route_open_failed(route_id: StringName, reason: String)

路由打开失败时触发。

参数：

名称	说明
route_id	路由标识。
reason	失败原因。

route_back_completed

• API：public

signal route_back_completed(route_id: StringName, layer: int)

路由返回完成时触发。

参数：

名称	说明
route_id	被弹出的路由标识。
layer	所在层级。

枚举

Operation

• API：public

enum Operation { ## 压入当前层级栈顶。 PUSH, ## 替换当前层级栈。 REPLACE, }

路由打开操作。

属性

max_history

• API：public

var max_history: int = 64

路由历史最大保留数量。小于等于 0 表示不保留历史。

方法

init

• API：public

func init() -> void:

初始化路由表、UI 工具引用和历史记录。

dispose

• API：public

func dispose() -> void:

释放路由表、UI 工具引用和历史记录。

configure

• API：public

func configure(routes: Array[GFUIRoute] = [], ui_utility: GFUIUtility = null) -> void:

配置路由表和可选 UI 工具实例。

参数：

名称	说明
routes	路由资源列表。
ui_utility	可选 GFUIUtility；为空时从当前架构查找。

set_ui_utility

• API：public

func set_ui_utility(ui_utility: GFUIUtility) -> void:

设置路由使用的 UI 栈工具。

参数：

名称	说明
ui_utility	UI 栈工具实例。

register_route

• API：public

func register_route(route: GFUIRoute) -> bool:

注册一个路由。

参数：

名称	说明
route	路由资源。

返回：注册成功返回 true。

register_routes

• API：public

func register_routes(routes: Array[GFUIRoute]) -> void:

批量注册路由。

参数：

名称	说明
routes	路由资源列表。

unregister_route

• API：public

func unregister_route(route_id: StringName) -> void:

注销路由。

参数：

名称	说明
route_id	路由标识。

clear_routes

• API：public

func clear_routes() -> void:

清空路由表。

get_route

• API：public

func get_route(route_id: StringName) -> GFUIRoute:

获取路由资源。

参数：

名称	说明
route_id	路由标识。

返回：路由资源；不存在时返回 null。

has_route

• API：public

func has_route(route_id: StringName) -> bool:

检查路由是否已注册。

参数：

名称	说明
route_id	路由标识。

返回：已注册返回 true。

get_route_ids

• API：public

func get_route_ids() -> PackedStringArray:

获取所有路由标识。

返回：路由标识列表。

push_route

• API：public

func push_route( route_id: StringName, params: Dictionary = {}, option_overrides: Dictionary = {}, config_callback: Callable = Callable() ) -> Node:

压入一个路由面板。

参数：

名称	说明
route_id	路由标识。
params	路由参数。
option_overrides	面板选项覆盖。
config_callback	面板实例化后、入栈前的额外配置回调。

返回：成功时返回面板实例。

结构：

• params: Dictionary，本次打开路由携带的项目自定义参数。
• option_overrides: Dictionary，字段同 GFUIUtility 打开面板 options，会覆盖路由 default_options。

replace_route

• API：public

func replace_route( route_id: StringName, params: Dictionary = {}, option_overrides: Dictionary = {}, config_callback: Callable = Callable() ) -> Node:

替换路由所在层级。

参数：

名称	说明
route_id	路由标识。
params	路由参数。
option_overrides	面板选项覆盖。
config_callback	面板实例化后、入栈前的额外配置回调。

返回：成功时返回面板实例。

结构：

• params: Dictionary，本次打开路由携带的项目自定义参数。
• option_overrides: Dictionary，字段同 GFUIUtility 打开面板 options，会覆盖路由 default_options。

push_route_async

• API：public

func push_route_async( route_id: StringName, params: Dictionary = {}, option_overrides: Dictionary = {}, config_callback: Callable = Callable() ) -> void:

异步压入一个路由面板。

参数：

名称	说明
route_id	路由标识。
params	路由参数。
option_overrides	面板选项覆盖。
config_callback	面板实例化后、入栈前的额外配置回调。

结构：

• params: Dictionary，本次打开路由携带的项目自定义参数。
• option_overrides: Dictionary，字段同 GFUIUtility 打开面板 options，会覆盖路由 default_options。

replace_route_async

• API：public

func replace_route_async( route_id: StringName, params: Dictionary = {}, option_overrides: Dictionary = {}, config_callback: Callable = Callable() ) -> void:

异步替换路由所在层级。

参数：

名称	说明
route_id	路由标识。
params	路由参数。
option_overrides	面板选项覆盖。
config_callback	面板实例化后、入栈前的额外配置回调。

结构：

• params: Dictionary，本次打开路由携带的项目自定义参数。
• option_overrides: Dictionary，字段同 GFUIUtility 打开面板 options，会覆盖路由 default_options。

back

• API：public

func back(layer: int = -1, do_free: bool = true) -> bool:

返回上一层路由。

参数：

名称	说明
layer	指定层级；小于 0 时使用最近的历史记录。
do_free	是否释放被弹出的面板。

返回：成功返回 true。

get_current_route_id

• API：public

func get_current_route_id(layer: int = -1) -> StringName:

获取当前路由标识。

参数：

名称	说明
layer	指定层级；小于 0 时返回最近路由。

返回：当前路由标识；没有时返回空 StringName。

get_route_history

• API：public

func get_route_history() -> Array[Dictionary]:

获取路由历史副本。

返回：从旧到新的历史条目。

结构：

• return: Array，元素为 Dictionary，包含 route_id、layer、panel、params 和 metadata。

clear_history

• API：public

func clear_history() -> void:

清空路由历史，不影响已打开面板。

get_debug_snapshot

• API：public

func get_debug_snapshot() -> Dictionary:

获取路由诊断快照。

返回：诊断快照。

结构：

• return: Dictionary，包含 route_count、history_count、current_route_id 和 has_ui_utility。