`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 `Class.CollectionService:AddTag()|AddTag()` ou `Class.CollectionService:RemoveTag()|RemoveTag()` .Ils peuvent également être gérés directement dans Studio via la section [balises](/studio/properties#instance-tags) des propriétés d'une instance, ou via l'outil [éditeur de balises intégré](/studio/view-tab#windows-and-tools).

  ##### 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 `Class.Workspace.StreamingEnabled|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 `Class.LocalScript|LocalScripts` d'être écrasées/supprimées.

Cette fonction se déclenche lorsqu'un `Class.Configuration` , `Class.CustomEvent` , `Class.CustomEventReceiver` , `Class.Dialog` ou `Class.VehicleSeat` est ajouté au `Class.DataModel` .

CollectionService.ItemAdded

instance

S'enflamme lorsqu'un `Class.Configuration` , `Class.CustomEvent` , `Class.CustomEventReceiver` , `Class.Dialog` ou `Class.VehicleSeat` est ajouté au `Class.DataModel` .

Cette fonction se déclenche lorsqu'un `Class.Configuration` , `Class.CustomEvent` , `Class.CustomEventReceiver` , `Class.Dialog` ou `Class.VehicleSeat` est supprimé du `Class.DataModel` .

CollectionService.ItemRemoved

Se déclenche lorsqu'un `Class.Configuration` , `Class.CustomEvent` , `Class.CustomEventReceiver` , `Class.Dialog` ou `Class.VehicleSeat` est supprimé du `Class.DataModel` .

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.

CollectionService.TagAdded

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.

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.

CollectionService.TagRemoved

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.

Cette méthode applique une balise à un `Class.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 `Class.CollectionService:GetInstanceAddedSignal()|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 `Class.CollectionService:RemoveTag()|RemoveTag()` , appelez `Class.Instance:Destroy()` ou dans une fonction connectée à un signal retourné par `Class.CollectionService:GetInstanceRemovedSignal()|GetInstanceRemovedSignal()` .

CollectionService:AddTag

Applique une balise à un `Class.Instance` .

Retourne un tableau de toutes les balises dans l'expérience.

CollectionService:GetAllTags

Cette fonction renvoie toutes les instances d'une classe donnée qui sont dans le `Class.DataModel`.Fonctionne uniquement pour `Class.Configuration` , `Class.CustomEvent` , `Class.CustomEventReceiver` , `Class.Dialog` , et `Class.VehicleSeat` .

CollectionService:GetCollection

class

Renvoie toutes les instances d'une classe donnée qui sont dans le `Class.DataModel`.

This code sample causes any `Class.BasePart` with the tag `Deadly` to kill
any `Class.Humanoid` that touches it. It does this using a common pattern with
`Class.CollectionService` to listen for all parts with the tag and make a
connection, then disconnect the connection when the tag is removed.

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 `Class.DataModel` en utilisant `Class.CollectionService:AddTag()` ou `Class.Instance:AddTag()` .

  *   Une instance avec le tag donné est ajoutée en tant que descendant du `Class.DataModel`, par exemple en définissant `Class.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 `Class.CollectionService:GetTagged()|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 `Class.DataModel` ).

  Voir aussi `Class.CollectionService:GetInstanceRemovedSignal()|GetInstanceRemovedSignal()` qui renvoie un événement qui se déclenche dans des conditions similaires.

CollectionService:GetInstanceAddedSignal

Un événement qui se déclenche lorsque vous ajoutez la balise à une instance.

Renvoie un signal qui se déclenche lorsqu'une balise donnée est ajoutée à une instance.

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 `Class.DataModel` en utilisant `Class.CollectionService:RemoveTag()` ou `Class.Instance:RemoveTag()` .

  *   Une instance avec le tag donné est supprimée comme descendant du `Class.DataModel`, par exemple en désactivant `Class.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 `Class.CollectionService:GetInstanceAddedSignal()|GetInstanceAddedSignal()` qui renvoie un événement qui se déclenche dans des conditions similaires.

CollectionService:GetInstanceRemovedSignal

Un événement qui se déclenche lorsque vous supprimez la balise d'une instance.

Renvoie un signal qui se déclenche lorsqu'une balise donnée est supprimée d'une instance.

Cette méthode renvoie une collection d'instances avec un tag donné qui sont des descendants du `Class.DataModel`.Enlever une balise en utilisant `Class.CollectionService:RemoveTag()` ou `Class.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 `Class.CollectionService:GetInstanceAddedSignal()|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 `Class.DataModel`, par exemple, leur parent est `nil` ; cette méthode ne renverra pas de telles instances.

CollectionService:GetTagged

Un ensemble de toutes les instances avec la balise.

Retourne un ensemble d'instances dans le jeu avec une balise donnée.

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

Donné un `Class.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 `Class.CollectionService:HasTag()|HasTag()` pour vérifier une seule balise.

CollectionService:GetTags

L'instance dont les balises doivent être renvoyées.

Un ensemble de chaînes qui sont les balises appliquées à l'instance donnée.

Obtient un tableau de toutes les balises appliquées à une instance donnée.

Cette méthode renvoie si un donné `Class.Instance` a une balise.

  Par extension, toutes les balises retournées par un appel à `Class.CollectionService:GetTags()|GetTags()` sur une instance retourneront `true` lorsqu'elles sont utilisées avec cette méthode.

CollectionService:HasTag

L'instance à vérifier pour la présence d'une balise.

Vérifiez si une instance a une balise donnée.

