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 = {} |
| 属性 | validation_rules |
var validation_rules: Array[GFValidationRule] = [] |
| 方法 | 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: |
| 方法 | add_validation_rule |
func add_validation_rule(rule: GFValidationRule) -> bool: |
| 方法 | get_enabled_validation_rules |
func get_enabled_validation_rules() -> Array[GFValidationRule]: |
| 方法 | 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.
validation_rules¶
- API：
public - 首次版本：
6.0.0
字段级附加校验规则。 规则在基础类型、空值和嵌套 schema 校验通过后执行，用于表达范围、集合、 格式或项目自定义约束，而不把这些策略硬编码进字段类型。
结构：
validation_rules: Array[GFValidationRule] field-level validation rules.
方法¶
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 - 首次版本：
4.4.0
将输入值转换为字段要求的类型；转换失败时返回输入值副本。
参数：
| 名称 | 说明 |
|---|---|
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.
add_validation_rule¶
- API：
public - 首次版本：
6.0.0
添加字段级校验规则。
参数：
| 名称 | 说明 |
|---|---|
rule |
校验规则。 |
返回：添加成功返回 true。
get_enabled_validation_rules¶
- API：
public - 首次版本：
6.0.0
获取启用的字段级校验规则。
返回：规则数组副本。
duplicate_field¶
- API：
public
创建同内容拷贝。
返回：新字段声明。
describe¶
- API：
public
导出字段声明摘要。
返回：字段声明字典。
结构：
return: Dictionary schema field description.
value_type_to_name¶
- API：
public
将字段类型转换为稳定名称。
参数：
| 名称 | 说明 |
|---|---|
type_id |
字段类型。 |
返回：类型名称。