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...

Array¶

一种内置数据结构，包含一系列元素。

描述¶

通用数组，可以包含任意类型的多个元素，可以通过从 0 开始的数字索引进行访问。负数索引可以用来从后面数起，就像在 Python 中一样（-1 是最后一个元素、-2 是倒数第二，以此类推）。

示例：

var array = ["One", 2, 3, "Four"]
print(array[0]) # One。
print(array[2]) # 3。
print(array[-1]) # Four。
array[2] = "Three"
print(array[-2]) # Three。

var array = new Godot.Collections.Array{"One", 2, 3, "Four"};
GD.Print(array[0]); // One。
GD.Print(array[2]); // 3。
GD.Print(array[array.Count - 1]); // Four。
array[2] = "Three";
GD.Print(array[array.Count - 2]); // Three。

可以使用 + 运算符连接数组：

var array1 = ["One", 2]
var array2 = [3, "Four"]
print(array1 + array2) # ["One", 2, 3, "Four"]

// C# 数组无法进行数组串联，但 Godot.Collections.Array 可以。
var array1 = new Godot.Collections.Array{"One", 2};
var array2 = new Godot.Collections.Array{3, "Four"};
GD.Print(array1 + array2); // Prints [One, 2, 3, Four]

注意：数组总是通过引用来传递。要获得一个可以独立于原始数组而被修改的数组的副本，请使用 duplicate。

注意：不支持在遍历数组时擦除元素，这将导致不可预知的行为。

备注

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

构造函数¶

Array	Array ( )
Array	Array ( Array base, int type, StringName class_name, Variant script )
Array	Array ( Array from )
Array	Array ( PackedByteArray from )
Array	Array ( PackedColorArray from )
Array	Array ( PackedFloat32Array from )
Array	Array ( PackedFloat64Array from )
Array	Array ( PackedInt32Array from )
Array	Array ( PackedInt64Array from )
Array	Array ( PackedStringArray from )
Array	Array ( PackedVector2Array from )
Array	Array ( PackedVector3Array from )

方法¶

bool	all ( Callable method ) const
bool	any ( Callable method ) const
void	append ( Variant value )
void	append_array ( Array array )
void	assign ( Array array )
Variant	back ( ) const
int	bsearch ( Variant value, bool before=true ) const
int	bsearch_custom ( Variant value, Callable func, bool before=true ) const
void	clear ( )
int	count ( Variant value ) const
Array	duplicate ( bool deep=false ) const
void	erase ( Variant value )
void	fill ( Variant value )
Array	filter ( Callable method ) const
int	find ( Variant what, int from=0 ) const
Variant	front ( ) const
int	get_typed_builtin ( ) const
StringName	get_typed_class_name ( ) const
Variant	get_typed_script ( ) const
bool	has ( Variant value ) const
int	hash ( ) const
int	insert ( int position, Variant value )
bool	is_empty ( ) const
bool	is_read_only ( ) const
bool	is_same_typed ( Array array ) const
bool	is_typed ( ) const
void	make_read_only ( )
Array	map ( Callable method ) const
Variant	max ( ) const
Variant	min ( ) const
Variant	pick_random ( ) const
Variant	pop_at ( int position )
Variant	pop_back ( )
Variant	pop_front ( )
void	push_back ( Variant value )
void	push_front ( Variant value )
Variant	reduce ( Callable method, Variant accum=null ) const
void	remove_at ( int position )
int	resize ( int size )
void	reverse ( )
int	rfind ( Variant what, int from=-1 ) const
void	shuffle ( )
int	size ( ) const
Array	slice ( int begin, int end=2147483647, int step=1, bool deep=false ) const
void	sort ( )
void	sort_custom ( Callable func )

操作符¶

bool	operator != ( Array right )
Array	operator + ( Array right )
bool	operator < ( Array right )
bool	operator <= ( Array right )
bool	operator == ( Array right )
bool	operator > ( Array right )
bool	operator >= ( Array right )
Variant	operator [] ( int index )

构造函数说明¶

Array Array ( )

构造空的 Array。

Array Array ( Array base, int type, StringName class_name, Variant script )

从 base 数组创建具有类型的数组。

Array Array ( Array from )

