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