Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Callable¶

代表一个方法或一个独立函数的内置类型。

描述¶

可调用体 Callable 是内置的 Variant 类型，代表某个函数。可以是 Object 实例中的某个方法，也可以是与对象无关的独立函数，比如 lambda 函数。和所有 Variant 类型一样可以保存在变量里，传递给其他函数。最常用于信号回调。

示例：

func print_args(arg1, arg2, arg3 = ""):
    prints(arg1, arg2, arg3)

func test():
    var callable = Callable(self, "print_args")
    callable.call("hello", "world")  # 输出 "hello world ".
    callable.call(Vector2.UP, 42, callable)  # 输出 "(0, -1) 42 Node(node.gd)::print_args".
    callable.call("invalid")  # 无效调用，应当至少有 2 个参数。

// 不支持参数默认值。
public void PrintArgs(Variant arg1, Variant arg2, Variant arg3 = default)
{
    GD.PrintS(arg1, arg2, arg3);
}

public void Test()
{
    // Invalid calls fail silently.
    Callable callable = new Callable(this, MethodName.PrintArgs);
    callable.Call("hello", "world"); // 不支持参数默认值，应当有 3 个参数。
    callable.Call(Vector2.Up, 42, callable); // 输出 "(0, -1) 42 Node(Node.cs)::PrintArgs".
    callable.Call("invalid"); // 无效调用，应当有 3 个参数。
}

GDScript 中可以在方法里创建 lambda 函数。Lambda 函数是自定义的可调用体，不与 Object 实例关联。也可以为 Lambda 函数命名。该名称会显示在调试器中，也会在 get_method 中使用。

func _init():
    var my_lambda = func (message):
        print(message)

    # 输出 大家好呀！
    my_lambda.call("大家好呀！")

    # 发出 button_pressed 信号时输出 "全军出击！"。
    button_pressed.connect(func(): print("全军出击！"))

注意：Signal、Array、Dictionary 等原生类型的方法不是 Callable 类型，这是为了避免不必要的开销。如果你需要将这些方法作为 Callable 传递，请使用 Lambda 函数进行封装。

func _init():
    var my_dictionary = { "hello": "world" }

    # 不可行，因为`clear` 不是可调用体。
    create_tween().tween_callback(my_dictionary.clear)

    # 可行，因为 Lambda 是自定义可调用体。
    create_tween().tween_callback(func(): my_dictionary.clear())

备注

通过 C# 使用这个 API 时有显著的不同。详见 C# API 与 GDScript 的差异。

构造函数¶

Callable	Callable ( )
Callable	Callable ( Callable from )
Callable	Callable ( Object object, StringName method )

方法¶

Callable	bind ( ... ) vararg const
Callable	bindv ( Array arguments )
Variant	call ( ... ) vararg const
void	call_deferred ( ... ) vararg const
Variant	callv ( Array arguments ) const
Array	get_bound_arguments ( ) const
int	get_bound_arguments_count ( ) const
StringName	get_method ( ) const
Object	get_object ( ) const
int	get_object_id ( ) const
int	hash ( ) const
bool	is_custom ( ) const
bool	is_null ( ) const
bool	is_standard ( ) const
bool	is_valid ( ) const
void	rpc ( ... ) vararg const
void	rpc_id ( int peer_id, ... ) vararg const
Callable	unbind ( int argcount ) const

操作符¶

bool	operator != ( Callable right )
bool	operator == ( Callable right )

构造函数说明¶

Callable Callable ( )

构造空的 Callable，没有绑定对象和方法。

Callable Callable ( Callable from )

构造给定 Callable 的副本。

Callable Callable ( Object object, StringName method )

创建新的 Callable，使用指定对象 object 中名为 method 的方法。

方法说明¶

Callable bind ( ... ) vararg const

返回该 Callable 的副本，绑定其中的一个或多个参数。调用时，被绑定的参数在提供给 call 的参数之后传递。另见 unbind。

注意：这个方法与其他类似方法链式调用时，参数列表的修改顺序是从右至左的。

Callable bindv ( Array arguments )