返回与 from 相同的数组。如果你需要一个数组的副本，请使用 duplicate。

Array Array ( PackedByteArray from )

从 PackedByteArray 构造一个数组。

Array Array ( PackedColorArray from )

从 PackedColorArray 构造一个数组。

Array Array ( PackedFloat32Array from )

从 PackedFloat32Array 构造一个数组。

Array Array ( PackedFloat64Array from )

从 PackedFloat64Array 构造一个数组。

Array Array ( PackedInt32Array from )

从 PackedInt32Array 构造一个数组。

Array Array ( PackedInt64Array from )

从 PackedInt64Array 构造一个数组。

Array Array ( PackedStringArray from )

从 PackedStringArray 构造一个数组。

Array Array ( PackedVector2Array from )

从 PackedVector2Array 构造一个数组。

Array Array ( PackedVector3Array from )

从 PackedVector3Array 构造一个数组。

方法说明¶

bool all ( Callable method ) const

对数组中的每个元素调用提供的 Callable，如果 Callable 为数组中的所有元素返回 true，则返回 true。如果 Callable 为一个或多个数组元素返回 false，则此方法返回 false。

该可调用的方法应采用一个 Variant 参数（当前数组元素）并返回一个布尔值。

func _ready():
    print([6, 10, 6].all(greater_than_5))  # 输出 True（3/3 元素评估为 `true`）。
    print([4, 10, 4].all(greater_than_5))  # 输出 False（1/3 元素评估为 `true`）。
    print([4, 4, 4].all(greater_than_5))  # 输出 False（0/3 元素评估为 `true`）。
    print([].all(greater_than_5))  # 输出 True（0/0 元素评估为 `true`）。

    print([6, 10, 6].all(func(number): return number > 5))  # 输出 True。与上面的第一行相同，但使用 lambda 函数。

func greater_than_5(number):
    return number > 5

另请参见 any、filter、map 和 reduce。

注意：与依赖 filter 返回的数组大小不同，此方法会尽可能早地返回以提高性能（尤其是对于大型数组）。

注意：对于空数组，此方法总是返回 true。

bool any ( Callable method ) const

对数组中的每个元素调用提供的 Callable，如果 Callable 为数组中的* 一个或多个*元素返回 true，则返回 true。如果 Callable 为数组中的所有元素返回 false，则此方法返回 false。

可调用体的方法应接受一个 Variant 参数（当前数组元素）并返回一个布尔值。

func _ready():
    print([6, 10, 6].any(greater_than_5))  # 输出 True（3 个元素评估为 `true`）。
    print([4, 10, 4].any(greater_than_5))  # 输出 True（1 个元素评估为 `true`）。
    print([4, 4, 4].any(greater_than_5))  # 输出 False（0 个元素评估为 `true`）。
    print([].any(greater_than_5))  # 输出 False（0 个元素评估为 `true`）。

    print([6, 10, 6].any(func(number): return number > 5))  # 输出 True。与上面的第一行相同，但使用 lambda 函数。

func greater_than_5(number):
    return number > 5

另请参阅 all、filter、map 和 reduce。

注意：与依赖 filter 返回的数组大小不同，此方法会尽可能早地返回以提高性能（尤其是对于大型数组）。

注意：对于一个空数组，这个方法总是返回 false。

void append ( Variant value )

向数组末尾追加一个元素（push_back 的别名）。

void append_array ( Array array )

在该数组的末尾追加其他数组。

var array1 = [1, 2, 3]
var array2 = [4, 5, 6]
array1.append_array(array2)
print(array1) # 输出 [1, 2, 3, 4, 5, 6].

void assign ( Array array )

将另一个 array 的元素赋值到该数组中。调整数组大小以匹配 array。如果数组是有类型的，则执行类型转换。

Variant back ( ) const

返回数组的最后一个元素。如果数组为空，则打印一个错误并返回 null。

注意：调用这个函数与写入 array[-1] 不一样，如果数组是空的，当从编辑器运行时，按索引访问将暂停项目的执行。

int bsearch ( Variant value, bool before=true ) const

使用二进法查找已有值的索引（如果该值尚未存在于数组中，则为保持排序顺序的插入索引）。传递 before 说明符是可选的。如果该参数为 false，则返回的索引位于数组中该值的所有已有的条目之后。

