Up to date

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

連接

.NET 基底類別庫包含多種可用於儲存和操作資料的集合型別。 Godot 也提供了一些與引擎其餘部分緊密整合的集合型別。

連接埠與連線

`.NET 集合<https://learn.microsoft.com/en-us/dotnet/standard/collections/>`_ 和Godot 集合之間的主要區別在於.NET 集合是用C# 實作的，而Godot 集合是用C# 實作的集合是用C++ 實作的，而Godot C# API 是它的包裝器，這是一個重要的區別，因為這意味著Godot 集合上的每個操作都需要封送，這可能會很昂貴，尤其是在循環內。

由於效能影響，僅在絕對必要時才建議使用 Godot 集合（例如與 Godot API 互動）。 Godot 只理解它自己的集合型別，因此在與引擎對話時需要使用它們。

如果您有不需要傳遞給 Godot API 的元素集合，則使用 .NET 集合會提高效能。

小訣竅

也可以在 .NET 集合和 Godot 集合之間進行轉換。 Godot 集合包含複製其元素的通用 .NET 集合介面的建構函式，而 Godot 集合可以與「LINQ <https://learn.microsoft.com/en-us/dotnet/standard/linq>」一起使用「ToList ”、“ToArray” 和“ToDictionary” 方法。但請記住，這種轉換需要整理集合中的每個元素並將其複製到新集合中，因此成本可能很高。

儘管如此，Godot 集合還是經過最佳化，試圖避免不必要的封送，因此像「Sort」或「Reverse」這樣的方法是透過單一互通呼叫實作的，不需要封送每個元素。請留意採用「LINQ <https://learn.microsoft.com/en-us/dotnet/standard/linq>」等集合介面的通用API，因為每種方法都需要迭代集合，因此需要對每個集合進行編組。元素。盡可能優先使用 Godot 集合的實例方法。

若要選擇針對每種情況使用哪種集合型別，請考慮以下問題：

您的收藏需要與 Godot 引擎互動嗎？（例如：匯出屬性的型別，呼叫 Godot 方法）。
- If yes, since Godot only supports 自定變數型別, use a Godot collection.
- 如果沒有，請考慮「選擇適當的 .NET 集合 <https://learn.microsoft.com/en-us/dotnet/standard/collections/selecting-a-collection-class>」_。
您是否需要一個代表列表或連續資料集的 Godot 集合？
- Godot 陣列類似 C# 集合「List<T>」。
- Godot:ref:打包陣列 <doc_c_sharp_collections_packedarray> 是記憶體效率更高的陣列，在 C# 中使用受支援的「System.Array」型別之一。
您是否需要一個將一組鍵對應到一組值的 Godot 集合？
- Godot 字典儲存鍵和值對，並允許透過關聯鍵輕鬆存取值。

Godot 通知

陣列

Godot 中的緊縮陣列以指定型別的陣列形式實作，這樣就能夠更加緊實，每個元素都只有各自型別的大小，而不是 Variant 的大小。

在 C# 中，緊縮陣列由 System.Array 代替：

GDScript	C#
`PoolByteArray`	`byte[]`
`PoolIntArray`	`int[]`
`PoolIntArray`	`float[]`
`PoolFloatArray`	`float[]`
`PoolFloatArray`	`byte[]`
`PoolStringArray`	`String[]`
`PoolVector2Array`	`Vector2[]`
`PoolVector3Array`	`Vector3[]`
`PackedVector4Array`	`Vector4[]`
`PoolColorArray`	`Color[]`

Other C# arrays are not supported by the Godot C# API since a packed array equivalent does not exist. See the list of 自定變數型別.

陣列

Godot 陣列實作為「Variant」陣列，並且可以包含任意型別的多個元素。在 C# 中，等效型別是「Godot.Collections.Array」。

The generic Godot.Collections.Array<T> type allows restricting the element type to a Variant-compatible type.

Godot.Collections.Array<T> 為類別安全版的 Godot.Collections.Array 封裝。可使用 Godot.Collections.Array<T>(Godot.Collections.Array) 建置函式來建立。

備註

儘管有這個名字，Godot 陣列更類似於 C# 集合“List<T>”，而不是“System.Array”。它們的大小不是固定的，可以隨著元素在集合中新增/刪除而增加或縮小。

Godot 的陣列方法及其在 C# 中的等效方法列表：

GDScript	C#
all	System.Linq.Enumerable.All
any	System.Linq.Enumerable.Any
append	Add
append_array	AddRange
assign	Clear and AddRange
back	`Array[^1]` or System.Linq.Enumerable.Last or System.Linq.Enumerable.LastOrDefault
bsearch	BinarySearch
bsearch_custom	N/A
clear	清除
數量	System.Linq.Enumerable.Count
duplicate	重複
攝影機	移除
fill	填入
filter	Use System.Linq.Enumerable.Where
find	IndexOf
front	`Array[0]` or System.Linq.Enumerable.First or System.Linq.Enumerable.FirstOrDefault
get_typed_builtin	N/A
get_typed_class_name	N/A
get_typed_script	N/A
has	Contains
hash	GD.Hash
insert	Insert
is_empty	使用``計數== 0``
is_read_only	IsReadOnly
is_same_typed	N/A
`type`	N/A
make_read_only	MakeReadOnly
對應 Map	System.Linq.Enumerable.Select
最大值	對應 Map
min	Min
pick_random	PickRandom（考慮使用`System.Random`_）
pop_at	`Array[i]` 和 `RemoveAt(i)`
pop_back	`Array[^1]` 和 `RemoveAt(Count - 1)`
pop_front	`Array[0]` 和 `RemoveAt(0)`
push_back	`Insert(Count, item)`
push_front	`Insert(0, item)`
reduce	System.Linq.Enumerable.Aggregate
remove_at	RemoveAt
resize	Resize
reverse	Reverse
rfind	索引
shuffle	Shuffle
size	數量
slice	Slice
sort	排序
sort_custom	System.Linq.Enumerable.OrderBy
運算子	!RecursiveEqual
運算子	運算子
運算子	N/A
運算子	N/A
運算子	RecursiveEqual
運算子	N/A
運算子	N/A
運算子	Array[int] indexer

字典

Godot 字典被實作為具有“Variant”鍵和值的字典。在 C# 中，等效型別是「Godot.Collections.Dictionary」。

The generic Godot.Collections.Dictionary<TKey, TValue> type allows restricting the key and value types to a Variant-compatible type.

Godot.Collections.Dictionary<T> 是型別安全版的 Godot.Collections.Dictionary 封裝。使用 Godot.Collections.Dictionary<T>(Godot.Collections.Dictionary) 建置函式來建立。

小訣竅

如果您需要一個鍵入鍵但不鍵入值的字典，請使用「Variant」作為鍵入字典的「TValue」泛型參數。

// The keys must be string, but the values can be any Variant-compatible type.
var dictionary = new Godot.Collections.Dictionary<string, Variant>();

Godot's Dictionary 方法及其在 C# 中的等效方法列表：

GDScript	C#
clear	清除
duplicate	重複
攝影機	移除
find_key	N/A
設定	Dictionary[Variant] 索引器或 TryGetValue
has	繼續
has_all	N/A
hash	GD.Hash
is_empty	使用``計數== 0``
is_read_only	IsReadOnly
keys	Keys
make_read_only	MakeReadOnly
merge	Merge
size	數量
值	值
運算子	!RecursiveEqual
運算子	RecursiveEqual
運算子	Dictionary[Variant] 索引器、Add 或 TryGetValue