Cette page a été traduite par l'API Cloud Translation.

Service HTML: communication avec les fonctions du serveur

google.script.run est une API JavaScript côté client asynchrone qui permet aux pages de service HTML d'appeler des fonctions Apps Script côté serveur. L'exemple suivant présente les fonctionnalités de base sur google.script.run — d'appeler une fonction sur le serveur à partir de JavaScript côté client.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function doSomething() {
  Logger.log('I was called!');
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      google.script.run.doSomething();
    </script>
  </head>
</html>

Si vous déployez ce script en tant qu'application Web et que vous accédez à son URL, vous ne verrez pas mais si vous consultez les journaux, vous verrez que la fonction serveur doSomething() a été appelé.

Les appels côté client vers des fonctions côté serveur sont asynchrones: après le navigateur demande au serveur d'exécuter la fonction doSomething(), le navigateur continue immédiatement à la ligne de code suivante sans attendre de réponse. Cela signifie que les appels de fonction du serveur peuvent ne pas s'exécuter dans l'ordre prévu. Si vous effectuez deux appels de fonction en même temps, il n'est pas possible de savoir quelle fonction s'exécutera en premier. Le résultat peut varier à chaque fois que vous chargez la page. Dans cette situation, les gestionnaires de succès et les gestionnaires d'échec permettent de contrôler le flux de votre code.

L'API google.script.run autorise 10 appels simultanés aux fonctions du serveur. Si vous effectuez un 11e appel alors que 10 sont toujours en cours d'exécution, la fonction du serveur sera retardée jusqu'à ce que l'une des 10 places soit libérée. En pratique, il faut rarement de penser à cette restriction, d'autant plus que la plupart des navigateurs limitent déjà le nombre de requêtes simultanées adressées au même serveur à un nombre inférieur à 10. Dans Firefox, par exemple, la limite est de 6. La plupart des navigateurs retardent autant des requêtes de serveur jusqu'à ce que l'une des requêtes existantes soit terminée.

Paramètres et valeurs renvoyées

Vous pouvez appeler une fonction serveur avec des paramètres du client. De même, un peut renvoyer une valeur au client sous la forme d'un paramètre transmis à gestionnaire de réussite.

Les paramètres juridiques et les valeurs de retour sont des primitives JavaScript, comme un Number, Boolean, String ou null, ainsi qu'aux objets et aux tableaux JavaScript qui sont composées de primitives, d'objets et de tableaux. Un élément form sur la page est également légal en tant que paramètre, mais il doit s'agir du seul paramètre de la fonction, et cette valeur renvoyée n'est pas autorisée. Les requêtes échouent si vous tentez de transmettre un Date, Function, élément DOM en dehors de form, ou tout autre type interdit y compris des types interdits dans des objets ou des tableaux. Les objets qui créent les références circulaires échouent également, et les champs non définis dans les tableaux deviennent null

Notez qu'un objet transmis au serveur devient une copie de l'original. Si un reçoit un objet et modifie ses propriétés, les propriétés le client ne sont pas affectés.

Gestionnaires de réussite

Parce que le code côté client passe à la ligne suivante sans attendre qu'un serveur pour terminer, withSuccessHandler(function) vous permet de spécifier une fonction de rappel côté client à exécuter lorsque le serveur répond. Si la fonction serveur renvoie une valeur, l'API la transmet à la nouvelle fonction en tant que paramètre.

L'exemple suivant affiche une alerte de navigateur lorsque le serveur répond. Remarque que cet exemple de code nécessite une autorisation, car la fonction côté serveur est qui accèdent à votre compte Gmail. Le moyen le plus simple d'autoriser le script est d'exécuter la fonction getUnreadEmails() manuellement depuis l'éditeur de script une fois avant pour charger la page. Sinon, lorsque vous déployer l'application Web, vous pouvez choisir l'exécuter en tant qu'"utilisateur accédant à l'application Web", auquel cas vous devrez une demande d'autorisation lorsque vous chargez l'application.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getUnreadEmails() {
  return GmailApp.getInboxUnreadCount();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onSuccess(numUnread) {
        var div = document.getElementById('output');
        div.innerHTML = 'You have ' + numUnread
            + ' unread messages in your Gmail inbox.';
      }

      google.script.run.withSuccessHandler(onSuccess)
          .getUnreadEmails();
    </script>
  </head>
  <body>
    <div id="output"></div>
  </body>
