Tâches courantes de script client
Le modèle d’objet d’API client est vaste et riche. En vous familiarisant avec l’écriture de scripts client, vous constatez que vous pouvez implémenter votre logique à l’aide de nombreux objets et méthodes d’API. Dans cette unité, nous allons examiner certaines des tâches courantes que vous effectuez, ainsi que les techniques permettant de les accomplir.
Accéder aux données de colonne Dataverse
Une colonne Dataverse se trouve dans le modèle d’objet en tant qu’objet d’attribut. La méthode getAttribute() de l’objet formContext vous permet de localiser rapidement un attribut spécifique ou tous les attributs présents sur le formulaire. Chaque objet d’attribut comprend des méthodes courantes et d’autres méthodes, selon le type de données d’attribut.
Remarque
Cet exemple de code suppose que les attributs et les contrôles utilisés sont présents. La plupart des méthodes renvoient null si les objets ne sont pas disponibles, donc les contrôles défensifs habituels doivent être utilisés dans la pratique.
Conseil
Les collections renvoyées par les méthodes d’API client possèdent des méthodes utiles vous permettant de parcourir les éléments. Pour en savoir plus, consultez Collections (référence d’API client) dans les applications pilotées par modèle - Power Apps.
| Tâche | Exemple |
|---|---|
| Accéder par nom | javascript var nameAttribute = formContext.getAttribute("name"); Affecte l’attribut pour la colonne Nom du compte à la variable nameAttribute. Si l’attribut n’est pas présent sur le formulaire, la méthode getAttribute renvoie la valeur null. |
| Accéder à tous les attributs | javascript var allAttributes = formContext.getAttribute(); Affecte un tableau de tous les attributs dans la collection formContext.data.entity.attributes à la variable allAttributes. |
Utiliser des attributs
| Tâche | Exemple |
|---|---|
| Obtenir la valeur d’un attribut | javascript var nameValue = formContext.getAttribute("name").getValue(); Affecte la valeur de la colonne Account Name à la variable nameValue. |
| Définir la valeur d’un attribut | javascript formContext.getAttribute("name").setValue("new name"); Définit la valeur de la colonne Account Name sur « nouveau nom ». |
| Obtient l’objet d’option sélectionné actuellement dans un attribut OptionSet (l’attribut OptionSet décrit la colonne de choix Dataverse) | javascript var addressTypeOption = formContext.getAttribute("address1_addresstypecode").getSelectedOption(); Affecte l’option sélectionnée dans la colonne Address Type à la variable addressTypeOption. |
| Déterminer si une valeur d’attribut a changé dans l’interface utilisateur depuis l’ouverture du formulaire | javascript var isNameChanged = formContext.getAttribute("name").getIsDirty(); Affecte une valeur booléenne qui indique si la valeur de la colonne Account Name a changé en la variable isNameChanged. |
| Changer si les données sont requises dans une colonne pour enregistrer un enregistrement | javascript formContext.getAttribute("creditlimit").setRequiredLevel("required"); Définit la colonne Crédit autorisé comme étant obligatoire. javascript formContext.getAttribute("creditlimit").setRequiredLevel("none"); Définit la colonne Crédit autorisé comme étant facultative. |
| Déterminer si les données d’un attribut sont envoyées lorsque l’enregistrement est enregistré | javascript var nameSubmitMode = formContext.getAttribute("name").getSubmitMode(); La valeur de la variable nameSubmitMode est un texte toujours, jamais ou modifié pour représenter la variable submitMode pour la colonne Account Name. |
| Contrôler si les données d’un attribut sont enregistrées lorsque l’enregistrement est enregistré | javascript formContext.getAttribute("name").setSubmitMode("always"); L’exemple force la valeur de la colonne Account Name à toujours être enregistrée, même si elle n’a pas changé. |
| Lorsque la sécurité de niveau de colonne a été appliquée à un attribut, déterminez si un utilisateur dispose des privilèges permettant d’effectuer des opérations de création, de lecture ou de mise à jour sur l’attribut. | javascript var canUpdateNameAttribute = formContext.getAttribute("name").getUserPrivilege().canUpdate; Affecte une valeur booléenne qui représente le privilège de l’utilisateur de redéfinir la colonne Account Name sur la variable canUpdateNameAttribute. |
Accéder aux contrôles de formulaire
| Tâche | Exemple |
|---|---|
| Accéder à tous les contrôles pour un attribut spécifique | javascript var nameControls = formContext.getAttribute("name").controls.get(); Affecte un tableau de tous les contrôles pour l’attribut Nom à la variable nameControls. La plupart des attributs sont représentés par un seul contrôle, mais ils peuvent avoir plusieurs contrôles si une même colonne a été ajoutée plusieurs fois au formulaire. |
| Accéder à un contrôle par son nom | javascript var nameControl = formContext.getControl("name"); Le premier contrôle ajouté à un formulaire pour une colonne porte le même nom que la colonne. Chacun des autres noms de contrôle se voit ajouter un numéro d’index. Par exemple, trois contrôles pour la colonne de nom sont nommés name, name1 et name2, respectivement. |
| Accéder à tous les contrôles | javascript var allControls = formContext.getControl(); Affecte un tableau de tous les contrôles dans la collection formContext.ui.controls à la variable allControls. |
Utiliser des contrôles de formulaire
Les objets de contrôle comme les objets d’attribut possèdent un ensemble commun de méthodes, quel que soit leur type. Ils possèdent également des méthodes spécialisées selon le type de contrôle.
| Tâche | Exemple |
|---|---|
| Déterminer si un contrôle est visible | javascript var isNameVisible = formContext.getControl("name").getVisible(); Affecte une valeur booléenne à la variable isNameVisible qui indique si la colonne Account Name est visible. |
| Masquer ou afficher un contrôle | javascript formContext.getControl("name").setVisible(false); Masque la colonne Account Name. |
| Obtenir une référence à l’attribut du contrôle | javascript var nameAttribute = formContext.getControl("name").getAttribute(); Affecte l’attribut pour le contrôle de la colonne Account Name à la variable nameAttribute. |
| Désactiver ou activer tous les contrôles pour un attribut | javascript formContext.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); }); N’oubliez pas que tout attribut peut avoir plusieurs contrôles. |
| Modifier l’intitulé d’un contrôle | javascript formContext.getControl("name").setLabel("Company Name"); Définit l’intitulé de la colonne Account Name sur le texte Nom de la société. |
| Obtenir le parent d’un contrôle | javascript var parentSection = formContext.getControl("name").getParent(); Affecte le contrôle parent de la colonne Account Name à la variable parentSection. |
| Définir le focus sur un contrôle | javascript formContext.getControl("name").setFocus(); Définit le focus d’entrée actif sur la colonne Account Name. |
Utiliser les onglets et sections
Chaque formulaire contient une collection d’onglets. Chaque onglet contient une collection de sections. Chaque section contient une collection de contrôles. Vous pouvez accéder par programme à ces éléments et utiliser leurs méthodes.
| Tâche | Exemple |
|---|---|
| Afficher ou masquer un onglet | javascript formContext.ui.tabs.get("general").setVisible(false); Masque l’onglet général. |
| Modifier l’intitulé d’un onglet | javascript formContext.ui.tabs.get("general").setLabel("Major"); Définit l’intitulé de l’onglet général sur le texte Majeur. |
| Afficher ou masquer une section | javascript formContext.getControl("industrycode").getParent().setVisible(false); Masque la section contenant la colonne Industry Code. |
Utiliser des données d’entité
Le tableau suivant contient des méthodes que vous pouvez utiliser pour obtenir des informations concernant l’enregistrement actif.
| Tâche | Exemple |
|---|---|
| Obtenir l’identifiant de l’enregistrement actif | javascript var recordId = formContext.data.entity.getId(); Affecte un identificateur unique d’enregistrement actif à la variable recordId. Si le formulaire est ouvert pour créer un enregistrement, la valeur null est renvoyée. |
| Enregistrer l’enregistrement actif | javascript formContext.data.entity.save(); Effectuez les actions équivalentes avec Enregistrer et fermer ou Enregistrer et nouveau à l’aide de saveandclose ou saveandnew. |
| Déterminez si des données de l’enregistrement actif ont été modifiées. | javascript var isDirty = formContext.data.entity.getIsDirty(); Affecte une valeur booléenne qui indique si la valeur d’une colonne du formulaire a été modifiée en variable isDirty. |