Cette méthode supprime une balise d'une instance. Le retrait réussi d'une balise déclenchera un signal créé par `Class.CollectionService:GetInstanceRemovedSignal()|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.

CollectionService:RemoveTag

L'instance pour supprimer la balise à partir de.

CollectionService

Un service qui gère les collections d'instance en utilisant des balises attribuées.

`Instance` est la classe de base pour toutes les classes dans la hiérarchie de classe Roblox qui peuvent faire partie de l'arbre `Class.DataModel`.

  Il n'est pas possible de créer directement des objets racine `Instance` , mais le constructeur spécial `Datatype.Instance.new()` crée des objets via du code, en prenant le nom de la classe en paramètre et en retournant l'objet créé.

Demonstrates detecting changes to an instance's ancestry by connecting to the `Class.Instance.AncestryChanged` event.

The ChangingPart's Parent is set to different values overtime. The parent of the part is the part's ancestor, so the `Class.Instance.AncestryChanged` event will fire whenever it changes.

S'enflamme lorsque la propriété `Class.Instance.Parent` de l'objet ou l'une de ses ancêtres est modifiée.

  Cet événement inclut deux paramètres : `child` se réfère au `Class.Instance` dont le `Class.Instance.Parent` a été effectivement modifié, alors que `parent` se réfère au nouveau `Class.Instance.Parent` de cette instance.

  Vous pouvez utiliser cet événement pour suivre la suppression d'une instance dans Studio, comme la suppression manuelle dans l'Explorateur ou via un plugin.Si vous devez détecter quand une instance est détruite en utilisant `Class.Instance:Destroy()` , utilisez l'événement `Class.Instance.Destroying` à la place.

Instance.AncestryChanged

child

Le `Class.Instance` dont le `Class.Instance.Parent` a été modifié.

parent

Le nouveau `Class.Instance.Parent` de la `Class.Instance` dont le `Class.Instance.Parent` a été modifié.

S'enflamme lorsque la propriété `Class.Instance.Parent` de l'objet ou l'une de ses ancêtres est modifiée.

Cet événement se déclenche chaque fois que n'importe quel attribut est modifié sur l'instance, y compris lorsqu'un attribut est défini sur `nil`.Le nom de l'attribut modifié est transmis à la fonction connectée.

  Par exemple, le fragment de code suivant connecte la fonction `attributeChanged()` à tirer chaque fois que l'un des attributs de la partie change :

  ```lua
  local Workspace = game:GetService("Workspace")

  local part = Workspace.Part

  local function attributeChanged(attributeName)
  	print(attributeName, "changed")
  end

  part.AttributeChanged:Connect(attributeChanged)
  ```

  Voir aussi `Class.Instance:GetAttributeChangedSignal()` qui renvoie un événement qui se déclenche lorsqu'un attribut spécifique change.

Instance.AttributeChanged

attribute

Le nom de l'attribut qui a été modifié.

S'enflamme chaque fois qu'un attribut est modifié sur le `Class.Instance`.

This snippet prints the names of objects as they are added to the Workspace:

Feux après qu'un objet soit parenté à ceci `Class.Instance` .

  Remarque, lors de l'utilisation de cette fonction sur un client pour détecter les objets créés par le serveur, il est nécessaire d'utiliser `Class.Instance:WaitForChild()` lors de l'indexation des descendants de cet objet.C'est parce que l'objet et ses descendants ne sont pas garantis de se répliquer simultanément du serveur au client.Par exemple :

  ```
  local Workspace = game:GetService("Workspace")

  Workspace.ChildAdded:Connect(function(child)
  	-- Use WaitForChild() since descendants may not have replicated yet
  	local head = child:WaitForChild("Head")
  end)
  ```

  Notez que cette fonction ne fonctionne que pour les enfants immédiats du `Class.Instance` . Pour une fonction qui capture tous les descendants, utilisez `Class.Instance.DescendantAdded` .

  Voir aussi `Class.Instance.ChildRemoved` .

Instance.ChildAdded

Feux après qu'un objet soit parenté à ceci `Class.Instance` .

This snippet prints the names of objects as they are removed from the
Workspace:

Feux après qu'un enfant a été retiré de ce `Class.Instance` .

  Supprimé fait référence au moment où le parent d'un objet est modifié de cette `Class.Instance` à quelque chose d'autre que ceci `Class.Instance` .Notez que cet événement se déclenchera également lorsqu'un enfant est détruit (en utilisant `Class.Instance:Destroy()` ) car la fonction destroy définira le parent d'un objet à `nil` .

  Cette fonction ne fonctionne que pour les enfants immédiats du `Class.Instance`. Pour une fonction qui capture tous les descendants, utilisez `Class.Instance.DescendantRemoving`.

  Voir aussi `Class.Instance.ChildAdded` .

Instance.ChildRemoved

Le `Class.Instance` qui a été supprimé.

Feux après qu'un enfant a été retiré de ce `Class.Instance` .

This following example will print the name of any object that is added to the
Workspace:

Cet événement se déclenche après l'ajout d'un descendant à la `Class.Instance`.

  Comme il tire pour chaque descendant, parenter un objet à la `Class.Instance` fera tirer l'événement pour cet objet et tous ses descendants individuellement.

  Si vous ne vous souciez que des enfants directs de la , utilisez à la place.

  Voir aussi `Class.Instance.DescendantRemoving` .

Instance.DescendantAdded

descendant

Feux après qu'un descendant ait été ajouté à la `Class.Instance`.

The following example prints the name of any descendant as it is being removed
from the Workspace:

Cet événement se déclenche **immédiatement avant** que le parent `Class.Instance` de telle sorte qu'une instance **descendante** ne sera plus une descendante.`Class.Instance:Destroy()|Destroy()` change le `Class.Instance.Parent|Parent` d'une instance en `nil`, donc l'appel de cette méthode sur un descendant du parent provoquera le déclenchement de cet événement.

  Puisque cet événement se déclenche avant **la suppression du descendant, le parent du descendant sera inchangé au moment du déclenchement de cet événement** .Si le descendant est également un enfant direct du parent, cet événement se déclenchera avant .

  Si un descendant a des enfants, cet événement se déclenche d'abord avec le descendant, suivi de ses descendants.

  ##### Avertissement

  Cet événement se déclenche avec l'objet descendant qui est supprimé.Tenter de définir le `Class.Instance.Parent|Parent` du descendant sur autre chose échouera.Ci-dessous est un exemple qui montre cela :

  ```
  local Workspace = game:GetService("Workspace")

  Workspace.DescendantRemoving:Connect(function(descendant)
  	-- Do not manipulate the parent of the descendant in this function!
  	-- This event fires BECAUSE the parent was manipulated, and the change hasn't happened yet
  	-- Therefore, it is problematic to change the parent like this:
  	descendant.Parent = game
  end)

  local part = Instance.new("Part")
  part.Parent = Workspace
  part.Parent = nil
  ```

  Voir aussi `Class.Instance.DescendantAdded|DescendantAdded` .

Instance.DescendantRemoving

Le `Class.Instance` qui est en train d'être supprimé.

S'enflamme immédiatement avant que le descendant du `Class.Instance` soit supprimé.

This sample demonstrates how, when using Immediate signal behavior, an Instance being destroyed remains in place until the connected function yields.

This sample demonstrates how, when using Deferred signal behavior,
an Instance is destroyed before the signal fires.

La `Class.Instance` ne sera jamais supprimée de la mémoire tant qu'une fonction connectée l'utilise encore.Cependant, si la fonction produit à tout moment, le `Class.Instance` et ses descendants seront parentés à `nil` .

  Si la propriété `Class.Workspace.SignalBehavior` est définie sur `Enum.SignalBehavior.Immediate`, cet événement se déclenche immédiatement avant que `Class.Instance` ou l'un de ses ancêtres ne soit détruit avec `Class.Instance:Destroy()` .

  Si la propriété `Class.Workspace.SignalBehavior` est définie sur `Enum.SignalBehavior.Deferred`, cet événement se déclenche au prochain point de reprise, qui sera après que le `Class.Instance` ou l'un de ses ancêtres a été détruit avec `Class.Instance:Destroy()` .

  Avec le comportement `Enum.SignalBehavior.Deferred|Deferred`, la connexion d'un script à son propre événement `Class.Instance.Destroying` est problématique, car le script sera détruit avant que le rappel puisse être appelé (ce qui signifie qu'il ne sera pas exécuté).

  Lors de la suppression d'un `Class.Instance` dans Studio, comme la suppression manuelle via le [Explorateur](/studio/explorer) ou via un plugin, le `Class.Instance` n'est pas détruit.Au lieu de cela, le parent est défini sur `nil` que vous pouvez suivre avec `Class.Instance.AncestryChanged` .

Instance.Destroying

Il se déclenche immédiatement avant (ou est reporté jusqu'à ce que) l'instance soit détruite via `Class.Instance:Destroy()` .

Cet événement se déclenche chaque fois que toute propriété de style est modifiée sur l'instance, y compris lorsque une propriété est définie sur `nil` .

  ```lua
  local Players = game:GetService("Players")

  local player = Players.LocalPlayer
  local playerGui = player.PlayerGui
  local HUDContainer = playerGui:WaitForChild("HUDContainer")
  local meterBar = HUDContainer.MeterBar

  local function stylePropertyChanged()
  	print("Styled properties changed")
  end

  meterBar:StyledPropertiesChanged():Connect(stylePropertyChanged)
  ```

Instance.StyledPropertiesChanged

Il se déclenche chaque fois que toute propriété de style est modifiée sur l'instance, y compris lorsqu'une propriété est définie sur `nil` .

Instance.childAdded

Cette méthode applique une balise à l'instance, sans effet si la balise est déjà appliquée.Ajouter avec succès une balise déclenchera un signal créé par `Class.CollectionService: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 `Class.Instance:RemoveTag()`, appelez `Class.Instance:Destroy()` ou dans une fonction connectée à un signal retourné par `Class.CollectionService:GetInstanceRemovedSignal()` .

