Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Callable

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

描述

可调用体 Callable 是表示函数的内置 Variant 类型。它可以是 Object 实例中的方法，也可以是用于不同目的的自定义可调用函数（请参阅 is_custom()）。与所有 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.0, -1.0) 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.0, -1.0) 42 Node(node.gd)::print_args”
    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("全军出击！"))

在 GDScript 中，可以将方法和全局函数作为 Callable 进行访问：

tween.tween_callback(node.queue_free)  # Object 的方法。
tween.tween_callback(array.clear)  # 内置类型的方法。
tween.tween_callback(print.bind("Test"))  # 全局函数。

注意：由于键不明确，Dictionary 不支持上述内容。

var dictionary = {"hello": "world"}

# 不行，“clear” 被视为一个键。
tween.tween_callback(dictionary.clear)

# 有效。
tween.tween_callback(Callable.create(dictionary, "clear"))

备注

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

构造函数

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

方法

Callable	bind(...) vararg const
Callable	bindv(arguments: Array)
Variant	call(...) vararg const
void	call_deferred(...) vararg const
Variant	callv(arguments: Array) const
Callable	create(variant: Variant, method: StringName) static
int	get_argument_count() 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	get_unbound_arguments_count() 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(peer_id: int, ...) vararg const
Callable	unbind(argcount: int) const

运算符

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

构造函数说明

Callable Callable() 🔗

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

Callable Callable(from: Callable)

构造给定 Callable 的副本。

Callable Callable(object: Object, method: StringName)

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

注意：对于内置 Variant 类型的方法，请改用 create()。

方法说明

Callable bind(...) vararg const 🔗

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

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

Callable bindv(arguments: Array) 🔗

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

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

Variant call(...) vararg const 🔗

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

void call_deferred(...) vararg const 🔗

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

func _ready():
    grab_focus.call_deferred()

public override void _Ready()
{
    Callable.From(GrabFocus).CallDeferred();
}

注意：延迟调用会在空闲时间处理。空闲时间主要发生在进程和物理帧的末尾。延迟调用将在其中一直运行，直到没有调用剩余为止，这意味着你可以从其他延迟调用中使用延迟调用，并且它们仍将在当前空闲时间周期中运行。这同样意味着你不应从延迟调用的方法（或从其调用的方法）中延迟调用其自身，因为这会导致无限递归，就像你直接调用该方法一样。

另见 Object.call_deferred()。

Variant callv(arguments: Array) const 🔗

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

Callable create(variant: Variant, method: StringName) static 🔗

为指定的 variant 中名为 method 的方法创建一个新的 Callable。为了表示内置 Variant 类型的方法，使用自定义可调用函数（请参阅 is_custom()）。如果 variant 是 Object，则将改为创建一个标准的可调用对象。

注意：该方法对于 Dictionary 类型始终是必需的，因为属性语法被用于访问其条目。当事先未知 variant 的类型时（对于多态），你也可以使用该方法。

int get_argument_count() const 🔗

返回该 Callable 应接受的所有参数的数量，包括可选参数。也就是说，结果中会减去使用 bind() 绑定的参数、加上使用 unbind() 解除绑定的参数。

Array get_bound_arguments() const 🔗

返回一个参数数组，其元素通过连续的bind() or unbind()调用绑定。这些参数会被追加到传给该调用的参数后面，而位于右侧的get_unbound_arguments_count()的参数已被预先从此调用中排除。

func get_effective_arguments(callable, call_args):
    assert(call_args.size() - callable.get_unbound_arguments_count() >= 0)
    var result = call_args.slice(0, call_args.size() - callable.get_unbound_arguments_count())
    result.append_array(callable.get_bound_arguments())
    return result

int get_bound_arguments_count() const 🔗

返回通过连续的bind()或unbind()调用绑定的参数总数。此总数与get_bound_arguments()返回的数组大小是一致的。详情参见get_bound_arguments()。

注意：方法get_bound_arguments_count()和get_unbound_arguments_count()都返回正值。

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 get_unbound_arguments_count() const 🔗

返回通过连续调用 bind() 和 unbind() 解绑的参数总数。详见 get_bound_arguments()。

注意：get_bound_arguments_count() 和 get_unbound_arguments_count() 方法都可以返回正值。

int hash() const 🔗

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

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

bool is_custom() const 🔗

如果该 Callable 是自定义可调用对象，则返回 true。使用自定义可调用对象：

用于绑定/解除绑定参数（参见 bind() 和 unbind()）；
用于表示内置 Variant 类型的方法（参见 create()）；
用于在 GDScript 中表示全局、lambda 和 RPC 函数；
用于核心、GDExtension 和 C# 中的其他目的。

bool is_null() const 🔗

如果这个 Callable 没有可以调用方法的目标，则返回 true。等价于 callable == Callable()。

注意：这与 not is_valid() 不同，使用 not is_null() 无法保证能够调用该可调用对象。请改用 is_valid()。

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(peer_id: int, ...) vararg const 🔗

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

Callable unbind(argcount: int) 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 !=(right: Callable) 🔗

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

bool operator ==(right: Callable) 🔗

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