CollectionService 管理具有 標籤 的實例群組 (收集)。標籤是套用於從伺服器複製到客戶端的實例的字串組。當保存位置時,也會將它們序列化。
CollectionService 的主要使用是註冊具有特定標籤的實例,您可以使用它們擴展其行為。如果你發現自己在許多不同的實例上添加相同的腳本,使用 CollectionService 的腳本可能會更好。
標籤可以通過此類別的方法,例如 AddTag() 或 RemoveTag() 來添加或移除。它們也可以直接在 Studio 中管理通過實個體、實例的 標籤 部分的屬性,或通過內置的 標籤編輯器 工具。
複製
當標籤複製時, 所有標籤在實例上同時複製 。因此,如果您從客戶端設置標籤在實例上,然後從服務伺服器上刪除/添加不同的標籤 不同 標籤在同一實例上,客戶端在實例上的本地標籤將被覆蓋。在 StreamingEnabled 位置,例如,當使用者離開客戶伺服器的傳輸區時,可以將實例卸下。如果這種情況的實例再次進入傳輸區域,屬性和標籤將從服務器重新同步。這可能導致由 LocalScripts 所做的變更被覆蓋/移除。
概要
方法
對 Instance 應用標籤。
返回體驗中所有標籤的數組。
返回在指定標籤被添加到實個體、實例時發出的信號。
返回一個信號,當指定標籤從實個體、實例中移除時發射。
返回遊戲中的一個標籤的多個實例。
取得應用於指定實個體、實例的所有標籤的數組。
檢查是否存在給定標籤的實例。
從實個體、實例中移除標籤。
活動
當標籤被添加到實例時,添加的標籤是該標籤在該空間的唯一出現,就會發生火災。
當標籤從實例中移除時,移除的標籤不再在任何地空間使用時,發生火災。
屬性
方法
AddTag
此方法對 Instance 應用標籤,如果標籤已應用到該個體、實例,則不做任何操作。成功添加標籤會發射由 GetInstanceAddedSignal() 創建的信號,使用指定的標籤。
警告
客戶端添加的標籤將在伺服器稍後在該實例上添加或移除標籤時掉落,因為伺服器會將所有標籤複製並覆蓋以前的標籤。
當標記實個體、實例時,常見的是某些資源被使用來提供標籤的功能,例如事件連線或表。為了防止記憶洩漏,當標籤不再需要時,清理這些(切斷、設為 nil 等)是一個好主意。當呼叫 RemoveTag() 、呼叫 Instance:Destroy() 或在與 GetInstanceRemovedSignal() 返回的信號連接的函數中時,請執行此操作。
參數
返回
GetInstanceAddedSignal
給予標籤 (字串),此方法返回一個信號,在兩個條件下發射:
標籤會被分配給 DataModel 使用 CollectionService:AddTag() 或 Instance:AddTag() 內的實例。
具有給定標籤的實例被添加為 DataModel 的子孫,例如設置 Instance.Parent 或類似。
使用相同標籤的後續呼叫此方法返回相同的訊號對物件。也可以考慮呼叫 GetTagged() 以獲得已標記的實例列表(因此如果它們已在 DataModel 中,就不會發射事件)。
也可以參閱GetInstanceRemovedSignal(),返回在相似條件下發生的事件。
參數
要監視的標籤。
返回
當您將標籤添加到實個體、實例時發生的事件。
範例程式碼
This code sample causes any BasePart with the tag Deadly to kill any Humanoid that touches it. It does this using a common pattern with CollectionService to listen for all parts with the tag and make a connection, then disconnect the connection when the tag is removed.
local CollectionService = game:GetService("CollectionService")
local tag = "Deadly"
local function onDeadlyPartTouched(otherPart)
if not otherPart.Parent then
return
end
local humanoid = otherPart.Parent:FindFirstChildOfClass("Humanoid")
if humanoid then
humanoid.Health = 0
end
end
-- Save the connections so they can be disconnected when the tag is removed
local connections = {}
local function onInstanceAdded(object)
-- Confirm that the object with this tag is a BasePart
if object:IsA("BasePart") then
connections[object] = object.Touched:Connect(onDeadlyPartTouched)
end
end
local function onInstanceRemoved(object)
-- If there is a stored connection on this object, disconnect/remove it
if connections[object] then
connections[object]:Disconnect()
connections[object] = nil
end
end
-- Listen for this tag being applied to objects
CollectionService:GetInstanceAddedSignal(tag):Connect(onInstanceAdded)
CollectionService:GetInstanceRemovedSignal(tag):Connect(onInstanceRemoved)
-- Also detect any objects that already have the tag
for _, object in pairs(CollectionService:GetTagged(tag)) do
onInstanceAdded(object)
end
GetInstanceRemovedSignal
給予標籤 (字串),此方法返回一個信號,在兩個條件下發射:
標籤會從 DataModel 使用 CollectionService:RemoveTag() 或 Instance:RemoveTag() 內的實例中移除。
具有給定標籤的實例會被移除為 DataModel 的子孫,例如通過取消 Instance.Parent 或類似操作。
使用相同標籤的後續呼叫此方法返回相同的訊號對物件。信號對於清理曾經擁有標籤的實例使用的資源有用,例如斷開連線。
也可以參閱GetInstanceAddedSignal(),返回在相似條件下發生的事件。
參數
要監視的標籤。
返回
當您從實個體、實例中移除標籤時發生的事件。
範例程式碼
This code sample causes any BasePart with the tag Deadly to kill any Humanoid that touches it. It does this using a common pattern with CollectionService to listen for all parts with the tag and make a connection, then disconnect the connection when the tag is removed.
local CollectionService = game:GetService("CollectionService")
local tag = "Deadly"
local function onDeadlyPartTouched(otherPart)
if not otherPart.Parent then
return
end
local humanoid = otherPart.Parent:FindFirstChildOfClass("Humanoid")
if humanoid then
humanoid.Health = 0
end
end
-- Save the connections so they can be disconnected when the tag is removed
local connections = {}
local function onInstanceAdded(object)
-- Confirm that the object with this tag is a BasePart
if object:IsA("BasePart") then
connections[object] = object.Touched:Connect(onDeadlyPartTouched)
end
end
local function onInstanceRemoved(object)
-- If there is a stored connection on this object, disconnect/remove it
if connections[object] then
connections[object]:Disconnect()
connections[object] = nil
end
end
-- Listen for this tag being applied to objects
CollectionService:GetInstanceAddedSignal(tag):Connect(onInstanceAdded)
CollectionService:GetInstanceRemovedSignal(tag):Connect(onInstanceRemoved)
-- Also detect any objects that already have the tag
for _, object in pairs(CollectionService:GetTagged(tag)) do
onInstanceAdded(object)
end
GetTagged
此方法返回一個包含給定標籤的實例數組,這些實例是 DataModel 的後裔。使用 CollectionService:RemoveTag() 或 Instance:RemoveTag() 移除標籤會確保此方法不會將它們返回。
如果您想偵測所有標籤的實例,兩者都提供 和 未來,使用此方法來循環過實例,同時也與由 GetInstanceAddedSignal() 返回的信號建立連接。
此方法不保證返回的實例順序。此外,例如,實例可能會被指派給它們的給定標籤,但不是 DataModel 的子孫,例如它的父親是 nil;此方法不會返回這些實例。
參數
要搜尋的標籤。
返回
標籤的所有實例的一個數陣。
範例程式碼
This code sample causes any BasePart with the tag Deadly to kill any Humanoid that touches it. It does this using a common pattern with CollectionService to listen for all parts with the tag and make a connection, then disconnect the connection when the tag is removed.
local CollectionService = game:GetService("CollectionService")
local tag = "Deadly"
local function onDeadlyPartTouched(otherPart)
if not otherPart.Parent then
return
end
local humanoid = otherPart.Parent:FindFirstChildOfClass("Humanoid")
if humanoid then
humanoid.Health = 0
end
end
-- Save the connections so they can be disconnected when the tag is removed
local connections = {}
local function onInstanceAdded(object)
-- Confirm that the object with this tag is a BasePart
if object:IsA("BasePart") then
connections[object] = object.Touched:Connect(onDeadlyPartTouched)
end
end
local function onInstanceRemoved(object)
-- If there is a stored connection on this object, disconnect/remove it
if connections[object] then
connections[object]:Disconnect()
connections[object] = nil
end
end
-- Listen for this tag being applied to objects
CollectionService:GetInstanceAddedSignal(tag):Connect(onInstanceAdded)
CollectionService:GetInstanceRemovedSignal(tag):Connect(onInstanceRemoved)
-- Also detect any objects that already have the tag
for _, object in pairs(CollectionService:GetTagged(tag)) do
onInstanceAdded(object)
end
GetTags
當提供 Instance 時,此方法會返回一個包含標籤的列表,用於應用於實個體、實例的標籤。
當您想要一次使用多個實例標籤時,此方法很有用,但檢查單一標籤的存在效率不高。為此,使用 HasTag() 檢查單一標籤。
參數
標籤應返回的實例。
返回
應用於給定實個體、實例的一組字串標籤。
範例程式碼
This code sample demonstrates adding, removing and querying a tag from an object using CollectionService.
local CollectionService = game:GetService("CollectionService")
local Workspace = game:GetService("Workspace")
local object = Workspace.Part
-- Add a tag
CollectionService:AddTag(object, "Deadly")
-- Query for a tag
if CollectionService:HasTag(object, "Deadly") then
print(object:GetFullName() .. " is deadly")
end
-- List tags on an object
local tags = CollectionService:GetTags(object)
print("The object " .. object:GetFullName() .. " has tags: " .. table.concat(tags, ", "))
-- Remove a tag
CollectionService:RemoveTag(object, "Deadly")
HasTag
此方法返回是否給定的 Instance 有標籤。
擴展到任何呼叫 GetTags() 在實例上返回的標籤,當使用此方法時,將返回 true 。
參數
返回
實例是否擁有標籤。
範例程式碼
This code sample demonstrates adding, removing and querying a tag from an object using CollectionService.
local CollectionService = game:GetService("CollectionService")
local Workspace = game:GetService("Workspace")
local object = Workspace.Part
-- Add a tag
CollectionService:AddTag(object, "Deadly")
-- Query for a tag
if CollectionService:HasTag(object, "Deadly") then
print(object:GetFullName() .. " is deadly")
end
-- List tags on an object
local tags = CollectionService:GetTags(object)
print("The object " .. object:GetFullName() .. " has tags: " .. table.concat(tags, ", "))
-- Remove a tag
CollectionService:RemoveTag(object, "Deadly")
RemoveTag
此方法從實個體、實例中移除標籤。成功移除標籤會發出由 GetInstanceRemovedSignal() 創建的信號,其中包含指定的標籤。
當移除標籤時,常見的是某些資源被使用來提供標籤的功能,例如事件連線或表。為了防止記憶洩漏,當標籤不再需要時,清理這些(切斷、設為 nil 等)是一個好主意。
參數
返回
範例程式碼
This code sample demonstrates adding, removing and querying a tag from an object using CollectionService.
local CollectionService = game:GetService("CollectionService")
local Workspace = game:GetService("Workspace")
local object = Workspace.Part
-- Add a tag
CollectionService:AddTag(object, "Deadly")
-- Query for a tag
if CollectionService:HasTag(object, "Deadly") then
print(object:GetFullName() .. " is deadly")
end
-- List tags on an object
local tags = CollectionService:GetTags(object)
print("The object " .. object:GetFullName() .. " has tags: " .. table.concat(tags, ", "))
-- Remove a tag
CollectionService:RemoveTag(object, "Deadly")