注意：在未排序的数组上调用 bsearch 会产生预料之外的行为。

int bsearch_custom ( Variant value, Callable func, bool before=true ) const

使用二分法和自定义比较方法查找已有值的索引（如果该值尚未存在于数组中，则为保持排序顺序的插入索引）。传递 before 说明符是可选的。如果该参数为 false，则返回的索引位于数组中该值的所有已有条目之后。自定义方法接收两个参数（数组中的一个元素和搜索到的值），如果第一个参数小于第二个参数，则必须返回 true，否则返回 false .

注意：在未排序的数组上调用 bsearch_custom 会产生预料之外的行为。

void clear ( )

清空数组。相当于调用 resize 时指定大小为 0。

int count ( Variant value ) const

返回元素在数组中出现的次数。

Array duplicate ( bool deep=false ) const

返回该数组的副本。

deep 为 true 时会执行深拷贝：所有嵌套数组和字典都将被复制，且不会与原始数组共享。为 false 时则进行浅拷贝，并保留对原始嵌套数组和字典的引用，因此修改副本中的子数组或字典，也会影响源数组中引用的子数组或字典。请注意，无论 deep 如何设置，任何 Object 派生的元素都是浅拷贝的。

void erase ( Variant value )

从数组中移除第一个匹配的值。如果数组中不存在该值，则什么也不会发生。要通过索引移除元素，请改用 remove_at。

注意：这个方法是就地操作的，不返回修改后的数组。

注意：在大型数组上，如果移除的元素靠近数组的开头（索引 0），则此方法会较慢。这是因为所有放置在移除元素之后的元素都必须重新索引。

注意：在遍历数组时不要移除条目。

void fill ( Variant value )

将该数组中的所有元素都设置为给定的值。通常与 resize 一起使用，用于创建给定大小的数组并对其元素进行初始化：

var array = []
array.resize(10)
array.fill(0) # 将 10 个元素都初始化为 0。

var array = new Godot.Collections.Array();
array.Resize(10);
array.Fill(0); // 将 10 个元素都初始化为 0。

注意：如果 value 为引用类型（派生自 Object、Array、Dictionary 等），那么会用同一个对象的引用填充该数组，即不会创建副本。

Array filter ( Callable method ) const

在数组中的每个元素上调用提供的 Callable，并返回一个新数组，其中包含调用方法后返回值为 true 的元素。

可调用的方法应该采用一个 Variant 参数（当前数组元素）并返回一个布尔值。

func _ready():
    print([1, 2, 3].filter(remove_1)) # 打印 [2, 3]。
    print([1, 2, 3].filter(func(number): return number != 1)) # 同上，但使用 lambda 函数。

func remove_1(number):
    return number != 1

另请参见 any、all、map 和 reduce。

int find ( Variant what, int from=0 ) const

在数组中搜索值并返回其索引，如果未找到则返回 -1 。可选地，可以传递起始搜索索引。

Variant front ( ) const

返回数组的第一个元素。如果数组为空，则打印错误并返回 null。

注意：调用这个函数和写 array[0] 是不一样的，如果数组为空，从编辑器运行时按索引访问将暂停项目执行。

int get_typed_builtin ( ) const

返回类型化数组的 Variant.Type 常量。如果该 Array 不是类型化的，则返回 @GlobalScope.TYPE_NIL。

StringName get_typed_class_name ( ) const

返回类型为 @GlobalScope.TYPE_OBJECT 的类型化 Array 的类名。

Variant get_typed_script ( ) const

返回与此类型化数组绑定的类名关联的脚本。

bool has ( Variant value ) const

如果该数组包含给定值，则返回 true。

print(["inside", 7].has("inside")) # 真
print(["inside", 7].has("outside")) # 假
print(["inside", 7].has(7)) # 真
print(["inside", 7].has("7")) # 假

var arr = new Godot.Collections.Array { "inside", 7 };
// has 被改名为 Contains
GD.Print(arr.Contains("inside")); // 真
GD.Print(arr.Contains("outside")); // 假
GD.Print(arr.Contains(7)); // 真
GD.Print(arr.Contains("7")); // 假

注意：这相当于使用 in 运算符，如下所示：

