Xrm.Utility (référence côté client)
Date de publication : janvier 2017
S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
L'objet Xrm.Utility fournit un conteneur pour les fonctions utiles qui ne sont pas associées directement à la page actuelle.
Ces fonctions sont disponibles dans chaque page d'application prenant en charge la création de scripts. Vous pouvez les utiliser dans des scripts de formulaire ou dans les commandes du ruban. Pour les ressources Web HTML, elles sont disponibles lorsque vous incluez la page ClientGlobalContext.js.aspx. Pour plus d'informations, voir Fonction GetGlobalContext et ClientGlobalContext.js.aspx (référence côté client).
Fonctions
Boîtes de dialogue
Utilisez les messages d'affichage alertDialog et confirmDialog pour les utilisateurs et définissez le code pour qu'il s'exécute en fonction de leur réponse. Ces fonctions doivent être utilisées avec les clients mobiles Dynamics 365 (téléphones et tablettes) à la place des méthodes window.alert et window.confirm.Fonctionnalités natives des appareils (clients mobiles Dynamics 365)
Utilisez getBarcodeValue et getCurrentPosition pour utiliser les fonctionnalités natives des appareils mobiles pour récupérer la valeur de code-barres ou la position actuelle de l'appareil.isActivityType
Déterminez si une entité est une entité d'activité.openEntityForm
Ouvre un formulaire d’entité.openQuickCreate
Pour Mise à jour 1 de Microsoft Dynamics CRM Online 2015 ou version ultérieure, utilisez cette fonction pour ouvrir un nouveau formulaire de création rapide. Vous pouvez utiliser cette fonction pour définir les valeurs par défaut à l'aide des mappages d'attributs ou d'attributs spécifiques. Si l'utilisateur enregistre l'enregistrement, vous pourrez recueillir une référence à l'enregistrement créé.openWebResource
Ouvre une ressource web HTML.
Boîtes de dialogue
Il existe deux types de boîtes de dialogue : alertDialog et confirmDialog. Elles sont incluses pour être utilisées avec des scripts qui fonctionnent avec les clients mobiles Dynamics 365 (téléphones et tablettes). Les clients mobiles Dynamics 365 ne permettent pas l'utilisation de fonctions JavaScript qui bloquent le flux du code comme window.alert et window.confirm. Utilisez ces méthodes à la place de ces méthodes si vous devez afficher un message à l'utilisateur. La différence principale réside dans le fait que ces méthodes ne bloquent pas le code jusqu'à ce qu'un utilisateur les ferme. Elles contiennent un paramètre de fonction de rappel pour indiquer quel code doit être exécuté selon les réponses des utilisateurs.
Notes
Dans les clients mobiles Dynamics 365 (téléphones et tablettes), l'utilisation de la méthode window.alert est remplacée pour utiliser Xrm.Utility.alertDialog sans rappel. Ceci affiche le message mais ne bloque pas l'exécution de code comme le fait window.alert. Ce mappage d'window.alert à Xrm.Utility.alertDialog dans les clients mobiles Dynamics 365 est obsolète et est supprimé dans la prochaine version majeure. Vous devez migrer les codes que dont vous disposez à présent pour utiliser Xrm.Utility.alertDialog plutôt que window.alert.
alertDialog
Affiche la boîte de dialogue contenant un message défini par l'application.
Xrm.Utility.alertDialog(message,onCloseCallback)
Paramètres
Nom
Type
Obligatoire
Description
message
Chaîne
Oui
Texte du message à afficher dans la boîte de dialogue.
onCloseCallback
Fonction
Non
Fonction à exécuter lorsque le bouton OK est actionné.
Remarques
Cette méthode est uniquement disponible pour Entités mises à jour.
confirmDialog
Affiche la boîte de dialogue de confirmation qui contient un message facultatif, ainsi que les boutons OK et Annuler.
Xrm.Utility.confirmDialog(message,yesCloseCallback,noCloseCallback)
Paramètres
Nom
Type
Obligatoire
Description
message
Chaîne
Oui
Texte du message à afficher dans la boîte de dialogue
yesCloseCallback
Fonction
Non
Fonction à exécuter lorsque le bouton OK est actionné.
noCloseCallback
Fonction
Non
Fonction à exécuter lorsque le bouton Annuler est actionné.
Remarques
Cette méthode est uniquement disponible pour Entités mises à jour.
Fonctionnalités natives des appareils (clients mobiles Dynamics 365)
Utilisez ces méthodes pour les clients Dynamics 365 pour téléphones et Dynamics 365 pour tablettes pour aider à enrichir l'expérience d'utilisateur des utilisateurs d'entreprise mobiles dans les domaines de la vente, du service après-vente, etc.
Notes
Ces méthodes ont été présentées dans Mise à jour de décembre 2016 pour Dynamics 365 (en ligne et local).
getBarcodeValue
Renvoie les informations de code-barres, telles qu'un numéro de produit, numérisées à l'aide de la caméra de l'appareil.
Xrm.Utility.getBarcodeValue().then(successCallback, errorCallback)
Paramètres
Nom
Type
Nécessaire
Description
successCallback
Fonction
Oui
Fonction à appeler lorsque la valeur du code-barres est renvoyée.
errorCallback
Fonction
Oui
Fonction à appeler lorsque l'opération échoue. Un objet d'erreur avec la propriété message est passé et décrit les détails de l'erreur.
Remarques
Pour que la méthode getBarcodeValue puisse fonctionner, les clients mobiles Dynamics 365 doivent avoir accès à la caméra de l'appareil, qui est activée par défaut.Exemple
L'exemple de code suivant illustre l'utilisation de cette méthode.Xrm.Utility.getBarcodeValue().then( function (result) { Xrm.Utility.alertDialog("Barcode value: " + result); }, function (error) { Xrm.Utility.alertDialog(error.message); })
getCurrentPosition
Renvoie la position actuelle à l'aide de la fonctionnalité de géolocalisation de l'appareil.
Xrm.Utility.getCurrentPosition().then(successCallback, errorCallback)
Paramètres
Nom
Type
Nécessaire
Description
successCallback
Fonction
Oui
Fonction à appeler lorsque les informations de géolocalisation actuelles sont renvoyées. Un objet de géolocalisation avec les attributs suivants est passé à la fonction.
coords : contient un ensemble de coordonnées géographiques avec la précision associée, ainsi qu'un ensemble d'autres attributs facultatifs tels que l'altitude et la vitesse.
timestamp : représente la date d'acquisition de l'objet qui est représentée en tant que DOMTimeStamp.
errorCallback
Fonction
Oui
Fonction à appeler lorsque l'opération échoue. Un objet avec les propriétés suivantes est transmis :
code : nombre. Code d’erreur.
message : chaîne. Message localisé décrivant les détails de l'erreur.
Si le paramètre d'emplacement de l'utilisateur n'est pas activé sur votre appareil mobile, le message d'erreur indique la même information. Si vous utilisez une version antérieure du client mobile Dynamics 365 ou si la fonctionnalité de géolocalisation n'est pas disponible sur votre appareil mobile, null est passé au rappel d'erreur.
Remarques
Pour que la méthode getCurrentPosition puisse fonctionner, la fonctionnalité de géolocalisation doit être activée sur votre appareil, et les clients mobiles Dynamics 365 doivent disposer d'autorisations pour accéder à l'emplacement de l'appareil, qui n'est pas activé par défaut.Exemple
L'exemple de code suivant illustre l'utilisation de cette méthode.Xrm.Utility.getCurrentPosition().then (function (location) { Xrm.Utility.alertDialog("Latitude: " + location.coords.latitude + ", Longitude: " + location.coords.longitude); }, function (error) { Xrm.Utility.alertDialog(error.message); })
isActivityType
Déterminez si une entité est une entité d'activité.
Xrm.Utility.isActivityType(entityName)
Paramètre
Nom
Type
Obligatoire
Description
entityName
Chaîne
Oui
Nom logique d'une entité.
Valeur renvoyée
Type
Description
Booléen
Vrai si l'entité est une entité d'activité, sinon faux.
openEntityForm
Ouvre un formulaire d'entité pour un nouvel enregistrement d'entité ou existant à l'aide des options définies en tant que paramètres.
Xrm.Utility.openEntityForm(name,id,parameters,windowOptions)
Paramètres
Nom
Type
Obligatoire
Description
nom
Chaîne
Oui
Nom logique de l’entité.
id
Chaîne
Non
La representation de la chaîne d'un identificateur unique ou de l'enregistrement à ouvrir dans le formulaire. Si elle n'est pas définie, un formulaire visant à créer un enregistrement est ouvert.
parameters
Objet
Non
Objet de dictionnaire qui transmet des paramètres supplémentaires au formulaire. Des paramètres non valides provoquent une erreur.
Les paramètres de chaîne de requête supplémentaires valides sont :
ID de formulaire : Pour définir la valeur d'ID du formulaire principal à utiliser lorsque plusieurs formulaires sont disponibles. Le paramètre est formid.
ID de champ par défaut : Pour définir les valeurs par défaut d'un nouveau formulaire de enregistrement. Pour plus d'informations, voir Définir les valeurs de champ utilisant les paramètres transmis à un formulaire.
Les paramètres navbar et cmdbar décrits dans Paramètres de chaîne de requête pour la page Main.aspx.
Paramètres de chaîne de requête personnalisés : Un formulaire peut être configuré afin d'accepter les paramètres de chaîne de requête personnalisés. Pour plus d'informations, voir Configurer un formulaire pour accepter les paramètres de chaîne de requête personnalisés.
windowOptions
Objet
Non
Pour Mise à jour 1 de Microsoft Dynamics CRM Online 2015 ou version ultérieure, utilisez ce paramètre optionnel dans l'application Web pour contrôler le mode d'ouverture du formulaire. Vous pouvez ouvrir un formulaire dans une nouvelle fenêtre en passant un objet de dictionnaire avec une propriété openInNewWindow booléenne définie sur true.
Ce paramètre est ignoré dans les clients mobiles Dynamics 365 (téléphones et tablettes).
Remarques
L'utilisation de cette fonction permet de s'assurer que les utilisateurs ne sont pas invités à ouvrir une nouvelle session dans certains cas.Exemples
Ouvrir un nouvel enregistrement de compte à l'aide du formulaire par défautXrm.Utility.openEntityForm("account");
Ouvrir un enregistrement de compte existant à l'aide du formulaire par défaut
Xrm.Utility.openEntityForm("account","A85C0252-DF8B-E111-997C-00155D8A8410");
Ouvrir un nouvel enregistrement de compte avec un formulaire spécifique et définir des valeurs par défaut
var parameters = {}; parameters["formid"] = "b053a39a-041a-4356-acef-ddf00182762b"; parameters["name"] = "Test"; parameters["telephone1"] = "(425) 555-1234"; Xrm.Utility.openEntityForm("account", null, parameters);
Ouvrir un nouvel enregistrement de compte à l'aide du formulaire par défaut dans une nouvelle fenêtre
var windowOptions = { openInNewWindow: true }; Xrm.Utility.openEntityForm("account",null,null,windowOptions);
openQuickCreate
Pour Mise à jour 1 de Microsoft Dynamics CRM Online 2015 ou version ultérieure, utilisez cette fonction pour ouvrir un nouveau formulaire de création rapide. Vous pouvez utiliser cette fonction pour définir les valeurs par défaut à l'aide des mappages d'attributs ou d'attributs spécifiques. Si l'utilisateur enregistre l'enregistrement, vous pourrez recueillir une référence à l'enregistrement créé.
Xrm.Utility.openQuickCreate(entityLogicalName,createFromEntity,parameters).then(successCallback, errorCallback);
Paramètres
Nom
Type
Obligatoire
Description
entityLogicalName
Chaîne
Oui
Nom logique de l'entité à créer.
createFromEntity
Recherche
Non
Désigne un enregistrement qui fournira des valeurs par défaut en fonction des valeurs d'attribut mappées.
Un objet de recherche contient les propriétés String suivantes :
entityType : Nom logique de l'entité.
id : Représentation sous forme de chaîne d'une valeur GUID de l'enregistrement.
name : Valeur d'attribut principal de l'enregistrement.
parameters
Objet
Non
Objet de dictionnaire qui transmet des paramètres de chaîne de requête supplémentaires au formulaire. Des paramètres de chaîne de requête non valides provoquent une erreur.
Les paramètres de chaîne de requête supplémentaires valides sont :
ID de champ par défaut : Pour définir les valeurs par défaut d'un nouveau formulaire de enregistrement. Pour plus d'informations, voir Définir les valeurs de champ utilisant les paramètres transmis à un formulaire.
Paramètres de chaîne de requête personnalisés : Un formulaire peut être configuré afin d'accepter les paramètres de chaîne de requête personnalisés. Pour plus d'informations, voir Configurer un formulaire pour accepter les paramètres de chaîne de requête personnalisés.
successCallback
Fonction
Non
Fonction qui sera appelée lorsqu'un enregistrement est enregistré. Un objet est transmis à cette fonction en tant que paramètre. Cet objet a une propriété savedEntityReference avec les propriétés suivantes pour identifier l'enregistrement créé :
entityType : Nom logique de l'entité.
id : Représentation sous forme de chaîne d'une valeur GUID de l'enregistrement.
name : Valeur d'attribut principal de l'enregistrement créé.
errorCallback
Fonction
Non
Fonction à appeler lorsque l'opération échoue.
Un objet avec les propriétés suivantes est transmis :
errorCode : Number. Code d’erreur.
message : String. Message d'erreur localisé.
Remarques
Cette fonction est uniquement disponible pour Mise à jour 1 de Microsoft Dynamics CRM Online 2015 ou version ultérieure.Il existe une limite de 10 formulaires de création rapide imbriqués dans l'application Web. Si cette limite est dépassée, cette fonction ouvrira le formulaire d'entité complet au lieu du formulaire de création rapide.
Exemple
Lorsque ce code est exécuté dans un formulaire d'entité de compte, un formulaire de création rapide pour créer un nouveau compte enfant avec un nom par défaut est défini pour inclure le nom du compte parent.var thisAccount = { entityType: "account", id: Xrm.Page.data.entity.getId() }; var callback = function (obj) { console.log("Created new " + obj.savedEntityReference.entityType + " named '" + obj.savedEntityReference.name + "' with id:" + obj.savedEntityReference.id); } var setName = { name: "Child account of " + Xrm.Page.getAttribute("name").getValue() }; Xrm.Utility.openQuickCreate("account", thisAccount, setName).then(callback, function (error) { console.log(error.message); });
Si ce code est exécuté avec les outils de développement du navigateur (outils F12), la suite décrira la sortie sur la console lors de l'exécution dans le contexte d'un compte nommé « A. Datum Corporation (sample) » et l'utilisateur ne modifiera pas le nom par défaut défini pour le nouveau compte enfant.
Created new account named 'Child account of A. Datum Corporation (sample)' with id:{1D4BFF87-E8C5-E411-80CF-00155DB58496}
openWebResource
Ouvre une ressource web HTML.
Notes
Cette fonction n'est pas prise en charge pour les clients mobiles Dynamics 365 (téléphones et tablettes) et le centre de services interactifs.
Xrm.Utility.openWebResource(webResourceName,webResourceData,width, height)
Paramètres
Nom
Type
Nécessaire
Description
webResourceName
Chaîne
Oui
Nom de la ressource Web HTML à ouvrir.
webResourceData
Chaîne
Non
Données à transmettre dans le paramètre de données.
width
Numéro
Non
Largeur de la fenêtre à ouvrir en pixels.
height
Numéro
Non
Hauteur de la fenêtre à ouvrir en pixels.
Valeur renvoyée
Objet de fenêtre.Remarques
Une ressource Web HTML peut accepter les valeurs de paramètres décrites dans Transmettre les paramètres aux ressources Web HTML. Cette fonction assure uniquement le transfert du paramètre de données facultatif. Pour transmettre les valeurs des autres paramètres non valides, vous devez les ajouter au paramètre webResourceName.Exemples
Ouvrir une ressource Web HTML nommée « new_webResource.htm »Xrm.Utility.openWebResource("new_webResource.htm");
Ouvrir une ressource Web HTML, notamment un élément unique des données du paramètre de données
Xrm.Utility.openWebResource("new_webResource.htm","dataItemValue");
Ouvrir une ressource Web HTML en transmettant plusieurs valeurs via le paramètre de données
var customParameters = encodeURIComponent("first=First Value&second=Second Value&third=Third Value"); Xrm.Utility.openWebResource("new_webResource.htm",customParameters);
Notes
Ces valeurs doivent être extraites de la valeur du paramètre de données dans la ressource Web HTML. Pour plus d'informations, consultez la rubrique Exemple : Transmettre plusieurs valeurs à une ressource Web via le paramètre de données.
Ouvrir une ressource Web HTML avec les paramètres prévus par les ressources Web HTML
Xrm.Utility.openWebResource("new_webResource.htm?typename=account&userlcid=1033");
Pour plus d'informations, voir Transmettre les paramètres aux ressources Web HTML.
Ouvrir une ressource Web HTML, en définissant la hauteur et la largeur
Xrm.Utility.openWebResource("new_webResource.htm", null, 300,300);
Voir aussi
Référence par programmation côté client
Ouvre les formulaires, vues, boîtes de dialogue et rapports avec une URL
Définir les valeurs de champ utilisant les paramètres transmis à un formulaire
Configurer un formulaire pour accepter les paramètres de chaîne de requête personnalisés
Référence rapide des scripts de formulaires
Écrire du code pour les formulaires Microsoft Dynamics 365
Utiliser le modèle d’objet Xrm.Page
Microsoft Dynamics 365
© 2017 Microsoft. Tous droits réservés. Copyright