Instance:AddTag

Cette fonction détruit tous les enfants et les descendants d'une instance.

  ```
  local part = Instance.new("Part")

  -- Add some sparkles
  for i = 1, 3 do
  	local sparkles = Instance.new("Sparkles")
  	sparkles.Parent = part

    local sc = Instance.new("Sparkles")
    sc.Parent = sparkles
  end

  print("Children:", #part:GetChildren())  --> Children: 3

  part:ClearAllChildren()

  print("Children:", #part:GetChildren())  --> Children: 0
  ```

  Si vous ne souhaitez pas détruire **tous** les enfants et les descendants, utilisez `Class.Instance:GetChildren()` ou `Class.Instance:GetDescendants()` pour parcourir ces enfants/descendants et sélectionnez ce que vous devez détruire.Par exemple, l'exemple de code suivant détruira tous les `Class.BasePart|BaseParts` descendant d'un `Class.Model` :

  ```
  local Workspace = game:GetService("Workspace")

  local model = Workspace:FindFirstChild("TestModel")

  for _, descendant in model:GetDescendants() do
  	if descendant:IsA("BasePart") then
  		descendant:Destroy()
  	end
  end
  ```

Instance:ClearAllChildren

Cette fonction détruit tous les enfants d'une instance.

Demonstrates cloning a model using `Class.Instance:Clone()`.

