📚 NbtList - 列表類型

一個NbtList代表一個列表，裡面儲存了一列 NBT 對象，類似於列表 / 數組這樣的數據結構。
通過NbtList對象的接口，才可以進行 NBT 列表所獨有的一些操作。

獲取一個 NBT 列表對象

從現有的NBT對象中解析獲取

詳見 NbtList - 列表類型 和 NbtCompound - 標籤類型 文檔

創建新的NBT列表對象

[JavaScript] new NbtList([data])
[Lua] NbtList([data])

• 參數：
• data : Array<NBT对象>（可選參數）
  傳入一個 NBT 對象構成的數組。數組中允許包含其他數組 / 對象結構， 但內容必須都為 NBT 對象。Null 會被視為 NBT.End
• 返回值：生成的NBT對象
• 返回值類型：NbtList
• 如果創建失敗，將拋出異常

對於某個一個NbtList類型的對象list，有如下這些接口

獲取列表長度

list.getSize()

• 返回值：此列表的長度
• 返回值類型：Integer

獲取某個下標位置儲存的數據類型

list.getTypeOf(index)

• 參數：
• index : Integer
  要查詢的目標下標
• 返回值：此下標處儲存的NBT的數據類型
• 返回值類型：Enum
• 如果要讀取的NBT不存在，將返回Null

可能的返回值有：NBT.End NBT.Byte NBT.Short NBT.Int NBT.Long
NBT.Float NBT.Double NBT.ByteArray NBT.String
NBT.List NBT.Compound

設置某個下標位置的NBT對象

list.setTag(index,tag)

• 參數：
• index : Integer
  要操作的目標下標
• tag: NBT对象
  要寫入的 NBT 對象。傳入 Null 時會寫入 NBT.End。目標下標必須已 存在，原有元素會被直接替換
• 返回值：寫入完畢的NBT列表（便於連鎖進行其他操作）
• 返回值類型：NbtList

讀取某個下標位置的NBT對象

list.getTag(index)

• 參數：
• index : Integer
  要操作的目標下標
• 返回值：下標位置的NBT對象
• 返回值類型：NBT对象
• 如果要讀取的NBT不存在，將返回Null

往列表末尾追加一個NBT對象

list.addTag(tag)

• 參數：
• tag: NBT对象
  要追加的 NBT 對象。傳入 Null 時會追加 NBT.End
• 返回值：追加完畢的NBT列表（便於連鎖進行其他操作）
• 返回值類型：NbtList

刪除某個下標位置的NBT對象

list.removeTag(index)

• 參數：
• index : Integer
  要刪除的目標下標
  下標不能超出有效下標的最大值
• 返回值：處理完畢的NBT列表（便於連鎖進行其他操作）
• 返回值類型：NbtList

一些協助 NBT 對象操作的方便函數

很明顯，在修改NBT的某些值的時候，純粹使用NBT對象會顯得麻煩而語法複雜。
因此，這裡還提供了一些簡化對象操作的方便函數，通過直接操作指定位置的數據，而避免通過NBT對象中轉，可以一定程度上降低代碼量

設置某個下標位置的具體數據

list.setEnd(index)
list.setByte(index,data)
list.setShort(index,data)
list.setInt(index,data)
list.setLong(index,data)
list.setFloat(index,data)
list.setDouble(index,data)
list.setByteArray(index,data)
list.setString(index,data)

• 參數：
• index : Integer
  要操作的目標下標
• data: Number / Float / Double / ByteBuffer / String
  要寫入的具體數據
  目標下標必須已存在，原有元素會被替換為對應的 NBT 類型
• 返回值：寫入完畢的NBT列表（便於連鎖進行其他操作）
• 返回值類型：NbtList

讀取某個下標位置的具體數據

list.getData(index)

• 參數：
• index : Integer
  要操作的目標下標
• 返回值：指定位置儲存的具體數據
• 返回值類型：Number / Float / Double / ByteBuffer / String，以對象儲存的數據類型為準
• 如果目標位置儲存的是List類型 NBT，將返回一個NbtList對象；如果目標位置儲存的是Compound類型 NBT，將返回一個NbtCompound對象
• 如果要讀取的NBT不存在，將返回Null

將List類型轉換為Array

list.toArray()

• 返回值：對應的數組 / 列表
• 返回值類型：Array

將List的內容轉換為腳本引擎數組 / 列表，把數據項都轉換為腳本引擎數據類型儲存於數組 / 列表的對應下標中，方便讀取和處理
如果List某一項儲存的是List或者Compound類型的 NBT，將在對應位置遞歸展開為Array或Object