GFSchemaField¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/foundation/schema/gf_schema_field.gd - 模块：
Standard - 继承：
Resource - API：
public - 类别：资源定义 (
resource_definition) - 首次版本：
4.4.0
通用数据字段声明。 描述一个 Dictionary 字段或数组元素的类型、必填性、空值策略、默认值和可选嵌套 schema。 它只表达结构契约，不绑定配置表、黑板、内容包或具体业务字段语义。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 枚举 | ValueType |
enum ValueType |
| 属性 | field_name |
var field_name: StringName = &"" |
| 属性 | value_type |
var value_type: ValueType = ValueType.ANY |
| 属性 | required |
var required: bool = false |
| 属性 | allow_null |
var allow_null: bool = true |
| 属性 | default_value |
var default_value: Variant = null |
| 属性 | dictionary_schema |
var dictionary_schema: GFDictionarySchema = null |
| 属性 | array_item_schema |
var array_item_schema: GFSchemaField = null |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 方法 | configure |
func configure( p_field_name: StringName, p_value_type: ValueType = ValueType.ANY, options: Dictionary = {} ) -> GFSchemaField: |
| 方法 | get_field_key |
func get_field_key() -> StringName: |
| 方法 | is_value_valid |
func is_value_valid(value: Variant) -> bool: |
| 方法 | coerce_value |
func coerce_value(value: Variant) -> Variant: |
| 方法 | try_coerce_value |
func try_coerce_value(value: Variant) -> Dictionary: |
| 方法 | validate_value |
func validate_value(value: Variant, context: Dictionary = {}) -> GFValidationReport: |
| 方法 | duplicate_field |
func duplicate_field() -> GFSchemaField: |
| 方法 | describe |
func describe() -> Dictionary: |
| 方法 | value_type_to_name |
static func value_type_to_name(type_id: ValueType) -> String: |
枚举¶
ValueType¶
- API：
public
enum ValueType { ## 不做类型约束。 ANY, ## 布尔值。 BOOL, ## 整数。 INT, ## 浮点数；int 也视为有效。 FLOAT, ## String。 STRING, ## StringName。 STRING_NAME, ## Vector2。 VECTOR2, ## Vector2i。 VECTOR2I, ## Vector3。 VECTOR3, ## Vector3i。 VECTOR3I, ## Color。 COLOR, ## Dictionary，可选嵌套 GFDictionarySchema。 DICTIONARY, ## Array，可选数组元素 GFSchemaField。 ARRAY, ## Object。 OBJECT, ## Resource。 RESOURCE, ## NodePath。 NODE_PATH, }
字段值类型。
属性¶
field_name¶
- API：
public
字段名。作为数组元素 schema 使用时可为空。
value_type¶
- API：
public
字段值类型。
required¶
- API：
public
是否必须出现在所属 Dictionary 中。
allow_null¶
- API：
public
是否允许 null 值。
default_value¶
- API：
public
默认值。GFDictionarySchema.apply_defaults() 会在缺字段时使用。
结构：
default_value: Variant default field value.
dictionary_schema¶
- API：
public
字典类型字段的嵌套 schema。
array_item_schema¶
- API：
public
数组类型字段的元素 schema。
metadata¶
- API：
public
可选元数据。GF 不解释其中业务字段。
结构：
metadata: Dictionary caller-defined schema metadata.
方法¶
configure¶
- API：
public
func configure( p_field_name: StringName, p_value_type: ValueType = ValueType.ANY, options: Dictionary = {} ) -> GFSchemaField:
配置字段声明。
参数：
| 名称 | 说明 |
|---|---|
p_field_name |
字段名。 |
p_value_type |
字段值类型。 |
options |
可选配置，支持 required、allow_null、default_value、dictionary_schema、array_item_schema 和 metadata。 |
返回：当前字段。
结构：
options: Dictionary schema field options.
get_field_key¶
- API：
public
获取稳定字段键。
返回：字段名。
is_value_valid¶
- API：
public
检查输入值是否符合字段声明。
参数：
| 名称 | 说明 |
|---|---|
value |
待检查值。 |
返回：符合声明时返回 true。
结构：
value: Variant value to validate.
coerce_value¶
- API：
public
将输入值转换为字段要求的类型。
参数：
| 名称 | 说明 |
|---|---|
value |
输入值。 |
返回：转换后的值。
结构：
value: Variant value to coerce.return: Variant coerced value.
try_coerce_value¶
- API：
public
尝试转换输入值并返回转换报告。
参数：
| 名称 | 说明 |
|---|---|
value |
输入值。 |
返回：包含 ok、value、message 的转换报告。
结构：
value: Variant value to coerce.return: Dictionary with ok, value, and message.
validate_value¶
- API：
public
校验字段值并返回报告。
参数：
| 名称 | 说明 |
|---|---|
value |
待校验值。 |
context |
可选上下文，支持 subject、path、key 和 schema_id。 |
返回：校验报告。
结构：
value: Variant value to validate.context: Dictionary validation context.
duplicate_field¶
- API：
public
创建同内容拷贝。
返回：新字段声明。
describe¶
- API：
public
导出字段声明摘要。
返回：字段声明字典。
结构：
return: Dictionary schema field description.
value_type_to_name¶
- API：
public
将字段类型转换为稳定名称。
参数：
| 名称 | 说明 |
|---|---|
type_id |
字段类型。 |
返回：类型名称。