`Clone()` crée une copie d'une instance et de tous ses descendants, en ignorant toutes les instances qui ne sont pas `Class.Instance.Archivable|Archivable` .Une copie de l'instance racine est retournée par cette méthode et son `Class.Instance.Parent|Parent` est défini sur `nil` .Notez que si l'instance elle-même a `Class.Instance.Archivable|Archivable` définie à `false`, cette fonction retournera `nil` .

  Si une propriété de référence telle que `Class.ObjectValue.Value` est définie dans une instance clonée, la valeur de la propriété de la copie dépend de la valeur de l'original :

  *   Si une propriété de référence se réfère à une instance qui a été **également** clonée, la copie se référera à la copie.
  *   Si une propriété de référence se réfère à un objet qui n'a pas été **cloné** , la même valeur est maintenue dans la copie.

Instance:Clone

Créer une copie d'une instance et de tous ses descendants, en ignorant les instances qui ne sont pas `Class.Instance.Archivable|Archivable` .

Demonstrates destroying a Part using the `Class.Instance:Destroy()` function.

This function is the correct way to dispose of objects that are no longer required.

Définit la propriété `Class.Instance.Parent` à `nil`, verrouille la propriété `Class.Instance.Parent` et déconnecte toutes les connexions, puis appelle `Destroy()` sur tous les enfants.Cette fonction est la bonne façon de se débarrasser d'objets qui ne sont plus nécessaires.

  L'élimination des objets inutiles est importante, car les objets inutiles et les connexions dans un endroit utilisent la mémoire qui peut entraîner des problèmes de performance sérieux au fil du temps.

  En tant que meilleure pratique après avoir appelé `Destroy()` sur un objet, définissez toutes les variables qui font référence à l'objet (ou à ses descendants) à `nil` .Cela empêche votre code d'accéder à quoi que ce soit ayant à voir avec l'objet.

  ```lua
  local part = Instance.new("Part")
  part.Name = "Hello, world"
  part:Destroy()
  -- Ne faites pas cela :
  print(part.Name)  --> "Bonjour, monde"
  -- Faites ceci pour empêcher la ligne ci-dessus de fonctionner :
  part = nil
  ```

  Une fois qu'une `Class.Instance` a été détruite par cette méthode, elle ne peut pas être réutilisée car la propriété `Class.Instance.Parent` est verrouillée.Pour **temporairement** supprimer un objet au lieu de le détruire, définissez `Class.Instance.Parent|Parent` à `nil` .Par exemple :

  ```
  local Workspace = game:GetService("Workspace")

  object.Parent = nil
  task.wait(2)
  object.Parent = Workspace
  ```

  Pour détruire un objet après un certain nombre de temps, utilisez `Class.Debris:AddItem()` .

Instance:Destroy

Définit la propriété `Class.Instance.Parent` à `nil`, verrouille la propriété `Class.Instance.Parent` et déconnecte toutes les connexions, puis appelle `Destroy()` sur tous les enfants.

Renvoie le premier ancêtre du `Class.Instance` dont le `Class.Instance.Name` est égal au nom donné.

  Cette fonction fonctionne en aval, ce qui signifie qu'elle commence à l'instant immédiat de l'instance `Class.Instance.Parent` et fonctionne vers le `Class.DataModel`.Si aucun ancêtre correspondant n'est trouvé, il renvoie `nil` .

  Le fragment de code suivant trouverait le premier ancêtre de l'objet nommé `Car` .

  ```
  local car = object:FindFirstAncestor("Car")
  ```

  Pour les variantes de cette fonction qui trouvent des ancêtres d'une classe spécifique, voir `Class.Instance:FindFirstAncestorOfClass()` et `Class.Instance:FindFirstAncestorWhichIsA()` .

Instance:FindFirstAncestor

name

Renvoie le premier ancêtre du `Class.Instance` dont le `Class.Instance.Name` est égal au nom donné.

Renvoie le premier ancêtre du `Class.Instance` dont le `Class.Object.ClassName` est égal à la classe donnée.

  Cette fonction fonctionne en aval, ce qui signifie qu'elle commence à l'instant immédiat de l'instance `Class.Instance.Parent` et fonctionne vers le `Class.DataModel`.Si aucun ancêtre correspondant n'est trouvé, il renvoie `nil` .

  Un usage commun de cette fonction est de trouver le appartient à. Par exemple :

  ```
  local model = part:FindFirstAncestorOfClass("Model")
  ```

  Cette fonction est une variante de `Class.Instance:FindFirstAncestor()` qui vérifie la propriété `Class.Object.ClassName` plutôt que `Class.Instance.Name`.`Class.Instance:FindFirstAncestorWhichIsA()` existe également, en utilisant la méthode `Class.Object:IsA()` au lieu de respecter l'héritage de classe.

Instance:FindFirstAncestorOfClass

className

Le `Class.Object.ClassName` à rechercher.

