GFBindableProperty

API Reference / Kernel / 类索引

• 路径：addons/gf/kernel/core/gf_bindable_property.gd
• 模块：Kernel
• 继承：RefCounted
• API：public
• 类别：协议与扩展点 (protocol)
• 首次版本：3.17.0

响应式数据绑定属性容器。 封装一个 Variant 值，当值发生变化时自动发出 value_changed 信号。 可用于 Controller 直接监听 Model 数据变化，无需通过事件总线中转。

成员概览

类型	名称	签名
信号	value_changed	signal value_changed(old_value: Variant, new_value: Variant)
属性	value	var value: Variant:
方法	_init	func _init(default_value: Variant = null) -> void:
方法	get_value	func get_value() -> Variant:
方法	set_value	func set_value(new_value: Variant) -> void:
方法	subscribe	func subscribe(callback: Callable, emit_current: bool = false) -> Callable:
方法	force_emit	func force_emit() -> void:
方法	mutate	func mutate(mutator: Callable) -> bool:
方法	append_to_array	func append_to_array(item: Variant) -> bool:
方法	append_array	func append_array(items: Array) -> bool:
方法	erase_from_array	func erase_from_array(item: Variant) -> bool:
方法	set_dictionary_value	func set_dictionary_value(key: Variant, new_value: Variant) -> bool:
方法	erase_dictionary_key	func erase_dictionary_key(key: Variant) -> bool:
方法	clear_collection	func clear_collection() -> bool:
方法	unbind	func unbind(node: Variant, callable: Callable) -> void:
方法	unbind_all	func unbind_all() -> void:
方法	unbind_all_node_bindings	func unbind_all_node_bindings() -> void:
方法	disconnect_all_subscribers	func disconnect_all_subscribers() -> void:
方法	bind_to	func bind_to(node: Node, callable: Callable) -> void:

信号

value_changed

• API：public

signal value_changed(old_value: Variant, new_value: Variant)

当属性值被设置为不同的新值时发出。 "type": "Variant", "description": "变化前的旧值。" } "type": "Variant", "description": "变化后的新值。" }

参数：

名称	说明
old_value	变化前的旧值。
new_value	变化后的新值。

结构：

• old_value {:
• new_value {:

属性

value

• API：public

var value: Variant:

当前属性值。设置该属性等价于调用 set_value()。 "type": "Variant", "description": "当前属性值。" }

结构：

• value {:

方法

_init

• API：public

func _init(default_value: Variant = null) -> void:

构造函数。 "type": "Variant", "description": "属性的初始值。" }

参数：

名称	说明
default_value	属性的初始值，默认为 null。

结构：

• default_value {:

get_value

• API：public

func get_value() -> Variant:

获取当前属性值。 "type": "Variant", "description": "当前存储的值。" }

返回：当前存储的值。

结构：

• return {:

set_value

• API：public

func set_value(new_value: Variant) -> void:

设置属性值。仅当新值与旧值不同时，才会更新并发出 value_changed 信号。 "type": "Variant", "description": "要设置的新值。" }

参数：

名称	说明
new_value	要设置的新值。

结构：

• new_value {:

subscribe

• API：public
• 首次版本：3.20.0

func subscribe(callback: Callable, emit_current: bool = false) -> Callable:

订阅属性变化，并返回取消订阅函数。

参数：

名称	说明
callback	变化回调，签名应为 func(old_value: Variant, new_value: Variant)。
emit_current	是否立即以当前值调用一次回调；为 true 时 old_value 和 new_value 都是当前值。

返回：可调用的取消订阅函数；callback 无效时返回空 Callable。

force_emit

• API：public

func force_emit() -> void:

强制发出 value_changed 信号。 适合在 Array、Dictionary 或 Object 发生原地变更后，由业务层显式通知监听者。

mutate

• API：public

func mutate(mutator: Callable) -> bool:

通过回调修改当前值并强制广播。

参数：

名称	说明
mutator	修改当前值的回调。

返回：回调有效时返回 true。

append_to_array

• API：public

func append_to_array(item: Variant) -> bool:

向当前 Array 追加一个元素。 "type": "Variant", "description": "要追加的元素。" }

参数：

名称	说明
item	要追加的元素。

返回：成功返回 true。

结构：

• item {:

append_array

• API：public

func append_array(items: Array) -> bool:

向当前 Array 追加多个元素。 "type": "Array", "description": "要追加的元素列表。" }

参数：

名称	说明
items	要追加的元素列表。

返回：成功返回 true。

结构：

• items {:

erase_from_array

• API：public

func erase_from_array(item: Variant) -> bool:

从当前 Array 删除一个元素。 "type": "Variant", "description": "要删除的元素。" }

参数：

名称	说明
item	要删除的元素。

返回：成功返回 true。

结构：

• item {:

set_dictionary_value

• API：public

func set_dictionary_value(key: Variant, new_value: Variant) -> bool:

设置当前 Dictionary 的一个键值。 "type": "Variant", "description": "Dictionary 键。" } "type": "Variant", "description": "Dictionary 新值。" }

参数：

名称	说明
key	键。
new_value	新值。

返回：成功返回 true。

结构：

• key {:
• new_value {:

erase_dictionary_key

• API：public

func erase_dictionary_key(key: Variant) -> bool:

从当前 Dictionary 删除一个键。 "type": "Variant", "description": "Dictionary 键。" }

参数：

名称	说明
key	键。

返回：成功返回 true。

结构：

• key {:

clear_collection

• API：public

func clear_collection() -> bool:

清空当前 Array 或 Dictionary。

返回：成功返回 true。

unbind

• API：public

func unbind(node: Variant, callable: Callable) -> void:

断开指定 Node 与 Callable 的绑定关系。 "type": "Variant", "description": "绑定生命周期的 Node；已失效对象会触发失效绑定清理。" }

参数：

名称	说明
node	绑定生命周期的节点；已失效对象会触发失效绑定清理。
callable	要解绑的回调函数。

结构：

• node {:

unbind_all

• API：public

func unbind_all() -> void:

断开所有由 bind_to() 创建的 Node 生命周期绑定。

unbind_all_node_bindings

• API：public

func unbind_all_node_bindings() -> void:

断开所有由 bind_to() 创建的 Node 生命周期绑定。

disconnect_all_subscribers

• API：public

func disconnect_all_subscribers() -> void:

断开 value_changed 信号上的所有订阅者，并清理 bind_to() 创建的 Node 生命周期绑定。

bind_to

• API：public

func bind_to(node: Node, callable: Callable) -> void:

绑定信号到一个 Node 的 Callable。当该 Node 退出场景树时，自动断开连接。

参数：

名称	说明
node	监听生命周期的节点。
callable	绑定的回调函数。