Array

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

描述

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

示例：

GDScriptC#

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。

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

GDScriptC#

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 ( 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 一起使用，用于创建给定大小的数组并对其元素进行初始化：

GDScriptC#

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。

GDScriptC#

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 运算符，如下所示：

GDScriptC#

# 将评估为`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。

GDScriptC#

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。另请参阅 pop_back。

注意：当数组元素很多时，由于 pop_front 每次调用时都要重新寻找数组所有元素的索引，所以会比 pop_back 慢很多。数组越大，pop_front 越慢。

void push_back ( Variant value )

在数组的末端追加一个元素。另请参阅 push_front。

void push_front ( Variant value )

在数组的开头添加一个元素。另请参阅 push_back。

注意：在大数组中，这个方法比 push_back 慢得多，因为每次调用它都会重新索引所有数组的元素。数组越大，push_front 的速度就越慢。

Variant reduce ( Callable method, Variant accum=null ) const

为数组中的每个元素调用给定的 Callable 并将结果累积在 accum 中。

该可调用体的方法接受两个参数：accum 的当前值，以及当前的数组元素。如果 accum 为 null（默认值），则会从第二个元素开始迭代，将第一个元素作为 accum 的初始值。

func _ready():
    print([1, 2, 3].reduce(sum, 10)) # 输出 16.
    print([1, 2, 3].reduce(func(accum, number): return accum + number, 10)) # 同上，但使用 lambda 函数。
func sum(accum, number):
    return accum + number

另见 map、filter、any、all。

void remove_at ( int position )

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

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

注意：在大数组中，如果被删除的元素靠近数组的开头（索引 0），这个方法会比较慢。这是因为所有放置在被移除元素之后的元素都要被重新索引。

注意：position 不能为负。要移除数组末尾的元素，请使用 arr.remove_at(arr.size() - (i + 1))。要移除数组末尾的元素并不返回值，请使用 arr.resize(arr.size() - 1)。

int resize ( int size )

调整数组的大小，让包含的元素数量发生变化。如果数组变小则清除多余元素，变大则新元素为 null。成功时返回 @GlobalScope.OK，操作失败时返回其他 Error 值。

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

void reverse ( )

将数组中的元素逆序排列。

int rfind ( Variant what, int from=-1 ) const

逆序搜索数组。还可以传递起始搜索位置索引。如果为负，则起始索引被视为相对于数组的结尾。

void shuffle ( )

将数组打乱，元素随机排列。该方法使用全局随机数生成器，与 @GlobalScope.randi 等方法一致。如果你想每次都使用新的种子，让打乱无法重现，则可以调用 @GlobalScope.randomize。

int size ( ) const

返回数组中元素的个数。

Array slice ( int begin, int end=2147483647, int step=1, bool deep=false ) const

返回该 Array 的切片，是从 begin（含）到 end（不含）的全新 Array。

begin 和 end 的绝对值会按数组大小进行限制，所以 end 的默认值会切到数组大小为止（即 arr.slice(1) 是 arr.slice(1, arr.size()) 的简写）。

如果 begin 或 end 为负，则表示相对于数组的末尾（即 arr.slice(0, -2) 是 arr.slice(0, arr.size() - 2) 的简写）。

如果指定了 step，则会用作原始元素的索引间距。这个参数可以为负，此时 begin 必须大于 end。例如，[0, 1, 2, 3, 4, 5].slice(5, 1, -2) 会返回 [5, 3]。

如果 deep 为 true，则每个元素都会按值复制，而不是按引用复制。

注意：要在 step 为负时包含第一个元素，请使用 arr.slice(begin, -arr.size() - 1, step)（即 [0, 1, 2].slice(1, -4, -1) 返回 [1, 0]）。

void sort ( )

对数组进行排序。

注意：排序所使用的算法并不稳定。也就是说，使用 sort 时相等的值之间的顺序可能会改变。

注意：字符串按字母顺序排序（与自然顺序相反）。当对一个以数字序列结尾的字符串数组进行排序时，这可能会导致意外的行为。请看下面的例子：

GDScriptC#

var strings = ["string1", "string2", "string10", "string11"]
strings.sort()
print(strings) # 输出 [string1, string10, string11, string2]

var strings = new Godot.Collections.Array { "string1", "string2", "string10", "string11" };
strings.Sort();
GD.Print(strings); // 输出 [string1, string10, string11, string2]

要执行自然顺序排序，可以使用 sort_custom 和 String.naturalnocasecmp_to，如下所示：

var strings = ["string1", "string2", "string10", "string11"]
strings.sort_custom(func(a, b): return a.naturalnocasecmp_to(b) < 0)
print(strings) # 输出 [string1, string2, string10, string11]

void sort_custom ( Callable func )

使用自定义的方法对数组进行排序。自定义方法接受两个参数（数组中的一对元素），并且必须返回 true 或者 false。对于两个元素 a 和 b，如果给定的方法返回 true，数组中的元素 b 将排在元素 a 之后。

注意：排序所使用的算法并不稳定。也就是说，使用 sort_custom 时相等的值之间的顺序可能会改变。

注意：你不能随机化返回值，因为堆排序算法期望确定的结果。随机化返回值将导致意外行为。

GDScriptC#

func sort_ascending(a, b):
    if a[0] < b[0]:
        return true
    return false
func _ready():
    var my_items = [[5, "Potato"], [9, "Rice"], [4, "Tomato"]]
    my_items.sort_custom(sort_ascending)
    print(my_items) # 输出 [[4, Tomato], [5, Potato], [9, Rice]].
    # Descending, lambda version.
    my_items.sort_custom(func(a, b): return a[0] > b[0])
    print(my_items) # 输出 [[9, Rice], [5, Potato], [4, Tomato]].

// Godot.Collections.Array 不支持自定义排序

操作符说明

bool operator != ( Array right )

将左操作数 Array 与右操作数 right Array 进行比较。如果大小或内容不相等，则返回 true，否则返回 false。

Array operator + ( Array right )

连接两个 Array，右操作数 right Array 加到左操作数指定的 Array 的末尾。例如，[1, 2] + [3, 4] 的结果是 [1, 2, 3, 4]。

bool operator < ( Array right )

对左操作数 Array 和右操作数 right Array 之间的各个索引进行比较，考虑两个数组的最高公共索引：遇到第一个不同的元素时，如果该元素较小则返回 true，如果该元素较大则返回 false。请注意，部分类型的存储数据可能导致本函数的递归调用。如果所有元素都相等，则比较两个数组的长度，如果左操作数 Array 元素较少则返回 false，否则返回 true。

bool operator <= ( Array right )

对左操作数 Array 和右操作数 right Array 之间的各个索引进行比较，考虑两个数组的最高公共索引：遇到第一个不同的元素时，如果该元素较小则返回 true，如果该元素较大则返回 false。请注意，部分类型的存储数据可能导致本函数的递归调用。如果所有元素都相等，则比较两个数组的长度，如果左操作数 Array 元素数量相等或较少则返回 true，否则返回 false。

bool operator == ( Array right )

将左操作数 Array 与 right Array 进行比较。如果数组的大小和内容相等，则返回 true，否则返回 false。

bool operator > ( Array right )

对左操作数 Array 和右操作数 right Array 之间的各个索引进行比较，考虑两个数组的最高公共索引：遇到第一个不同的元素时，如果该元素较大则返回 true，如果该元素较小则返回 false。请注意，部分类型的存储数据可能导致本函数的递归调用。如果所有元素都相等，则比较两个数组的长度，如果左操作数 Array 元素较多则返回 true，否则返回 false。

bool operator >= ( Array right )

对左操作数 Array 和右操作数 right Array 之间的各个索引进行比较，考虑两个数组的最高公共索引：遇到第一个不同的元素时，如果该元素较大则返回 true，如果该元素较小则返回 false。请注意，部分类型的存储数据可能导致本函数的递归调用。如果所有元素都相等，则比较两个数组的长度，如果左操作数 Array 元素数量相等或较多则返回 true，否则返回 false。

Variant operator [] ( int index )

该函数返回指定位置的 Variant 类型元素的引用。数组从索引0开始。 index 可以是一个从头开始的零或正值，也可以是一个从末尾开始的负值。访问越界的数组会导致运行时错误，这将导致在编辑器中运行时打印错误并暂停项目执行。

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.