Renvoie le premier ancêtre du `Class.Instance` dont le `Class.Object.ClassName` est égal à la classe donnée.

Retourne le premier ancêtre du `Class.Instance` pour lequel `Class.Object:IsA()` renvoie vrai pour la classe donnée.

  Cette fonction fonctionne en aval, ce qui signifie qu'elle commence à l'instant immédiat de l'instance `Class.Instance.Parent` et fonctionne vers le `Class.DataModel`.Si aucun ancêtre correspondant n'est trouvé, il renvoie `nil` .

  Contrairement à `Class.Instance:FindFirstAncestorOfClass()`, cette fonction utilise `Class.Object:IsA()` qui respecte l'héritage de classe. Par exemple :

  ```
  print(part:IsA("Part"))  --> true
  print(part:IsA("BasePart"))  --> true
  print(part:IsA("Instance"))  --> true
  ```

  La suite du code suivante retournera donc le premier ancêtre , ou , indépendamment du fait qu'il s'agisse d'un , ou .

  ```
  local part = object:FindFirstAncestorWhichIsA("BasePart")
  ```

  Voir aussi `Class.Instance:FindFirstAncestor()` .

Instance:FindFirstAncestorWhichIsA

Retourne le premier ancêtre du `Class.Instance` pour lequel `Class.Object:IsA()` renvoie vrai pour la classe donnée.

Ce qui suit rechercherait dans l'espace de travail un nom d'objet « Brick ». S'il est trouvé, il changerait le nom de l'objet en « Foo ».

Retourne le premier enfant du `Class.Instance` avec le nom donné, ou `nil` si aucun tel enfant n'existe.Si l'argument facultatif `recursive` optionnel est `true`, cette fonction recherche tous les descendants plutôt que les enfants immédiats du `Class.Instance`.

  ##### Vérification de l'existence d'un objet

  `FindFirstChild()` est nécessaire si vous devez vérifier qu'un objet existe avant de continuer.Tenter d'indexer un enfant par son nom en utilisant l'opérateur point provoque une erreur si l'enfant n'existe pas.

  ```lua
  local Workspace = game:GetService("Workspace")

  -- Les erreurs suivantes se produisent si la partie n'existe pas dans l'espace de travail
  Workspace.Part.Transparency = 0.5
  ```

  Une meilleure approche consiste à utiliser `FindFirstChild()` pour vérifier d'abord `Part` , puis à utiliser une déclaration `if` pour exécuter du code qui en a besoin.

  ```lua
  local Workspace = game:GetService("Workspace")

  local part = Workspace:FindFirstChild("Part")
  if part then
  	part.Transparency = 0.5
  end
  ```

  ##### Trouver un enfant dont le nom correspond à une propriété

  Parfois, le `Class.Instance.Name|Name` d'un objet est le même que celui d'une propriété de son `Class.Instance.Parent|Parent` .Lors de l'utilisation de l'opérateur point, les propriétés prennent le pas sur les enfants s'ils partagent un nom.

  Dans l'exemple suivant, un `Class.Folder` appelé `Color` est ajouté à un `Class.Part` qui a également la propriété `Class.Part.Color`.Remarquez que `part.Color` se réfère à la valeur de propriété `Datatype.Color3`, pas à l'instance enfant `Class.Folder`.Un avantage de l'utilisation de `Class.Instance:FindFirstChild()|FindFirstChild()` est que l'introduction de nouvelles propriétés n'impose pas de risque pour votre code.

  ```lua
  local part = Instance.new("Part")
  local folder = Instance.new("Folder")
  folder.Name = "Color"
  folder.Parent = part
  local c1 = part.Color  -- La propriété
  local c2 = part:FindFirstChild("Color")  -- The child folder
  ```

  ##### Notes de performances

  `Class.Instance:FindFirstChild()|FindFirstChild()` prend environ 20 % plus de temps que l'utilisation de l'opérateur point et presque 8 fois plus de temps que simplement le stockage d'une référence à un objet.Vous devez donc éviter de l'appeler dans du code dépendant de la performance, comme dans des boucles serrées ou des fonctions connectées à `Class.RunService.Heartbeat` et `Class.RunService.PreRender` .Au lieu de cela, stockez le résultat dans une variable, ou envisagez d'utiliser `Class.Instance.ChildAdded|ChildAdded` ou `Class.Instance:WaitForChild()|WaitForChild()` pour détecter quand un enfant d'un nom donné devient disponible.

Instance:FindFirstChild

recursive

Si la recherche doit être menée de manière récursive ou non.

Renvoie le premier enfant du `Class.Instance` trouvé avec le nom donné.

Retourne le premier enfant du `Class.Instance` dont le `Class.Object.ClassName|ClassName` est égal au donné `className` .Contrairement à `Class.Instance:FindFirstChildWhichIsA()` , cette fonction ne renvoie que des objets dont la classe correspond à `className` , en ignorant l'héritage de classe.Si aucun enfant correspondant n'est trouvé, cette fonction renvoie `nil` .

Instance:FindFirstChildOfClass

Retourne le premier enfant du `Class.Instance` dont le `Class.Object.ClassName|ClassName` est égal au nom de classe donné.