# 将评估为`true`。
if 2 in [2, 4, 6, 8]:
    print("包含！")

// 由于 C# 中没有关键字“in”，因此必须使用 Contains
var array = new Godot.Collections.Array { 2, 4, 6, 8 };
if (array.Contains(2))
{
    GD.Print("包含！");
}

int hash ( ) const

返回代表该数组及其内容的 32 位整数哈希值。

注意：内容相同的 Array 会得到一致的哈希值。然而，反之不然。返回一致的哈希值并不意味着数组相等，因为不同的数组可能因为哈希碰撞而得到一致的哈希值。

int insert ( int position, Variant value )

在给定的数组位置插入一个新值。位置必须合法，或者是在数组末尾（pos == size()）。操作成功时返回 @GlobalScope.OK，而如果操作失败则返回其他任意一个 Error 值。

注意：该方法在原地执行，不会返回修改过的数组。

注意：在较大的数组中，如果插入值的位置在数组偏前的位置，这个方法的运行速度会比较慢，因为在插入值后面所有的元素都要被重新索引。

bool is_empty ( ) const

该数组为空时，返回 true。

bool is_read_only ( ) const

如果该数组只读，则返回 true。见 make_read_only。如果数组是用 const 关键字声明的，则自动只读。

bool is_same_typed ( Array array ) const

如果该数组的类型与 array 相同，则返回 true。

bool is_typed ( ) const

如果该数组是类型化的，则返回 true。类型化数组只能存储与其关联类型的元素，能够为其 [] 运算符提供类型安全支持。类型化数组的方法仍然返回 Variant。

void make_read_only ( )

使该数组只读，即禁止修改该数组的元素。不适用于嵌套的内容，例如嵌套数组的内容。

Array map ( Callable method ) const

为数组中的每个元素调用提供的 Callable 并返回一个新数组，其中填充了该调用方法返回的值。

可调用的方法应该采用一个 Variant 参数（当前数组元素）并且可以返回任意 Variant。

func _ready():
    print([1, 2, 3].map(negate)) # 打印 [-1, -2, -3].
    print([1, 2, 3].map(func(number): return -number)) # 同上，但使用 lambda 函数。

func negate(number):
    return -number

另请参见 filter、reduce、any 和 all。

Variant max ( ) const

如果数组中包含的所有元素都是可比较的类型，则返回其中的最大值。如果无法比较，则返回 null。

要使用自定义比较器来查找最大值，可以使用 reduce。这个例子中会比较数组中的每个元素，并返回第一个最大值：

func _ready():
    var arr = [Vector2(0, 1), Vector2(2, 0), Vector2(1, 1), Vector2(1, 0), Vector2(0, 2)]
    # 这个例子中我们比较的是长度。
    print(arr.reduce(func(max, val): return val if is_length_greater(val, max) else max))

func is_length_greater(a, b):
    return a.length() > b.length()

Variant min ( ) const

如果数组中包含的所有元素都是可比较的类型，则返回其中的最小值。如果无法比较，则返回 null。

使用自定义比较器的示例见 max。

Variant pick_random ( ) const

从目标数组中返回一个随机值。如果数组为空，则打印一个错误并返回 null。

var array: Array[int] = [1, 2, 3, 4]
print(array.pick_random())  # 打印四个数字中的任何一个。

var array = new Godot.Collections.Array { 1, 2, 3, 4 };
GD.Print(array.PickRandom()); // 打印四个数字中的任何一个。

Variant pop_at ( int position )

移除并返回数组中位于 position 索引处的元素。如果 position 为负数，则认为是相对于该数组末尾的值。如果该数组为空，则返回 null，不会改动数组。数组访问越界时会输出错误消息，但如果数组为空时不会。

注意：在较大的数组上，这个方法会比 pop_back 慢，因为会对移除元素后的数组元素重新进行索引。数组越大，或者移除元素的索引越小，pop_at 就越慢。

Variant pop_back ( )

移除并返回数组中的末尾元素。如果数组为空，则返回 null，而不打印错误消息。另见pop_front。

Variant pop_front ( )

移除并返回数组的第一个元素。如果数组是空的，将不会输出任何错误信息并返回 null。另请参阅