</html>

Gestionnaires d'échecs

Si le serveur ne répond pas ou génère une erreur, withFailureHandler(function) vous permet de spécifier un gestionnaire d'échecs au lieu d'un gestionnaire de réussite, avec Error (le cas échéant) transmis en tant qu'argument.

Par défaut, si vous ne spécifiez pas de gestionnaire d'échecs, les échecs sont consignés dans le Console JavaScript. Pour ignorer ce paramètre, appelez withFailureHandler(null) ou fournissez un gestionnaire d'échecs qui n'a aucun effet.

La syntaxe des gestionnaires d'échec est presque identique à celle des gestionnaires de réussite, car cette de l'exemple.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getUnreadEmails() {
  // 'got' instead of 'get' will throw an error.
  return GmailApp.gotInboxUnreadCount();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onFailure(error) {
        var div = document.getElementById('output');
        div.innerHTML = "ERROR: " + error.message;
      }

      google.script.run.withFailureHandler(onFailure)
          .getUnreadEmails();
    </script>
  </head>
  <body>
    <div id="output"></div>
  </body>
</html>

Objets User

Vous pouvez réutiliser le même gestionnaire de réussite ou d'échec pour plusieurs appels à la méthode en appelant withUserObject(object) pour spécifier un objet qui sera transmis au gestionnaire en tant que deuxième paramètre. Cet "objet utilisateur" (à ne pas confondre avec La classe User, qui vous permet de répondre contexte dans lequel le client a contacté le serveur. Comme les objets utilisateur ne sont pas envoyées au serveur, il peut s'agir de presque n'importe quel élément, y compris des fonctions, des éléments DOM d'entrée, etc., sans les restrictions sur les paramètres et les valeurs de retour pour les appels de serveur. Toutefois, les objets Utilisateur ne peuvent pas être des objets construits avec new.

Dans cet exemple, cliquer sur l'un des deux boutons met à jour ce bouton avec une icône à partir du serveur tout en laissant l'autre bouton inchangé, même s'il partager un gestionnaire de réussite. Dans le gestionnaire onclick, le mot clé this fait référence au button lui-même.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getEmail() {
  return Session.getActiveUser().getEmail();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function updateButton(email, button) {
        button.value = 'Clicked by ' + email;
      }
    </script>
  </head>
  <body>
    <input type="button" value="Not Clicked"
      onclick="google.script.run
          .withSuccessHandler(updateButton)
          .withUserObject(this)
          .getEmail()" />
    <input type="button" value="Not Clicked"
      onclick="google.script.run
          .withSuccessHandler(updateButton)
          .withUserObject(this)
          .getEmail()" />
  </body>
</html>

Formulaires

Si vous appelez une fonction de serveur avec un élément form en tant que paramètre, le formulaire devient un seul objet avec des noms de champ comme clés et des valeurs de champ comme valeurs. La les valeurs sont toutes converties en chaînes, à l'exception du contenu de file-input des champs, qui deviennent des objets Blob.

Cet exemple traite un formulaire, y compris un champ de saisie de fichier, sans recharger la la page ; il importe le fichier dans Google Drive, puis imprime l'URL sur la page côté client. Dans le gestionnaire onsubmit, le mot clé this fait référence au formulaire lui-même. Notez que lors du chargement de tous les formulaires de la page, l'action d'envoi par défaut est désactivée par preventFormSubmit. Cela permet d'éviter que ne redirige pas les internautes vers une URL inexacte en cas d'exception.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function processForm(formObject) {
  var formBlob = formObject.myFile;
  var driveFile = DriveApp.createFile(formBlob);
  return driveFile.getUrl();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      // Prevent forms from submitting.
      function preventFormSubmit() {
        var forms = document.querySelectorAll('form');
        for (var i = 0; i < forms.length; i++) {
          forms[i].addEventListener('submit', function(event) {
            event.preventDefault();
          });
        }
      }
      window.addEventListener('load', preventFormSubmit);

      function handleFormSubmit(formObject) {
        google.script.run.withSuccessHandler(updateUrl).processForm(formObject);
      }
      function updateUrl(url) {
        var div = document.getElementById('output');
        div.innerHTML = '<a href="' + url + '">Got it!</a>';
      }
    </script>
  </head>
  <body>
    <form id="myForm" onsubmit="handleFormSubmit(this)">
      <input name="myFile" type="file" />
      <input type="submit" value="Submit" />
    </form>
    <div id="output"></div>
 </body>
</html>

Exécuteurs de script

Vous pouvez considérer google.script.run comme un compilateur pour un "exécuteur de script". Si vous ajouter un gestionnaire de réussite, un gestionnaire d'échec ou un objet utilisateur à un exécuteur de script, vous ne modifient pas l'exécuteur existant ; Au lieu de cela, vous obtenez un nouvel exécuteur de script avec un nouveau comportement.

Vous pouvez utiliser n'importe quelle combinaison et n'importe quel ordre de withSuccessHandler(), withFailureHandler() et withUserObject(). Vous pouvez également appeler l'un des modifier des fonctions sur un exécuteur de script pour lequel une valeur est déjà définie. Les nouvelles remplace simplement la valeur précédente.

Cet exemple définit un gestionnaire d'échecs commun pour les trois appels de serveur, mais deux gestionnaires de réussite distincts:

var myRunner = google.script.run.withFailureHandler(onFailure);
var myRunner1 = myRunner.withSuccessHandler(onSuccess);
var myRunner2 = myRunner.withSuccessHandler(onDifferentSuccess);

myRunner1.doSomething();
myRunner1.doSomethingElse();
myRunner2.doSomething();

Fonctions privées

Les fonctions serveur dont le nom se termine par un trait de soulignement sont considérées comme privées. Ces fonctions ne peuvent pas être appelées par google.script et leur nom n'est jamais envoyé au client. Vous pouvez ainsi les utiliser pour masquer les détails d'implémentation qui doivent rester secrets sur le serveur. google.script ne peut pas non plus voir des fonctions dans des bibliothèques et des fonctions qui ne sont pas déclaré au niveau supérieur du script.

Dans cet exemple, la fonction getBankBalance() est disponible dans le client du code ; un utilisateur qui inspecte votre code source peut découvrir son nom même si vous ne l'appelez pas. Cependant, les fonctions deepSecret_() et obj.objectMethod() sont complètement invisibles pour le client.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getBankBalance() {
  var email = Session.getActiveUser().getEmail()
  return deepSecret_(email);
}