Retourne le premier enfant du `Class.Instance` pour lequel `Class.Object:IsA()` renvoie vrai pour la classe donnée.

  Si aucun enfant correspondant n'est trouvé, cette fonction renvoie `nil` .Si l'argument récursif facultatif est vrai, cette fonction recherche tous les descendants plutôt que les enfants immédiats de la `Class.Instance` .

  Contrairement à `Class.Instance:FindFirstChildOfClass()`, cette fonction utilise `Class.Object:IsA()` qui respecte l'héritage de classe. Par exemple :

  ```lua
  print(part:IsA("Part")) --> vrai
  print(part:IsA("BasePart")) --> vrai
  print(part:IsA("Instance")) --> true
  ```

  Par conséquent, l'exemple de code suivant retournera le premier enfant `Class.BasePart` , indépendamment du fait qu'il s'agisse d'un `Class.WedgePart` , `Class.MeshPart` ou `Class.Part` .

  ```
  local part = object:FindFirstChildWhichIsA("BasePart")
  ```

  Les développeurs qui recherchent un enfant par nom devraient utiliser `Class.Instance:FindFirstChild()` à la place.

Instance:FindFirstChildWhichIsA

Retourne le premier enfant du `Class.Instance` pour lequel `Class.Object:IsA()` renvoie vrai pour la classe donnée.

Renvoie le premier descendant trouvé avec le donné `Class.Instance.Name` .

  Cette méthode est désactivée et ne peut pas être utilisée.Pour trouver le premier descendant d'une instance, envisagez d'utiliser le paramètre `recursive` sur `Class.Instance:FindFirstChild()` à la place.

Instance:FindFirstDescendant

Renvoie le premier descendant trouvé avec le donné `Class.Instance.Name` .

Si le `Class.Instance` est un `Class.Actor`, le `Class.Actor` lui-même est renvoyé.Sinon, son ancêtre le plus proche `Class.Actor` est retourné.Si aucun ancêtre n'est un `Class.Actor` , le résultat est `nil` .

Instance:GetActor

Retourne le `Class.Actor` associé à l'instance, si nécessaire.

Cette méthode renvoie la valeur qui a été attribuée au nom d'attribut donné. Si aucun attribut n'a été attribué, `nil` est renvoyé.

  Par exemple, le fragment de code suivant définit puis obtient la valeur de l'attribut `InitialPosition` de l'instance :

  ```lua
  local Workspace = game:GetService("Workspace")

  local part = Workspace.Part
  part:SetAttribute("InitialPosition", part.Position)

  local initialPosition = instance:GetAttribute("InitialPosition")
  print(initialPosition)
  ```

  ##### Voir aussi

  *   `Class.Instance:SetAttribute()` qui définit l'attribut avec le nom donné à la valeur donnée.
  *   `Class.Instance:GetAttributes()` qui renvoie un dictionnaire de paires clé-valeur pour chacun des attributs de l'instance.

Instance:GetAttribute

La valeur qui a été attribuée au nom d'attribut donné. Si aucun attribut n'a été attribué, `nil` est retournée.

Renvoie la valeur qui a été attribuée au nom d'attribut donné.

Cette fonction renvoie un événement qui se comporte exactement comme l'événement `Class.Object.Changed|Changed`, sauf qu'il ne se déclenche que lorsque l'attribut spécifique change ; efficacement, c'est similaire à `Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal()` pour les attributs.

  Il est généralement une bonne idée d'utiliser cette méthode au lieu d'une connexion à `Class.Object.Changed|Changed` avec une fonction qui vérifie le nom de l'attribut.Les appels ultérieurs à cette méthode sur le même objet avec le même nom d'attribut retournent le même événement.

  L'exemple de code suivant renvoie un signal qui déclenche la fonction `attributeChanged()` lorsque l'attribut de la partie `InitialPosition` change :

  ```lua
  local Workspace = game:GetService("Workspace")

  local part = Workspace.Part
  part:SetAttribute("InitialPosition", part.Position)

  local function attributeChanged()
  	print("Attribute changed")
  end

  part:GetAttributeChangedSignal("InitialPosition"):Connect(attributeChanged)
  ```

  Voir aussi `Class.Instance.AttributeChanged` qui se déclenche chaque fois que n'importe quel attribut est modifié sur l'instance.

Instance:GetAttributeChangedSignal

Le nom de l'attribut spécifié pour lequel le signal de changement est renvoyé.

Un événement qui se déclenche lorsque l'attribut donné change.

Renvoie un événement qui se déclenche lorsque l'attribut donné change.

Cette méthode renvoie un dictionnaire de paires clé-valeur pour chaque attribut où la clé est le nom de l'attribut et la valeur est une valeur non `nil` .

  Par exemple, le fragment de code suivant affiche les attributs et les valeurs d'une instance :

  ```lua
  local Workspace = game:GetService("Workspace")

  local part = Workspace.Part
  part:SetAttribute("InitialPosition", part.Position)
  part:SetAttribute("CanUse", true)

  for name, value in part:GetAttributes() do
  	print(name .. " = " .. value)
  end
  ```

  Voir aussi `Class.Instance:GetAttribute()` qui renvoie la valeur qui a été attribuée au nom d'attribut donné.

Instance:GetAttributes

Un dictionnaire de paires de chaîne → variantes pour chaque attribut où la chaîne est le nom de l'attribut et la variante est une valeur non nulle.

Renvoie un dictionnaire des attributs de l'instance.

The below would print the name of all objects currently in Workspace when ran.

