spUtil : client

  • Rversion finale: Zurich
  • Mis à jour 31 juil. 2025
  • 7 minutes de lecture

    • L’API spUtil fournit des méthodes utilitaires permettant d’exécuter des fonctions courantes dans un Portail de services script client de widget.

    Ces fonctions comprennent :

    Pour plus d’informations sur les widgets, voir Widgets du portail de services.

    spUtil : addErrorMessage(Message de chaîne)

    Affiche un message d’erreur de notification.

    Tableau 1. Paramètres
    Nom Type Description
    message Chaîne Message d’erreur à afficher.
    Tableau 2. Renvoie
    Type Description
    nul 
    spUtil.addErrorMessage("There has been an error processing your request")

    spUtil : addInfoMessage(message de chaîne)

    Affiche un message d’informations de notification.

    Tableau 3. Paramètres
    Nom Type Description
    message Chaîne Message à afficher.
    Tableau 4. Renvoie
    Type Description
    nul 
    spUtil.addInfoMessage("Your order has been placed")

    spUtil : addTrivialMessage(message de chaîne)

    Affiche un message de notification trivial.

    Les messages triviaux disparaissent après un court laps de temps.

    Tableau 5. Paramètres
    Nom Type Description
    message Chaîne Message à afficher.
    Tableau 6. Renvoie
    Type Description
    nul 
    spUtil.addTrivialMessage("Thanks for your order")

    spUtil : createUid()

    Créez un identificateur unique.

    Tableau 7. Paramètres
    Nom Type Description
    Aucun
    Tableau 8. Renvoie
    Type Description
    Chaîne ID unique de 32 caractères.

    spUtil : get(String widgetId Données de l’objet)

    Incorpore un modèle de widget dans un script client de widget.

    La fonction de rappel renvoie le modèle de widget complet. Pour plus d’informations sur les widgets, voir Widgets du portail de services.

    Tableau 9. Paramètres
    Nom Type Description
    ID de widget Chaîne ID du widget ou sys_id du widget à intégrer.
    données Objet Facultatif. Paires nom/valeur de paramètres à transmettre au modèle de widget.
    Tableau 10. Renvoie
    Type Description
    Objet Modèle du widget intégré.

    Sans données transmises.

    spUtil.get("widget-cool-clock").then(function(response) {
  c.coolClock = response;
});

    Avec des données transmises.

    spUtil.get('pps-list-modal', {title: c.data.editAllocations, 
  table: 'resource_allocation', 
  queryString: 'GROUPBYuser^resource_plan=' + c.data.sysId, 
  view: 'resource_portal_allocations' }).then(function(response) {
    var formModal = response;
    c.allocationListModal = response;
  });

    spUtil : getHeaders()

    Récupère tous les en-têtes à utiliser pour les appels d’API.

    Tableau 11. Paramètres
    Nom Type Description
    Aucun
    Tableau 12. Renvoie
    Type Description
    Objet Tous les en-têtes à utiliser pour les appels d’API.

    spUtil : getHost()

    Renvoie le domaine hôte complet.

    Tableau 13. Paramètres
    Nom Type Description
    Aucun
    Tableau 14. Renvoie
    Type Description
    Chaîne Le domaine de l’hôte complet, par exemple, hi.servicenow.com

    spUtil : getPreference(Préférence de chaîne, rappel de fonction)

    Exécute le rappel avec la réponse de préférence utilisateur en transmettant le nom de la préférence.

    Tableau 15. Paramètres
    Nom Type Description
    préférence Chaîne Nom de la préférence.
    rappel Fonction Définissez la fonction de rappel.
    Tableau 16. Renvoie
    Type Description
    nul

    spUtil : getURL()

    Renvoie les informations actuelles de l’URL du portail de services.

    Tableau 17. Paramètres
    Nom Type Description
    Aucun
    Tableau 18. Renvoie
    Type Description
    Chaîne URL actuelle du portail de services.

    spUtil : format(modèle de chaîne, données de l’objet)

    Met en forme une chaîne qui contient des variables.

    Utilisez cette méthode comme alternative à la concaténation par chaîne.

    Tableau 19. Paramètres
    Nom Type Description
    modèle Chaîne Modèle de chaîne contenant des valeurs pour la substitution de variables.
    données Objet Objet contenant les valeurs des variables définies dans la chaîne de modèle.
    Tableau 20. Renvoie
    Type Description
    Chaîne Chaîne contenant les valeurs des variables au lieu de la nomenclature des variables. 
    spUtil.format('An error ocurred: {error} when loading {widget}', {error: '404', widget: 'sp-widget'})

    Sortie :

    'An error occurred: 404 when loading sp-widget'

    spUtil - isMobile()

    Vérifie si le client actuel est un appareil mobile.

    Tableau 21. Paramètres
    Nom Type Description
    Aucun
    Tableau 22. Renvoie
    Type Description
    Booléen Marqueur indiquant si le client actuel est un appareil mobile.
    Valeurs valides :
    • vrai : le client actuel est un appareil mobile.
    • faux : le client actuel n’est pas un appareil mobile.

    spUtil : parseAttributes(attributs de chaîne)

    Analyse les attributs séparés par des virgules dans une chaîne spécifiée.

    Tableau 23. Paramètres
    Nom Type Description
    attributs Chaîne Chaîne contenant des attributs séparés par des virgules, tels que le champ Attributs d’un enregistrement de dictionnaire.
    Tableau 24. Renvoie
    Type Description
    Tableau Tableau d’objets contenant les attributs analysés. 
    function getRefQualElements() {
  var refQualElements = [];
  if (field && field.attributes && field.attributes.indexOf('ref_qual_elements') > -1) {
    var attributes = spUtil.parseAttributes(field.attributes);
    refQualElements = attributes['ref_qual_elements'].split(';');
  }
  return refQualElements;
}

    spUtil : recordWatch(Object $scope, String table, String filter, Function callback)

    Surveille les mises à jour d’une table ou d’un filtre et renvoie la valeur à partir de la fonction de rappel.

    Permet à un développeur de widgets de répondre aux mises à jour de table en temps réel. Par exemple, en utilisant recordWatch(), le widget Liste simple peut écouter les changements apportés à sa table de données. Si des enregistrements sont ajoutés, supprimés ou mis à jour, le widget se met à jour automatiquement.

    Remarque :
    Lors du passage de l’argument $scope dans la fonction recordWatch(), injectez $scope dans les paramètres de votre fonction de script client.
    Tableau 25. Paramètres
    Nom Type Description
    $scope Objet Périmètre de l’objet de données mis à jour par la fonction de rappel.
    Table Chaîne Table surveillée.
    filtre Chaîne Filtrez les champs à surveiller.
    rappel Fonction Facultatif. Paramètre pour définir la fonction de rappel.
    Tableau 26. Renvoie
    Type Description
    Promesse Valeur de retour de la fonction de rappel. 
    //A simple recordWatch function.
