Partager via


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 :

    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éfaut

    Xrm.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 :

    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