Fonctions Collect, Clear et ClearCollect

Permet de créer et de supprimer des collections, ainsi que d’ajouter des enregistrements à une source de données.

Collect

S’applique à : Applications canevas Cartes Plug-ins low-code Dataverse Power Platform CLI

La fonction Collect ajoute des enregistrements à une source de données. Les éléments ajoutés sont du type :

• Une valeur unique : la valeur est placée dans le champ Value d’un nouvel enregistrement. Toutes les autres propriétés sont blank.
• Un enregistrement : chaque propriété nommée est placée dans la propriété correspondante d’un nouvel enregistrement. Toutes les autres propriétés sont vides.
• Une table : chaque enregistrement de la table est ajouté sous forme d’enregistrement séparé de la source de données, comme décrit ci-dessus. La table n’est pas ajoutée à un enregistrement sous forme de table imbriquée. Pour cela, incluez tout d’abord la table dans un enregistrement.

Si vous utilisez une collection, d’autres colonnes sont créées si nécessaire. Les colonnes d’autres sources de données sont définies par la source de données et aucune nouvelle colonne ne peut être ajoutée.

Si la source de données n’existe pas, une collection est créée.

Les collections sont parfois utilisées pour contenir les variables globales ou effectuer une copie temporaire d’une source de données. Les applications canevas dépendent de formules recalculées automatiquement lorsque l’utilisateur interagit avec une application. Les collections ne proposent pas cet avantage et peuvent compliquer la création et la compréhension de votre application. Avant d’utiliser une collection de cette manière, examinez l’utilisation des variables.

Vous pouvez également utiliser la fonction Patch pour créer des enregistrements dans une source de données.

La fonction Collect renvoie la source de données modifiée en tant que table. La fonction Collect peut uniquement être utilisée dans une formule de comportement.

Clear

S’applique à : Applications canevas

La fonction Clear supprime tous les enregistrements d’une collection, à l’exception des colonnes.

Notez que Clear fonctionne uniquement sur les collections et non sur d’autres sources de données. Utilisez RemoveIf( DataSource, true ) dans ce deuxième cas. Soyez prudent, car vous supprimez alors tous les enregistrements de la zone de stockage de la source de données, ce qui peut avoir une incidence sur d’autres utilisateurs.

Utilisez la fonction Remove pour supprimer les enregistrements de manière sélective.

Aucune valeur n’est renvoyée avec la fonction Clear. qui peut uniquement être utilisée dans une formule de comportement.

ClearCollect

S’applique à : Applications canevas Applications pilotées par modèle

La fonction ClearCollect supprime tous les enregistrements d’une collection, Et puis ajoute un ensemble différent d’enregistrements à la même collection. ClearCollect regroupe Clear et Collect dans une même fonction.

ClearCollect renvoie la collection modifiée en tant que table. La fonction ClearCollect peut uniquement être utilisée dans une formule de comportement.

Délégation

Lorsqu’elles sont utilisées avec une source de données, ces fonctions ne peuvent pas être déléguées. Seule la première partie de la source de données sera extraite, puis la fonction sera appliquée. Il se peut que le résultat ne représente pas une vue d’ensemble complète. Un avertissement peut apparaître au moment de la création pour vous rappeler cette limitation et pour vous suggérer d’utiliser d’autres alternatives lorsque cela est possible. Pour plus d’informations, consultez la Vue d’ensemble de la délégation.

Syntaxe

Collect( DataSource, Item, ... )

• DataSource : obligatoire. Source de données à laquelle ajouter des données. Si elle n’existe pas déjà, une collection est créée.
• Item(s) : obligatoire. Un ou plusieurs enregistrements ou tables à ajouter à la source de données.

Clear( Collection )

• Collection : obligatoire. Collection à effacer.

ClearCollect( Collection, Item, ... )

• Collection : obligatoire. Collection à effacer et à laquelle vous voulez ajouter des données.
• Item(s) : obligatoire. Un ou plusieurs enregistrements ou tables à ajouter à la source de données.

Exemples

Suppression et ajout d’enregistrements à une source de données

Dans ces exemples, vous devez effacer une collection appelée IceCream puis y ajouter des éléments. La source de données commence par le contenu suivant :

Formule	Description	Résultat
ClearCollect( IceCream, { Flavor: "Strawberry", Quantity: 300 } )	Efface toutes les données à partir de la collection IceCream, puis ajoute un enregistrement qui inclut une quantité de glace à la fraise.	La collection IceCream a également été modifiée.
Collect( IceCream, { Flavor: "Pistachio", Quantity: 40 }, { Flavor: "Orange", Quantity: 200 } )	Ajoute deux enregistrements à la collection IceCream avec une certaine quantité de glace à la pistache et de glace à l’orange.	La collection IceCream a également été modifiée.
Clear( IceCream )	Supprime tous les enregistrements de la collection IceCream.	La collection IceCream a également été modifiée.

Pour obtenir des exemples pas à pas de la création d’une collection, consultez Créer et mettre à jour une collection.

Enregistrements et tables

Ces exemples examinent comment les arguments d’enregistrement et de table Collect et ClearCollect sont gérés.

Formule	Description	Résultat
ClearCollect( IceCream, { Flavor: "Chocolate", Quantity: 100 }, { Flavor: "Vanilla", Quantity: 200 } )	Efface toutes les données et ajoute deux enregistrements à la collection IceCream qui inclut une quantité de glace au chocolat et à la vanille. Les enregistrements à ajouter sont fournis en tant qu’arguments individuels à la fonction.	La collection IceCream a également été modifiée.
ClearCollect( IceCream, Table( { Flavor: "Chocolate", Quantity: 100 }, { Flavor: "Vanilla", Quantity: 200 } ) )	Identique à l’exemple précédent, sauf que les enregistrements sont combinés dans une table et transmis via un seul argument. Le contenu du tableau est extrait enregistrement par enregistrement avant d’être ajouté au collection IceCream.	La collection IceCream a également été modifiée.
ClearCollect( IceCream, { MyFavorites: Table( { Flavor: "Chocolate", Quantity: 100 }, { Flavor: "Vanilla", Quantity: 200 } ) } )	Identique à l’exemple précédent, sauf que la table est encapsulée dans un enregistrement. Les enregistrements de la table ne sont pas extraits et à la place, la table entière est ajoutée en tant que cellule de l’enregistrement.	La collection IceCream a également été modifiée.