返回该 Callable 的副本，绑定其中的一个或多个参数，参数从数组中读取。调用时，被绑定的参数在提供给 call 的参数之后传递。另见 unbind。

注意：这个方法与其他类似方法链式调用时，参数列表的修改顺序是从右至左的。

Variant call ( ... ) vararg const

调用该 Callable 所代表的方法。可以传递参数，必须与该方法的签名相匹配。

void call_deferred ( ... ) vararg const

使用延迟模式调用该 Callable 所代表的方法，即在当前帧的末尾调用。可以传递参数，必须与该方法的签名相匹配。

func _ready():
    grab_focus.call_deferred()

另见 Object.call_deferred。

Variant callv ( Array arguments ) const

调用该 Callable 所代表的方法。与 call 不同，这个方法需要所有参数都放在 arguments Array 之中。

Array get_bound_arguments ( ) const

返回绑定的参数（只要 get_bound_arguments_count 大于零）或者空数组（如果 get_bound_arguments_count 小于等于零）。

int get_bound_arguments_count ( ) const

返回通过成功调用 bind 或 unbind 绑定（或解绑）参数的总数。如果解绑参数的总数比绑定参数大，则这个函数的返回值小于零。

StringName get_method ( ) const

返回该 Callable 所代表的方法的名称。如果该可调用体是 GDScript lambda 函数，则返回该函数的名称或 "<anonymous lambda>"。

Object get_object ( ) const

返回该 Callable 所调用的对象。

int get_object_id ( ) const

返回该 Callable 中对象的 ID（见 Object.get_instance_id）。

int hash ( ) const

返回该 Callable 对象的 32 位哈希值。

注意：内容相同的 Callable 哈希值始终相同。反之则不然，返回的哈希值相同并不意味着可调用体相等，因为不同的可调用体可能由于哈希冲突而具有相同的哈希值。引擎在 hash 中使用 32 位哈希算法。

bool is_custom ( ) const

如果该 Callable 为自定义可调用体，则返回 true。自定义可调用体是由 bind 或 unbind 创建的。在 GDScript 中，lambda 函数也是自定义可调用体。

bool is_null ( ) const

如果该 Callable 没有调用方法的目标，则返回 true。

bool is_standard ( ) const

如果该 Callable 为标准可调用体，则返回 true。这个方法与 is_custom 相对。如果该可调用体为 lambda 函数，则返回 false。

bool is_valid ( ) const

如果该可调用体的对象存在，且分配了有效的方法名，或者为自定义可调用体，则返回 true。

void rpc ( ... ) vararg const

在所有已连接的对等体上执行 RPC（Remote Procedure Call，远程过程调用）。用于多人游戏，一般不可用，除非所调用的函数有 RPC 标记（使用 @GDScript.@rpc 或 Node.rpc_config）。在不支持的方法上调用该方法会导致出错。见 Node.rpc。

void rpc_id ( int peer_id, ... ) vararg const

在指定的对等体 ID（请参阅多人游戏文档）上执行 RPC（Remote Procedure Call，远程过程调用）。用于多人游戏，一般不可用，除非所调用的函数有 RPC 标记（使用 @GDScript.@rpc 或 Node.rpc_config）。在不支持的方法上调用该方法会导致出错。见 Node.rpc_id。

Callable unbind ( int argcount ) const

返回这个 Callable 的副本，解绑了一些参数。换句话说，调用新的可调用体时，用户提供的最后几个参数会被忽略，忽略几个由 argcount 决定。剩余的参数会被传递给该可调用体。这样传入的参数就能够比原本可调用体所能处理的参数要多，例如带有固定数量参数的信号。另见 bind。

注意：这个方法与其他类似方法链式调用时，参数列表的修改顺序是从右至左的。

func _ready():
    foo.unbind(1).call(1, 2) # 调用 foo(1).
    foo.bind(3, 4).unbind(1).call(1, 2) # 调用 foo(1, 3, 4)，注意改动的不是 bind 中的参数。

操作符说明¶

bool operator != ( Callable right )

如果两个 Callable 调用的目标不同，则返回 true。

bool operator == ( Callable right )

如果两个 Callable 调用的自定义目标相同，则返回 true。