Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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 array1 = ["One", 2]
var array2 = [3, "Four"]
print(array1 + array2) # ["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

另请参见 anyfiltermapreduce

注意:与依赖 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

另请参阅 allfiltermapreduce

注意:与依赖 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

返回该数组的副本。

deeptrue 时会执行深拷贝:所有嵌套数组和字典都将被复制,且不会与原始数组共享。为 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。

注意:如果 value 为引用类型(派生自 ObjectArrayDictionary 等),那么会用同一个对象的引用填充该数组,即不会创建副本。


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

另请参见 anyallmapreduce


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")) # 假

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

# 将评估为`true`。
if 2 in [2, 4, 6, 8]:
    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

另请参见 filterreduceanyall


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())  # 打印四个数字中的任何一个。

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 的当前值,以及当前的数组元素。如果 accumnull(默认值),则会从第二个元素开始迭代,将第一个元素作为 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

另见 mapfilteranyall


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

调用一次 resize 并分配新值比逐个添加新元素要快。

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


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

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

如果 beginend 为负,则表示相对于数组的末尾(即 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 时相等的值之间的顺序可能会改变。

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

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

要执行自然顺序排序,可以使用 sort_customString.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。对于两个元素 ab,如果给定的方法返回 true,数组中的元素 b 将排在元素 a 之后。

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

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

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

操作符说明

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 )

将左操作数 Arrayright 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 可以是一个从头开始的零或正值,也可以是一个从末尾开始的负值。访问越界的数组会导致运行时错误,这将导致在编辑器中运行时打印错误并暂停项目执行。