GFInputIconAtlasProvider

API Reference / Standard / 类索引

• 路径：addons/gf/standard/input/formatting/gf_input_icon_atlas_provider.gd
• 模块：Standard
• 继承：GFInputIconProvider
• API：public
• 类别：资源定义 (resource_definition)
• 首次版本：3.17.0

可配置输入图标图集 Provider。 将 InputEvent 归一化为通用图标键，再通过显式映射或路径模板解析 Texture2D / RichText 图标。 框架不附带图标资源，也不规定项目的美术风格或平台命名。

成员概览

类型	名称	签名
属性	root_path	var root_path: String = ""
属性	style	var style: StringName = &"default"
属性	platform	var platform: StringName = &""
属性	fallback_platform	var fallback_platform: StringName = &"generic"
属性	path_pattern	var path_pattern: String = "{root}/{style}/{platform}/{icon}.png"
属性	icon_paths	var icon_paths: Dictionary = {}
属性	icon_textures	var icon_textures: Dictionary = {}
属性	rich_text_separator	var rich_text_separator: String = " "
属性	split_key_modifiers	var split_key_modifiers: bool = true
方法	set_icon_path	func set_icon_path(icon_key: StringName, icon_resource_path: String) -> void:
方法	set_icon_texture	func set_icon_texture(icon_key: StringName, texture: Texture2D) -> void:
方法	clear_cache	func clear_cache() -> void:
方法	supports_event	func supports_event(input_event: InputEvent, options: Dictionary = {}) -> bool:
方法	get_event_icon	func get_event_icon(input_event: InputEvent, options: Dictionary = {}) -> Texture2D:
方法	get_event_rich_text	func get_event_rich_text(input_event: InputEvent, options: Dictionary = {}) -> String:
方法	get_event_icon_path	func get_event_icon_path(input_event: InputEvent, options: Dictionary = {}) -> String:
方法	resolve_event_icon_key	func resolve_event_icon_key(input_event: InputEvent, options: Dictionary = {}) -> StringName:
方法	get_event_icon_candidates	func get_event_icon_candidates(input_event: InputEvent, options: Dictionary = {}) -> PackedStringArray:

属性

root_path

• API：public

var root_path: String = ""

图标根目录。路径模板中的 {root} 会使用该值。

style

• API：public

var style: StringName = &"default"

图标风格名。路径模板中的 {style} 会使用该值。

platform

• API：public

var platform: StringName = &""

平台名。为空时使用 options.platform 或 fallback_platform。

fallback_platform

• API：public

var fallback_platform: StringName = &"generic"

平台回退名。

path_pattern

• API：public

var path_pattern: String = "{root}/{style}/{platform}/{icon}.png"

路径模板。可使用 {root}、{style}、{platform}、{icon}。

icon_paths

• API：public

var icon_paths: Dictionary = {}

显式路径映射，key 为 get_event_icon_candidates() 产生的图标键。

结构：

• icon_paths: Dictionary，以 StringName 或 String 图标键为键，值为 String Texture2D 资源路径。

icon_textures

• API：public

var icon_textures: Dictionary = {}

显式纹理映射，key 为 get_event_icon_candidates() 产生的图标键。

结构：

• icon_textures: Dictionary，以 StringName 或 String 图标键为键，值为 Texture2D。

rich_text_separator

• API：public

var rich_text_separator: String = " "

RichText 输出多个图标时使用的分隔文本。

split_key_modifiers

• API：public

var split_key_modifiers: bool = true

是否为带修饰键的键盘事件输出多个图标。

方法

set_icon_path

• API：public

func set_icon_path(icon_key: StringName, icon_resource_path: String) -> void:

设置图标路径映射。

参数：

名称	说明
icon_key	图标键。
icon_resource_path	Texture2D 资源路径。

set_icon_texture

• API：public

func set_icon_texture(icon_key: StringName, texture: Texture2D) -> void:

设置图标纹理映射。

参数：

名称	说明
icon_key	图标键。
texture	图标纹理。

clear_cache

• API：public

func clear_cache() -> void:

清空已加载的纹理缓存。

supports_event

• API：public

func supports_event(input_event: InputEvent, options: Dictionary = {}) -> bool:

判断是否支持指定输入事件。

参数：

名称	说明
input_event	输入事件。
options	调用选项。

返回：支持返回 true。

结构：

• options: Dictionary，可包含 allow_missing_paths、root_path、style、platform、path_pattern、split_key_modifiers 和 include_key_modifier_combo。

get_event_icon

• API：public

func get_event_icon(input_event: InputEvent, options: Dictionary = {}) -> Texture2D:

获取输入事件图标。

参数：

名称	说明
input_event	输入事件。
options	调用选项。

返回：图标纹理；不存在时返回 null。

结构：

• options: Dictionary，可包含 allow_missing_paths、root_path、style、platform、path_pattern、split_key_modifiers 和 include_key_modifier_combo。

get_event_rich_text

• API：public

func get_event_rich_text(input_event: InputEvent, options: Dictionary = {}) -> String:

获取输入事件 RichTextLabel BBCode。

参数：

名称	说明
input_event	输入事件。
options	调用选项。

返回：BBCode；无法解析时返回空字符串。

结构：

• options: Dictionary，可包含 allow_missing_paths、icon_size、rich_text_separator、root_path、style、platform、path_pattern、split_key_modifiers 和 include_key_modifier_combo。

get_event_icon_path

• API：public

func get_event_icon_path(input_event: InputEvent, options: Dictionary = {}) -> String:

获取输入事件的首选图标路径。

参数：

名称	说明
input_event	输入事件。
options	调用选项。

返回：图标路径；无法解析时返回空字符串。

结构：

• options: Dictionary，可包含 allow_missing_paths、root_path、style、platform、path_pattern、split_key_modifiers 和 include_key_modifier_combo。

resolve_event_icon_key

• API：public

func resolve_event_icon_key(input_event: InputEvent, options: Dictionary = {}) -> StringName:

获取输入事件的首选图标键。

参数：

名称	说明
input_event	输入事件。
options	调用选项。

返回：图标键；无法解析时返回空 StringName。

结构：

• options: Dictionary，可包含 split_key_modifiers 和 include_key_modifier_combo。

get_event_icon_candidates

• API：public

func get_event_icon_candidates(input_event: InputEvent, options: Dictionary = {}) -> PackedStringArray:

获取输入事件可能使用的图标键列表。

参数：

名称	说明
input_event	输入事件。
options	调用选项。

返回：图标键列表，按优先级排序。

结构：

• options: Dictionary，可包含 split_key_modifiers 和 include_key_modifier_combo。