CollectionService
*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.
CollectionService gère des groupes ( collections ) d'instances avec des balises .Les balises sont des ensembles de chaînes appliquées aux instances qui se répliquent du serveur au client.Ils sont également sérialisés lorsque les lieux sont sauvegardés.
L'utilisation principale de CollectionService est d'enregistrer des instances avec des balises spécifiques que vous pouvez utiliser pour étendre leur comportement.Si vous vous retrouvez à ajouter le même script à de nombreuses instances différentes, un script qui utilise CollectionService peut être meilleur.
Les balises peuvent être ajoutées ou supprimées via les méthodes de cette classe telles que AddTag() ou RemoveTag() .Ils peuvent également être gérés directement dans Studio via la section balises des propriétés d'une instance, ou via l'outil éditeur de balises intégré.
Réplication
Lorsque les balises se répliquent, toutes les balises sur une instance se répliquent en même temps .Si vous définissez une balise sur une instance à partir du client, puis ajoutez/supprimez une balise différente sur la même instance du serveur, les balises locales de l'instance du client sont remplacées.Dans StreamingEnabled endroits, les instances peuvent être déchargées lorsqu'elles quittent la zone diffusée du client.Si une telle instance réentre dans la zone diffusée, les propriétés et les balises seront ré synchronisées depuis le serveur.Cela peut provoquer des modifications apportées par LocalScripts d'être écrasées/supprimées.
Résumé
Méthodes
Applique une balise à un Instance .
Retourne un tableau de toutes les balises dans l'expérience.
Renvoie un signal qui se déclenche lorsqu'une balise donnée est ajoutée à une instance.
Renvoie un signal qui se déclenche lorsqu'une balise donnée est supprimée d'une instance.
Retourne un ensemble d'instances dans le jeu avec une balise donnée.
Obtient un tableau de toutes les balises appliquées à une instance donnée.
Vérifiez si une instance a une balise donnée.
Supprime une balise d'une instance.
Évènements
Se déclenche lorsqu'une balise est ajoutée à une instance et que la balise ajoutée est la seule occurrence de cette balise dans l'emplacement.
Se déclenche lorsqu'une balise est supprimée d'une instance et que la balise supprimée n'est plus utilisée nulle emplacementailleurs.
Propriétés
Méthodes
AddTag
Cette méthode applique une balise à un Instance , ne faisant rien si la balise est déjà appliquée à cette instance.Ajouter avec succès une balise déclenchera un signal créé par GetInstanceAddedSignal() avec la balise donnée.
Avertissements
Les balises d'une instance qui ont été ajoutées côté client seront supprimées si le serveur ajoute ou supprime plus tard une balise sur cette instance car le serveur réplique toutes les balises ensemble et remplace les balises précédentes.
Lors du marquage d'une instance, il est courant que certaines ressources soient utilisées pour donner au tag sa fonctionnalité, par exemple des connexions d'événements ou des tables.Pour empêcher les fuites de mémoire, il est une bonne idée de les nettoyer (débrancher, réinitialiser à nil , etc.) lorsqu'elles ne sont plus nécessaires pour une balise.Faites ceci lorsque vous appelez RemoveTag() , appelez Instance:Destroy() ou dans une fonction connectée à un signal retourné par GetInstanceRemovedSignal() .
Paramètres
Retours
GetInstanceAddedSignal
Donné un tag (chaîne), cette méthode renvoie un signal qui se déclenche sous deux conditions :
La balise est attribuée à une instance dans le DataModel en utilisant CollectionService:AddTag() ou Instance:AddTag() .
Une instance avec le tag donné est ajoutée en tant que descendant du DataModel, par exemple en définissant Instance.Parent ou similaire.
Les appels ultérieurs à cette méthode avec le même tag renvoient le même objet de signal.Considérez également d'appeler GetTagged() pour obtenir une liste d'instances qui ont déjà une balise (et donc ne déclencheront pas l'événement s'elles sont déjà dans le DataModel ).
Voir aussi GetInstanceRemovedSignal() qui renvoie un événement qui se déclenche dans des conditions similaires.
Paramètres
La balise à surveiller.
Retours
Un événement qui se déclenche lorsque vous ajoutez la balise à une instance.
Échantillons de code
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)
endGetInstanceRemovedSignal
Donné un tag (chaîne), cette méthode renvoie un signal qui se déclenche sous deux conditions :
La balise est supprimée d'une instance dans le DataModel en utilisant CollectionService:RemoveTag() ou Instance:RemoveTag() .
Une instance avec le tag donné est supprimée comme descendant du DataModel, par exemple en désactivant Instance.Parent ou similaire.
Les appels ultérieurs à cette méthode avec le même tag renvoient le même objet de signal.Le signal est utile pour nettoyer les ressources utilisées par des instances qui avaient autrefois des balises, telles que la rupture des connexions.
Voir aussi GetInstanceAddedSignal() qui renvoie un événement qui se déclenche dans des conditions similaires.
Paramètres
La balise à surveiller.
Retours
Un événement qui se déclenche lorsque vous supprimez la balise d'une instance.
Échantillons de code
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)
endGetTagged
Cette méthode renvoie une collection d'instances avec un tag donné qui sont des descendants du DataModel.Enlever une balise en utilisant CollectionService:RemoveTag() ou Instance:RemoveTag() garantit que cette méthode ne les retourne pas.
Si vous voulez détecter toutes les instances avec une balise, les deux présentent et l'avenir, utilisez cette méthode pour itérer sur les instances tout en établissant également une connexion avec un signal retourné par GetInstanceAddedSignal() .
Cette méthode ne garantit pas l'ordre des instances retournées.De plus, il est possible que des instances puissent avoir la balise donnée leur être attribuée mais ne pas être une descendance du DataModel, par exemple, leur parent est nil ; cette méthode ne renverra pas de telles instances.
Paramètres
La balise à rechercher.
Retours
Un ensemble de toutes les instances avec la balise.
Échantillons de code
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)
endGetTags
Donné un Instance , cette méthode renvoie un tableau de chaînes qui sont les balises appliquées à l'instance.
Cette méthode est utile lorsque vous voulez faire quelque chose avec plusieurs balises d'instance à la fois, mais il est inefficace de vérifier l'existence d'une seule balise.Pour cela, utilisez HasTag() pour vérifier une seule balise.
Paramètres
L'instance dont les balises doivent être renvoyées.
Retours
Un ensemble de chaînes qui sont les balises appliquées à l'instance donnée.
Échantillons de code
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
Cette méthode renvoie si un donné Instance a une balise.
Par extension, toutes les balises retournées par un appel à GetTags() sur une instance retourneront true lorsqu'elles sont utilisées avec cette méthode.
Paramètres
L'instance à vérifier pour la présence d'une balise.
La balise à vérifier.
Retours
Si l'instance a la balise.
Échantillons de code
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
Cette méthode supprime une balise d'une instance. Le retrait réussi d'une balise déclenchera un signal créé par GetInstanceRemovedSignal() avec la balise donnée.
Lors de l'élimination d'une balise, il est courant que certaines ressources soient utilisées pour donner à la balise sa fonctionnalité, par exemple des connexions d'événements ou des tables.Pour empêcher les fuites de mémoire, il est une bonne idée de les nettoyer (débrancher, réinitialiser à nil , etc.) lorsqu'elles ne sont plus nécessaires pour une balise.
Paramètres
L'instance pour supprimer la balise à partir de.
La balise à supprimer de l'instance.
Retours
Échantillons de code
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")Évènements
TagAdded
Cet événement se déclenche lorsqu'une balise est ajoutée à une instance et que la balise ajoutée est la seule occurrence de cette balise dans l'emplacement.
Paramètres
TagRemoved
Cet événement se déclenche lorsqu'une balise est supprimée d'une instance et que la balise supprimée n'est plus utilisée nulle emplacementailleurs.