Renvoie un tableau (une table numérotée) contenant tous les enfants directs de l'instance, ou chaque `Class.Instance` dont le `Class.Instance.Parent|Parent` est égal à l'objet.L'array peut être itérée en utilisant un boucle for numérique ou générique :

  ```lua
  local Workspace = game:GetService("Workspace")

  -- Exemple de boucle for numérique
  local children = Workspace:GetChildren()
  for i = 1, #children do
  	local child = children[i]
  	print(child.Name .. " is child number " .. i)
  end
  ```

  ```lua
  local Workspace = game:GetService("Workspace")

  -- Exemple générique de boucle while
  local children = Workspace:GetChildren()
  for i, child in children do
  	print(child.Name .. " is child number " .. i)
  end
  ```

  Les enfants sont triés par l'ordre dans lequel leur propriété `Class.Instance.Parent|Parent` a été définie à l'objet.

  Voir aussi la fonction `Class.Instance:GetDescendants()|GetDescendants`.

Instance:GetChildren

Un tableau contenant les enfants de l'instance.

Renvoie un tableau contenant tous les enfants de l'instance.

Renvoie une chaîne codée de l'ID de débogage utilisé internement par Roblox. Notez que :

  *   Cet élément est protégé. Tenter de l'utiliser dans un `Class.Script` ou `Class.LocalScript` provoquera une erreur.
  *   Un ID de débogage est un ID utilisé dans les processus de débogage.Il permet à un débogueur de lire chaque instruction avant qu'une application ne la traite.Tous les objets dans Roblox agissent comme des processus et chaque instruction d'exécution (ou «code») qui peut être débogée si nécessaire.
  *   Cela peut être utile pour les plugins qui doivent distinguer des objets similaires les uns des autres (tels que les objets qui partagent le même nom).

Instance:GetDebugId

scopeLength

Renvoie une chaîne codée de l'ID de débogage utilisé internement par Roblox.

GetDescendants is often used to do something to all the descendants that are a
particular type of object. The code in this example uses GetDescendants and
`Class.Instance:IsA()` to find all of the parts in the workspace and turns
them green.

Cette méthode d'objet renvoie une liste qui contient tous les descendants de cet objet.Contrairement à `Class.Instance:GetChildren()`, qui ne renvoie que les enfants immédiats d'un objet, cette méthode trouve chaque enfant de l'objet, chaque enfant de ces enfants, et ainsi de suite.

Instance:GetDescendants

Un tableau contenant les descendants de l'instance.

Renvoie un tableau contenant tous les descendants de l'instance.

This code sample demonstrates the behavior of `Class.Instance:GetFullName()`.
It shows how the function behaves when called on an object not in the
`DataModel` hierarchy, and it also shows how the return value does not escape
special characters.

This code sample re-implements the `Class.Instance:GetFullName()` function in
Lua.

Renvoie une chaîne décrivant l'ascendance de l'instance.La chaîne est une concaténation du `Class.Instance.Name|Name` de l'objet et de ses ancêtres, séparée par des périodes.Le `Class.DataModel` ( `game` ) n'est pas pris en compte.Par exemple, un `Class.Part` dans le `Class.Workspace` peut retourner `Class.Workspace.Part`.

  Lorsqu'on appelle sur un `Class.Instance` qui n'est pas un descendant du `Class.DataModel` , cette fonction prend en compte tous les ancêtres jusqu'à et y compris le plus ancien sans `Class.Instance.Parent|Parent` .

  Cette fonction est utile pour l'enregistrement et le débogage.Vous ne devriez pas essayer d'analyser la chaîne renvoyée pour toute opération utile ; cette fonction n'échappe pas les périodes (ou tout autre symbole) dans les noms d'objets.En d'autres termes, bien que son résultat semble souvent être un identifiant Luau valide, il n'est pas garanti.

Instance:GetFullName

Renvoie une chaîne décrivant l'ascendance de l'instance.

Cette méthode renvoie la valeur stylée ou explicitement modifiée de la propriété spécifiée, ou la valeur par défaut de la propriété si elle n'a pas été stylée/modifiée.Cela diffère légèrement de l'accès à la valeur de propriété directement, comme `[GuiObject].Rotation` , qui renvoie la valeur par défaut ou modifiée de la propriété.

  ```lua
  local Players = game:GetService("Players")
  local ReplicatedStorage = game:GetService("ReplicatedStorage")

  local player = Players.LocalPlayer
  local playerGui = player.PlayerGui
  local HUDContainer = playerGui:WaitForChild("HUDContainer")

  local coreSheet = ReplicatedStorage:FindFirstChild("CoreSheet")
  local rule = coreSheet:FindFirstChildWhichIsA("StyleRule")
  rule.Selector = "TextButton"

  -- Référence à un bouton
  local button = HUDContainer:FindFirstChildWhichIsA("TextButton")

  print(button:GetStyled("Rotation")) --> 0 (valeur par défaut)
  print(button.Rotation) --> 0 (valeur par défaut)

  -- Appliquer la rotation via la propriété règle de style
  rule:SetProperty("Rotation", 30)

  print(button:GetStyled("Rotation")) --> 30 (valeur stylée basée sur la règle)
  print(button.Rotation) --> 0 (valeur par défaut)

  -- Modifier/annuler explicitement la propriété style
  button.Rotation = 45

  print(button:GetStyled("Rotation")) --> 45 ( valeur modifiée )
  print(button.Rotation) --> 45 (modified value)
  ```

Instance:GetStyled

La valeur style ou explicitement modifiée de la propriété spécifiée, ou la valeur de propriété par défaut si elle n'a pas été style/modifiée.

Renvoie la valeur stylée ou explicitement modifiée de la propriété spécifiée, ou la valeur de propriété par défaut si elle n'a pas été stylée/modifiée.