spUtil.recordWatch($scope, "live_profile", "sys_id=" + liveProfileId);

//In a widget client script
function(spUtil, $scope) {
  /* widget controller */
  var c =this;

  // Registers a listener on the incident table with the filter active=true, 
  // meaning that whenever something changes on that table with that filter, 
  // the callback function is executed.    
  // The callback function takes a single parameter 'response', which contains 
  // the property 'data'. The 'data' property contains information about the changed record. 
  spUtil.recordWatch($scope, "incident", "active=true", function(response) {
        
    // Returns the data inserted or updated on the table 
    console.log(response.data);   
    
    });
}

    spUtil : refresh(Objet $scope)

    Appelle le serveur et remplace les options et données actuelles par la réponse du serveur.

    L’appel de spUtil.refresh() est similaire à l’appel de server.refresh(). Toutefois, lorsque vous appelez spUtil.refresh(), vous pouvez définir l’objet $scope.

    Tableau 27. Paramètres
    Nom Type Description
    $scope Objet Périmètre défini pour la mise à jour.
    Tableau 28. Renvoie
    Type Description
    Objet Options et objets de données mis à jour.

    spUtil : scrollTo(sélecteur de chaîne, heure numérique)

    Fait défiler jusqu’à l’élément avec le sélecteur spécifié, sur une période de temps spécifiée.

    Tableau 29. Paramètres
    Nom Type Description
    sélecteur Chaîne Sélecteur auquel accéder.
    heure Numéro Temps nécessaire pour faire défiler jusqu’au sélecteur spécifié.

    Unité : millisecondes
    Tableau 30. Renvoie
    Type Description
    nul

    spUtil : setBreadCrumb(Objet $scope, Fils d’Ariane de tableau)

    Met à jour le fil d’Ariane de l’en-tête.

    Tableau 31. Paramètres
    Nom Type Description
    $scope Objet Périmètre défini pour la table.
    Fils d'Ariane Tableau Conditions utilisées pour créer le filtre de fil d’Ariane.
    Tableau 32. Renvoie
    Type Description
    nul

    spUtil - setPreference(String pref, String value)

    Définit une préférence utilisateur.

    Tableau 33. Paramètres
    Nom Type Description
    Pref Chaîne Nom de la préférence
    valide Chaîne Valeur de préférence
    Tableau 34. Renvoie
    Type Description
    nul

    spUtil : setSearchPage(String searchPage)

    Met à jour la page de recherche.

    Tableau 35. Paramètres
    Nom Type Description
    Page de recherche Chaîne Nom de la page de recherche.
    Tableau 36. Renvoie
    Type Description
    nul

    spUtil - update(Objet $scope)

    Met à jour l’objet de données sur le serveur dans un périmètre donné.

    Cette méthode est similaire à server.update(), mais inclut un paramètre $scope qui définit le champ d’application à transmettre.

    Tableau 37. Paramètres
    Nom Type Description
    $scope Objet Périmètre défini pour la mise à jour.
    Tableau 38. Renvoie
    Type Description
    Objet Objet de données mis à jour.

    L’exemple suivant inclut un widget P1 qui surveille les modifications apportées au champ d’état et utilise un filtre pour surveiller tous les P1 actifs et laisser la fonction de rappel déterminer s’il faut actualiser les données. La data.changes propriété contient un tableau de champs mis à jour. Si l’état d’un champ a changé, les données sont mises à jour dans le widget.

    var q = "priority=1^active=true^EQ";
spUtil.recordWatch($scope, "incident", q, function(event, data) {
   if (data.changes.includes("state")) { // only update if state was updated.
      spUtil.update($scope);
   }
});