GFConfigTableSchema¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/config/gf_config_table_schema.gd - 模块：
Standard - 继承：
Resource - API：
public - 类别：资源定义 (
resource_definition) - 首次版本：
3.17.0
通用导表结构声明与校验器。 用于在导入期或运行时校验表数据结构，保持数据工具链可替换且不绑定业务表。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 属性 | table_name |
var table_name: StringName = &"" |
| 属性 | id_field |
var id_field: StringName = &"id" |
| 属性 | columns |
var columns: Array[GFConfigTableColumn] = [] |
| 属性 | 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 |
| 属性 | require_unique_id |
var require_unique_id: bool = false |
| 属性 | indexes |
var indexes: Array[GFConfigTableIndexDefinition] = [] |
| 属性 | references |
var references: Array[GFConfigTableReference] = [] |
| 属性 | record_validation_rules |
var record_validation_rules: Array[GFConfigValidationRule] = [] |
| 属性 | table_validation_rules |
var table_validation_rules: Array[GFConfigValidationRule] = [] |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 方法 | infer_from_records |
static func infer_from_records( inferred_table_name: StringName, table_data: Variant, options: Dictionary = {} ) -> GFConfigTableSchema: |
| 方法 | get_table_key |
func get_table_key() -> StringName: |
| 方法 | get_column |
func get_column(field_name: StringName) -> GFConfigTableColumn: |
| 方法 | has_column |
func has_column(field_name: StringName) -> bool: |
| 方法 | get_index |
func get_index(index_id: StringName) -> GFConfigTableIndexDefinition: |
| 方法 | has_index |
func has_index(index_id: StringName) -> bool: |
| 方法 | get_reference |
func get_reference(reference_id: StringName) -> GFConfigTableReference: |
| 方法 | has_reference |
func has_reference(reference_id: StringName) -> bool: |
| 方法 | get_column_names |
func get_column_names() -> PackedStringArray: |
| 方法 | validate_definition |
func validate_definition(options: Dictionary = {}) -> Dictionary: |
| 方法 | validate_record |
func validate_record(record: Dictionary, row_key: Variant = null, options: Dictionary = {}) -> Dictionary: |
| 方法 | validate_table |
func validate_table(table_data: Variant, options: Dictionary = {}) -> Dictionary: |
| 方法 | coerce_record |
func coerce_record(record: Dictionary) -> Dictionary: |
| 方法 | build_empty_record |
func build_empty_record(include_optional: bool = true) -> Dictionary: |
| 方法 | duplicate_schema |
func duplicate_schema() -> GFConfigTableSchema: |
| 方法 | describe |
func describe() -> Dictionary: |
属性¶
table_name¶
- API：
public
表名。为空时可由调用方自行决定表标识。
id_field¶
- API：
public
记录 ID 字段。为空时不检查记录 ID。
columns¶
- API：
public
字段声明列表。
结构：
columns: Array[GFConfigTableColumn]，定义当前表允许的字段和字段级校验规则。
allow_extra_fields¶
- API：
public
是否允许记录包含 schema 未声明的字段。
coerce_values¶
- API：
public
是否在校验前按字段声明尝试类型转换。
fail_on_coerce_error¶
- API：
public
启用 coerce_values 时，转换失败是否作为校验错误。
require_unique_id¶
- API：
public
校验整表时是否要求 id_field 唯一。
indexes¶
- API：
public
可选复合索引声明。唯一索引会参与表级校验。
结构：
indexes: Array[GFConfigTableIndexDefinition]，定义当前表的复合索引和唯一性约束。
references¶
- API：
public
可选跨表引用声明。引用目标由 GFConfigReferenceResolver 在多表上下文中校验。
结构：
references: Array[GFConfigTableReference]，定义当前表到其他表的引用关系。
record_validation_rules¶
- API：
public
可选记录级校验规则。规则会在字段结构校验后作用于整条记录。
结构：
record_validation_rules: Array[GFConfigValidationRule]，包含作用于单条记录的校验规则。
table_validation_rules¶
- API：
public
可选表级校验规则。规则会在行结构、唯一 ID 和索引校验后作用于整表。
结构：
table_validation_rules: Array[GFConfigValidationRule]，包含作用于整张表的校验规则。
metadata¶
- API：
public
可选元数据，供导入器、编辑器或项目层扩展使用。
结构：
metadata: Dictionary，保存导入器、编辑器或项目层附加到当前 schema 的元数据。
方法¶
infer_from_records¶
- API：
public
static func infer_from_records( inferred_table_name: StringName, table_data: Variant, options: Dictionary = {} ) -> GFConfigTableSchema:
从记录样本推导通用 schema。
参数：
| 名称 | 说明 |
|---|---|
inferred_table_name |
推导出的表名。 |
table_data |
Array[Dictionary] 或 Dictionary 形式的表数据。 |
options |
可选参数，支持 id_field、required_if_present_in_all_rows、allow_extra_fields、coerce_values。 |
返回：推导出的 schema；数据无效时返回空 schema。
结构：
table_data: Variant，支持 Array[Dictionary] 或 Dictionary，记录值必须为 Dictionary。options: Dictionary，可包含 id_field、required_if_present_in_all_rows、allow_extra_fields 和 coerce_values。
get_table_key¶
- API：
public
获取稳定表键。
返回：表名。
get_column¶
- API：
public
获取字段声明。
参数：
| 名称 | 说明 |
|---|---|
field_name |
字段名。 |
返回：找到时返回字段声明，否则返回 null。
has_column¶
- API：
public
检查字段声明是否存在。
参数：
| 名称 | 说明 |
|---|---|
field_name |
字段名。 |
返回：存在返回 true。
get_index¶
- API：
public
获取索引声明。
参数：
| 名称 | 说明 |
|---|---|
index_id |
索引标识。 |
返回：找到时返回索引声明，否则返回 null。
has_index¶
- API：
public
检查索引声明是否存在。
参数：
| 名称 | 说明 |
|---|---|
index_id |
索引标识。 |
返回：存在返回 true。
get_reference¶
- API：
public
获取引用声明。
参数：
| 名称 | 说明 |
|---|---|
reference_id |
引用标识。 |
返回：找到时返回引用声明，否则返回 null。
has_reference¶
- API：
public
检查引用声明是否存在。
参数：
| 名称 | 说明 |
|---|---|
reference_id |
引用标识。 |
返回：存在返回 true。
get_column_names¶
- API：
public
获取当前 schema 的字段名列表。
返回：字段名列表。
validate_definition¶
- API：
public
校验 schema 自身声明是否完整、一致。
参数：
| 名称 | 说明 |
|---|---|
options |
可选上下文，支持 source。 |
返回：校验报告字典。
结构：
options: Dictionary，可包含 source、line、column、row_index、column_index 和 row_locations。return: GFConfigValidationReport 兼容 Dictionary。
validate_record¶
- API：
public
func validate_record(record: Dictionary, row_key: Variant = null, options: Dictionary = {}) -> Dictionary:
校验单条记录。
参数：
| 名称 | 说明 |
|---|---|
record |
记录字典。 |
row_key |
可选行标识，用于错误报告。 |
options |
可选上下文，支持 source、line、row_index、row_locations。 |
返回：校验报告字典。
结构：
record: Dictionary，待校验的配置记录，键为字段名，值为字段数据。row_key: Variant，写入校验报告 issue 的行标识。options: Dictionary，可包含 source、line、column、row_index、column_index 和 row_locations。return: GFConfigValidationReport 兼容 Dictionary。
validate_table¶
- API：
public
校验整张表。
参数：
| 名称 | 说明 |
|---|---|
table_data |
Array[Dictionary] 或 Dictionary 形式的表数据。 |
options |
可选上下文，支持 source、row_locations。 |
返回：校验报告字典。
结构：
table_data: Variant，支持 Array[Dictionary] 或 Dictionary，记录值必须为 Dictionary。options: Dictionary，可包含 source、line、column、row_index、column_index 和 row_locations。return: GFConfigValidationReport 兼容 Dictionary。
coerce_record¶
- API：
public
按字段声明转换单条记录。
参数：
| 名称 | 说明 |
|---|---|
record |
输入记录。 |
返回：转换后的新记录。
结构：
record: Dictionary，待转换的配置记录，键为字段名，值为字段数据。return: Dictionary，转换后的记录副本。
build_empty_record¶
- API：
public
创建空记录模板。
参数：
| 名称 | 说明 |
|---|---|
include_optional |
为 true 时包含非必填字段。 |
返回：新记录字典。
结构：
return: Dictionary，键为字段名，值为字段默认值转换后的结果。
duplicate_schema¶
- API：
public
创建同内容拷贝，避免运行时修改污染共享 Resource。
返回：新 schema。
describe¶
- API：
public
导出 schema 摘要。
返回：schema 字典。
结构：
return: Dictionary，包含 table_name、id_field、columns、allow_extra_fields、coerce_values、fail_on_coerce_error、require_unique_id、indexes、references、record_validation_rules、table_validation_rules 和 metadata。