function deepSecret_(email) {
 // Do some secret calculations
 return email + ' has $1,000,000 in the bank.';
}

var obj = {
  objectMethod: function() {
    // More secret calculations
  }
};

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onSuccess(balance) {
        var div = document.getElementById('output');
        div.innerHTML = balance;
      }

      google.script.run.withSuccessHandler(onSuccess)
          .getBankBalance();
    </script>
  </head>
  <body>
    <div id="output">No result yet...</div>
  </body>
</html>

Redimensionnement des boîtes de dialogue dans Google Workspace applications

Boîtes de dialogue personnalisées dans Google Docs, Sheets ou Les formulaires peuvent être redimensionnés en appelant la méthode Méthodes google.script.host setWidth(width) ou setHeight(height) po code côté client. (Pour définir la taille initiale d'une boîte de dialogue, utilisez HtmlOutput méthodes setWidth(width) et setHeight(height)). Notez que les boîtes de dialogue ne sont pas recentrées dans la fenêtre parent lorsqu'elles sont redimensionnées et qu'elles impossible de redimensionner les barres latérales.

Fermeture des boîtes de dialogue et des barres latérales dans Google Workspace

Si vous utilisez le service HTML pour afficher une boîte de dialogue ou une barre latérale dans Google Docs, Sheets ou Forms, vous ne pouvez pas fermer l'interface en appelant window.close(). Au lieu de cela, vous doit appeler google.script.host.close() Pour voir un exemple, consultez la section diffuser du code HTML en tant qu' Google Workspace interface utilisateur.

Déplacement du curseur du navigateur vers Google Workspace...

Pour déplacer le curseur dans le navigateur de l'utilisateur depuis une boîte de dialogue ou une barre latérale vers dans un éditeur Google Docs, Sheets ou Forms, il vous suffit d'appeler la méthode google.script.host.editor.focus() Cette méthode est particulièrement utile en combinaison avec les méthodes Document service Document.setCursor(position) et Document.setSelection(range).