GFTagCatalog¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/foundation/tags/gf_tag_catalog.gd - 模块：
Standard - 继承：
Resource - API：
public - 类别：资源定义 (
resource_definition) - 首次版本：
8.0.0
可选标签目录与重定向资源。 用于声明项目可识别的标签、说明文本、迁移重定向和元数据。它只提供 定义校验和标签源规范化，不强制所有 GFTagSet 或 GFTagQuery 必须依赖全局目录。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 属性 | catalog_id |
var catalog_id: StringName = &"" |
| 属性 | tag_definitions |
var tag_definitions: Array[Dictionary] = [] |
| 属性 | allow_undefined_tags |
var allow_undefined_tags: bool = true |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 方法 | configure |
func configure( p_catalog_id: StringName, p_definitions: Array[Dictionary] = [], options: Dictionary = {} ) -> GFTagCatalog: |
| 方法 | add_tag |
func add_tag(tag: StringName, options: Dictionary = {}) -> bool: |
| 方法 | add_redirect |
func add_redirect(source_tag: StringName, target_tag: StringName, options: Dictionary = {}) -> bool: |
| 方法 | has_tag |
func has_tag(tag: StringName, include_redirects: bool = true) -> bool: |
| 方法 | get_tag_definition |
func get_tag_definition(tag: StringName, include_redirects: bool = true) -> Dictionary: |
| 方法 | get_tags |
func get_tags() -> PackedStringArray: |
| 方法 | get_redirect_tags |
func get_redirect_tags() -> PackedStringArray: |
| 方法 | resolve_tag |
func resolve_tag(tag: StringName, max_depth: int = 16) -> StringName: |
| 方法 | normalize_tag_source |
func normalize_tag_source(source: Variant, options: Dictionary = {}) -> GFTagSet: |
| 方法 | validate_tag_source |
func validate_tag_source(source: Variant, options: Dictionary = {}) -> GFValidationReport: |
| 方法 | validate_definition |
func validate_definition(options: Dictionary = {}) -> GFValidationReport: |
| 方法 | duplicate_catalog |
func duplicate_catalog() -> GFTagCatalog: |
| 方法 | to_dictionary |
func to_dictionary() -> Dictionary: |
| 方法 | from_dictionary |
static func from_dictionary(data: Dictionary) -> GFTagCatalog: |
属性¶
catalog_id¶
- API：
public - 首次版本：
8.0.0
目录标识。为空时调用方可自行决定报告主题。
tag_definitions¶
- API：
public - 首次版本：
8.0.0
标签定义列表。 每项是 Dictionary，至少包含 tag，可选 redirect_to、description 和 metadata。
结构：
tag_definitions: Array[Dictionary]，每项包含 tag: StringName/String、redirect_to: StringName/String、description: String、metadata: Dictionary。
allow_undefined_tags¶
- API：
public - 首次版本：
8.0.0
校验标签源时是否允许目录外标签。
metadata¶
- API：
public - 首次版本：
8.0.0
目录元数据。GF 不解释其中业务字段。
结构：
metadata: Dictionary caller-defined catalog metadata.
方法¶
configure¶
- API：
public - 首次版本：
8.0.0
func configure( p_catalog_id: StringName, p_definitions: Array[Dictionary] = [], options: Dictionary = {} ) -> GFTagCatalog:
配置标签目录。
参数：
| 名称 | 说明 |
|---|---|
p_catalog_id |
目录标识。 |
p_definitions |
标签定义列表。 |
options |
可选配置，支持 allow_undefined_tags 和 metadata。 |
返回：当前目录。
结构：
p_definitions: Array[Dictionary] 标签定义列表。options: Dictionary catalog options.
add_tag¶
- API：
public - 首次版本：
8.0.0
添加标签定义。
参数：
| 名称 | 说明 |
|---|---|
tag |
标签名。 |
options |
定义选项，支持 redirect_to、description 和 metadata。 |
返回：添加成功返回 true。
结构：
options: Dictionary tag definition options.
add_redirect¶
- API：
public - 首次版本：
8.0.0
func add_redirect(source_tag: StringName, target_tag: StringName, options: Dictionary = {}) -> bool:
添加标签重定向定义。
参数：
| 名称 | 说明 |
|---|---|
source_tag |
旧标签名。 |
target_tag |
目标标签名。 |
options |
定义选项，支持 description 和 metadata。 |
返回：添加成功返回 true。
结构：
options: Dictionary redirect definition options.
has_tag¶
- API：
public - 首次版本：
8.0.0
检查目录中是否声明了标签。
参数：
| 名称 | 说明 |
|---|---|
tag |
标签名。 |
include_redirects |
是否把重定向源也视作已声明。 |
返回：已声明返回 true。
get_tag_definition¶
- API：
public - 首次版本：
8.0.0
获取标签定义。
参数：
| 名称 | 说明 |
|---|---|
tag |
标签名。 |
include_redirects |
是否允许返回重定向源定义。 |
返回：定义副本；未声明时返回空 Dictionary。
结构：
return: Dictionary tag definition.
get_tags¶
- API：
public - 首次版本：
8.0.0
获取所有正式标签名。
返回：排序后的标签名，不包含重定向源。
get_redirect_tags¶
- API：
public - 首次版本：
8.0.0
获取所有重定向源标签。
返回：排序后的重定向源标签。
resolve_tag¶
- API：
public - 首次版本：
8.0.0
解析标签重定向。 连续重定向会被追踪到最终目标；遇到循环或空标签时返回原始标签。
参数：
| 名称 | 说明 |
|---|---|
tag |
原始标签。 |
max_depth |
最大重定向层数。 |
返回：解析后的标签。
normalize_tag_source¶
- API：
public - 首次版本：
8.0.0
规范化标签源。 会读取任意 GFTagSourceAdapter 支持的来源，解析重定向并合并重复标签层数。
参数：
| 名称 | 说明 |
|---|---|
source |
标签源。 |
options |
规范化选项，支持 drop_undefined 和 max_redirect_depth。 |
返回：新的标签集合。
结构：
source: Variant accepted by GFTagSourceAdapter.options: Dictionary normalization options.
validate_tag_source¶
- API：
public - 首次版本：
8.0.0
校验标签源是否满足目录声明。
参数：
| 名称 | 说明 |
|---|---|
source |
标签源。 |
options |
校验选项，支持 subject、allow_undefined_tags 和 max_redirect_depth。 |
返回：校验报告。
结构：
source: Variant accepted by GFTagSourceAdapter.options: Dictionary validation options.
validate_definition¶
- API：
public - 首次版本：
8.0.0
校验目录定义自身。
参数：
| 名称 | 说明 |
|---|---|
options |
校验选项，支持 subject。 |
返回：校验报告。
结构：
options: Dictionary validation options.
duplicate_catalog¶
- API：
public - 首次版本：
8.0.0
创建同内容拷贝。
返回：新标签目录。
to_dictionary¶
- API：
public - 首次版本：
8.0.0
导出为字典。
返回：标签目录字典。
结构：
return: Dictionary serialized tag catalog.
from_dictionary¶
- API：
public - 首次版本：
8.0.0
从字典创建标签目录。
参数：
| 名称 | 说明 |
|---|---|
data |
标签目录字典。 |
返回：新标签目录。
结构：
data: Dictionary serialized tag catalog.