CollectionService

顯示已棄用項目

*此內容是使用 AI(Beta 測試版)翻譯,可能含有錯誤。若要以英文檢視此頁面,請按一下這裡

無法建立
服務

CollectionService 管理具有 標籤 的實例群組 (收集)。標籤是套用於從伺服器複製到客戶端的實例的字串組。當保存位置時,也會將它們序列化。

CollectionService 的主要使用是註冊具有特定標籤的實例,您可以使用它們擴展其行為。如果你發現自己在許多不同的實例上添加相同的腳本,使用 CollectionService 的腳本可能會更好。

標籤可以通過此類別的方法,例如 AddTag()RemoveTag() 來添加或移除。它們也可以直接在 Studio 中管理通過實個體、實例的 標籤 部分的屬性,或通過內置的 標籤編輯器 工具。

複製

當標籤複製時, 所有標籤在實例上同時複製 。因此,如果您從客戶端設置標籤在實例上,然後從服務伺服器上刪除/添加不同的標籤 不同 標籤在同一實例上,客戶端在實例上的本地標籤將被覆蓋。在 StreamingEnabled 位置,例如,當使用者離開客戶伺服器的傳輸區時,可以將實例卸下。如果這種情況的實例再次進入傳輸區域,屬性和標籤將從服務器重新同步。這可能導致由 LocalScripts 所做的變更被覆蓋/移除。

概要

方法

活動

屬性

方法

AddTag

()

此方法對 Instance 應用標籤,如果標籤已應用到該個體、實例,則不做任何操作。成功添加標籤會發射由 GetInstanceAddedSignal() 創建的信號,使用指定的標籤。

警告
  • 客戶端添加的標籤將在伺服器稍後在該實例上添加或移除標籤時掉落,因為伺服器會將所有標籤複製並覆蓋以前的標籤。

  • 當標記實個體、實例時,常見的是某些資源被使用來提供標籤的功能,例如事件連線或表。為了防止記憶洩漏,當標籤不再需要時,清理這些(切斷、設為 nil 等)是一個好主意。當呼叫 RemoveTag() 、呼叫 Instance:Destroy() 或在與 GetInstanceRemovedSignal() 返回的信號連接的函數中時,請執行此操作。

參數

instance: Instance
預設值:""
tag: string
預設值:""

返回

()

GetAllTags

平行寫入

返回體驗中所有標籤的數組。


返回

GetInstanceAddedSignal

給予標籤 (字串),此方法返回一個信號,在兩個條件下發射:

使用相同標籤的後續呼叫此方法返回相同的訊號對物件。也可以考慮呼叫 GetTagged() 以獲得已標記的實例列表(因此如果它們已在 DataModel 中,就不會發射事件)。

也可以參閱GetInstanceRemovedSignal(),返回在相似條件下發生的事件。

參數

tag: string

要監視的標籤。

預設值:""

返回

當您將標籤添加到實個體、實例時發生的事件。

範例程式碼

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.

Deadly Bricks using CollectionService

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

給予標籤 (字串),此方法返回一個信號,在兩個條件下發射:

使用相同標籤的後續呼叫此方法返回相同的訊號對物件。信號對於清理曾經擁有標籤的實例使用的資源有用,例如斷開連線。

也可以參閱GetInstanceAddedSignal(),返回在相似條件下發生的事件。

參數

tag: string

要監視的標籤。

預設值:""

返回

當您從實個體、實例中移除標籤時發生的事件。

範例程式碼

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.

Deadly Bricks using CollectionService

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

Instances
平行寫入

此方法返回一個包含給定標籤的實例數組,這些實例是 DataModel 的後裔。使用 CollectionService:RemoveTag()Instance:RemoveTag() 移除標籤會確保此方法不會將它們返回。

如果您想偵測所有標籤的實例,兩者都提供 未來,使用此方法來循環過實例,同時也與由 GetInstanceAddedSignal() 返回的信號建立連接。

此方法不保證返回的實例順序。此外,例如,實例可能會被指派給它們的給定標籤,但不是 DataModel 的子孫,例如它的父親是 nil;此方法不會返回這些實例。

參數

tag: string

要搜尋的標籤。

預設值:""

返回

Instances

標籤的所有實例的一個數陣。

範例程式碼

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.

Deadly Bricks using CollectionService

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() 檢查單一標籤。

參數

instance: Instance

標籤應返回的實例。

預設值:""

返回

應用於給定實個體、實例的一組字串標籤。

範例程式碼

This code sample demonstrates adding, removing and querying a tag from an object using CollectionService.

Using Tags and 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

參數

instance: Instance

用於檢查標籤存在的實例。

預設值:""
tag: string

要檢查的標籤。

預設值:""

返回

實例是否擁有標籤。

範例程式碼

This code sample demonstrates adding, removing and querying a tag from an object using CollectionService.

Using Tags and 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 等)是一個好主意。

參數

instance: Instance

要從標籤中移除的實例。

預設值:""
tag: string

要從實個體、實例中移除的標籤。

預設值:""

返回

()

範例程式碼

This code sample demonstrates adding, removing and querying a tag from an object using CollectionService.

Using Tags and 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")

活動

TagAdded

當標籤被添加到實例時,此事件發生,添加的標籤是該標籤在該空間的唯一出現。

參數

tag: string

TagRemoved

當標籤從實例中移除時,此事件會發生,且移除的標籤已不再在空間方任何地方使用。

參數

tag: string