GFDictionarySchema

API Reference / Standard / 类索引

• 路径：addons/gf/standard/foundation/schema/gf_dictionary_schema.gd
• 模块：Standard
• 继承：Resource
• API：public
• 类别：资源定义 (resource_definition)
• 首次版本：4.4.0

通用 Dictionary 结构声明与校验器。 为任意 Dictionary 提供字段声明、默认值补齐、类型转换、嵌套结构校验和定义自检。 它只描述数据形态，不包含配置表索引、跨表引用、内容包启用策略或游戏业务规则。

成员概览

类型	名称	签名
属性	schema_id	var schema_id: StringName = &""
属性	fields	var fields: Array[GFSchemaField] = []
属性	allow_extra_fields	var allow_extra_fields: bool = true
属性	coerce_values	var coerce_values: bool = false
属性	fail_on_coerce_error	var fail_on_coerce_error: bool = true
属性	metadata	var metadata: Dictionary = {}
方法	configure	func configure( p_schema_id: StringName, p_fields: Array[GFSchemaField] = [], options: Dictionary = {} ) -> GFDictionarySchema:
方法	add_field	func add_field(field: GFSchemaField) -> bool:
方法	get_field	func get_field(field_name: StringName) -> GFSchemaField:
方法	has_field	func has_field(field_name: StringName) -> bool:
方法	get_field_names	func get_field_names() -> PackedStringArray:
方法	build_defaults	func build_defaults(include_optional: bool = true) -> Dictionary:
方法	apply_defaults	func apply_defaults(values: Dictionary, include_optional: bool = true, should_coerce: bool = true) -> Dictionary:
方法	coerce_dictionary	func coerce_dictionary(values: Dictionary, include_defaults: bool = true) -> Dictionary:
方法	validate_definition	func validate_definition(options: Dictionary = {}) -> GFValidationReport:
方法	validate_dictionary	func validate_dictionary(values: Dictionary, options: Dictionary = {}) -> GFValidationReport:
方法	duplicate_schema	func duplicate_schema() -> GFDictionarySchema:
方法	describe	func describe() -> Dictionary:

属性

schema_id

• API：public

var schema_id: StringName = &""

Schema 标识。为空时可由调用方自行决定报告主题。

fields

• API：public

var fields: Array[GFSchemaField] = []

字段声明列表。

结构：

• fields: Array[GFSchemaField] declared Dictionary fields.

allow_extra_fields

• API：public

var allow_extra_fields: bool = true

是否允许包含 schema 未声明的字段。

coerce_values

• API：public

var coerce_values: bool = false

是否在校验前按字段声明尝试类型转换。

fail_on_coerce_error

• API：public

var fail_on_coerce_error: bool = true

启用 coerce_values 时，转换失败是否作为校验错误。

metadata

• API：public

var metadata: Dictionary = {}

可选元数据。GF 不解释其中业务字段。

结构：

• metadata: Dictionary caller-defined schema metadata.

方法

configure

• API：public

func configure( p_schema_id: StringName, p_fields: Array[GFSchemaField] = [], options: Dictionary = {} ) -> GFDictionarySchema:

配置 schema。

参数：

名称	说明
p_schema_id	Schema 标识。
p_fields	字段声明列表。
options	可选配置，支持 allow_extra_fields、coerce_values、fail_on_coerce_error 和 metadata。

返回：当前 schema。

结构：

• p_fields: Array[GFSchemaField] declared Dictionary fields.
• options: Dictionary schema options.

add_field

• API：public

func add_field(field: GFSchemaField) -> bool:

添加字段声明。

参数：

名称	说明
field	字段声明。

返回：添加成功返回 true。

get_field

• API：public

func get_field(field_name: StringName) -> GFSchemaField:

获取字段声明。

参数：

名称	说明
field_name	字段名。

返回：找到时返回字段声明，否则返回 null。

has_field

• API：public

func has_field(field_name: StringName) -> bool:

检查字段声明是否存在。

参数：

名称	说明
field_name	字段名。

返回：存在返回 true。

get_field_names

• API：public

func get_field_names() -> PackedStringArray:

获取当前 schema 的字段名列表。

返回：排序后的字段名。

build_defaults

• API：public

func build_defaults(include_optional: bool = true) -> Dictionary:

创建默认 Dictionary。

参数：

名称	说明
include_optional	为 true 时包含非必填字段。

返回：默认数据字典。

结构：

• return: Dictionary default values.

apply_defaults

• API：public

func apply_defaults(values: Dictionary, include_optional: bool = true, should_coerce: bool = true) -> Dictionary:

为输入 Dictionary 补齐默认值。

参数：

名称	说明
values	输入字典。
include_optional	为 true 时补齐非必填字段。
should_coerce	为 true 时按字段声明转换已有值和默认值。

返回：补齐后的新字典。

结构：

• values: Dictionary source values.
• return: Dictionary normalized values.

coerce_dictionary

• API：public

func coerce_dictionary(values: Dictionary, include_defaults: bool = true) -> Dictionary:

按字段声明转换 Dictionary。

参数：

名称	说明
values	输入字典。
include_defaults	为 true 时同时补默认值。

返回：转换后的新字典。

结构：

• values: Dictionary source values.
• return: Dictionary coerced values.

validate_definition

• API：public

func validate_definition(options: Dictionary = {}) -> GFValidationReport:

校验 schema 自身声明。

参数：

名称	说明
options	可选上下文，支持 subject、source_path 和 source。

返回：校验报告。

结构：

• options: Dictionary validation context.

validate_dictionary

• API：public

func validate_dictionary(values: Dictionary, options: Dictionary = {}) -> GFValidationReport:

校验 Dictionary 数据。

参数：

名称	说明
values	输入字典。
options	可选上下文，支持 subject、path、source_path 和 source。

返回：校验报告。

结构：

• values: Dictionary source values.
• options: Dictionary validation context.

duplicate_schema

• API：public

func duplicate_schema() -> GFDictionarySchema:

创建同内容拷贝。

返回：新 schema。

describe

• API：public

func describe() -> Dictionary:

导出 schema 摘要。

返回：schema 字典。

结构：

• return: Dictionary schema description.