Callable

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

描述

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

示例：

GDScriptC#

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 ( 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。

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.