Cette méthode renvoie un événement qui se comporte exactement comme l'événement `Class.Instance.StyledPropertiesChanged|StyledPropertiesChanged`, sauf qu'il ne se déclenche que lorsque la propriété de style donnée change.Il est généralement une bonne idée d'utiliser cette méthode au lieu d'une connexion à `Class.Instance.StyledPropertiesChanged|StyledPropertiesChanged` avec une fonction qui vérifie le nom de propriété.Les appels ultérieurs à cette méthode sur le même objet avec le même nom de propriété retournent le même événement.

  Notez que cet événement ne passera aucun argument à une fonction connectée, la valeur de la propriété modifiée devant être lue directement dans un script.

  ```lua
  local Players = game:GetService("Players")

  local player = Players.LocalPlayer
  local playerGui = player.PlayerGui
  local HUDContainer = playerGui:WaitForChild("HUDContainer")
  local meterBar = HUDContainer.MeterBar

  local function stylePropertyChanged()
  	print("Style property changed!")
  end

  meterBar:GetStyledPropertyChangedSignal("AnchorPoint"):Connect(stylePropertyChanged)
  ```

Instance:GetStyledPropertyChangedSignal

property

Nom de la propriété de style pour laquelle écouter les modifications.

Événement qui se déclenche lorsque la propriété de style donnée change.

Cette méthode renvoie une liste des balises appliquées à l'instance donnée, en tant que chaînes.Vous pouvez ajouter des balises dans Studio dans la fenêtre [propriétés](/studio/properties) ou en temps d'exécution avec `Class.Instance:AddTag()|AddTag()` .

  Cette méthode est utile lorsque vous voulez faire quelque chose avec plusieurs balises sur une instance à la fois.Cependant, il est inefficace d'utiliser cette méthode pour vérifier l'existence d'une seule balise ; au lieu de cela, utilisez `Class.Instance:HasTag()|HasTag()` pour vérifier une balise spécifique.

Instance:GetTags

Obtient une liste de toutes les balises appliquées à l'instance.

Cette méthode renvoie `true` si la balise fournie a été ajoutée à l'objet.Vous pouvez ajouter des balises dans Studio dans la fenêtre [propriétés](/studio/properties) ou en temps d'exécution avec `Class.Instance:AddTag()|AddTag()` .

Instance:HasTag

Vérifiez si l'instance a une balise donnée.

Demonstrates determining if one instance is the ancestor of another using `Class.Instance:IsAncestorOf()`

Workspace and SpawnLocation are ancestors of the SpawnLocation's decal.
Workspace is an ancestor of SpawnLocation.

SpawnLocation and its decal are descendants of Workspace, not ancenstors.
Decal is a descendant to SpawnLocation, not an ancestor.

Renvoie vrai si un `Class.Instance` est un ancêtre du descendant donné.

  Un `Class.Instance` est considéré comme l'ancêtre d'un objet si la valeur `Class.Instance.Parent` ou une des valeurs de ses parents `Class.Instance.Parent` est définie sur `Class.Instance` .

  Voir aussi, `Class.Instance:IsDescendantOf()` .

Instance:IsAncestorOf

Vrai si le `Class.Instance` est un ancêtre du descendant donné.

Renvoie vrai si un `Class.Instance` est un ancêtre du descendant donné.

Renvoie `true` si un `Class.Instance` est un descendant de l'ancêtre donné.

  Notez que `IsDescendantOf()` ne peut pas être utilisé avec un paramètre de `nil` pour vérifier si un objet a été supprimé.

  Voir aussi `Class.Instance:IsAncestorOf()` .

Instance:IsDescendantOf

ancestor

Vrai si le `Class.Instance` est un descendant de l'ancêtre donné.

Renvoie `true` si un `Class.Instance` est un descendant de l'ancêtre donné.

Renvoie `true` si la valeur stockée dans la propriété spécifiée est égale au code instantané par défaut.Par exemple, si l'exportation de la propriété `Class.TextLabel.TextSize|TextSize` de un `Class.TextLabel` indique `8` , alors l'appel de `IsPropertyModified("TextSize")` sur l'étiquette retournera `false` car `8` est la valeur par défaut pour `Class.TextLabel.TextSize` lorsque l'étiquette est créée via `Instance.new("TextLabel")` plutôt que d'être insérée via les flux de travail d'insertion de Studio.

  Notez que si cette méthode renvoie , le style n'affectera pas la propriété car la modification explicite d'une propriété aura priorité sur le style.

Instance:IsPropertyModified

Booléen indiquant si la propriété est modifiée.

Renvoie `true` si la valeur stockée dans la propriété spécifiée est égale au code instantané par défaut.

The following code demonstrates how a part can be re-added to the DataModel
after being removed:

Cette fonction définit le `Class.Instance.Parent` de l'objet à `nil` et fait de même pour tous ses descendants.

  Si l'objet est référencé avant d'être supprimé, il est possible de récupérer l'objet à un point ultérieur.

Instance:Remove

Définit l'objet `Parent` à `nil` et fait de même pour tous ses descendants.

Instance

`Instance` est la classe de base pour toutes les classes dans la hiérarchie de classe Roblox qui peuvent faire partie de l'arbre `Class.DataModel`.

/reference/engine/classes/CollectionService.yaml

CollectionService

Résumé

Propriétés

Méthodes

Événements

Propriétés

Méthodes

Événements