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。