Classe google.script.run (API côté client)

google.script.run est une API JavaScript côté client asynchrone disponible dans les pages de services HTML qui peut appeler des fonctions Apps Script côté serveur. Pour interagir avec les boîtes de dialogue ou les barres latérales dans Google Docs, Sheets ou Forms à partir du code côté client, utilisez google.script.host. Pour plus d'informations, consultez le guide de communication avec les fonctions de serveur dans le service HTML.

Méthodes

MéthodeType renvoyéBrève description
myFunction(...) (toute fonction côté serveur) void Exécute la fonction Apps Script côté serveur avec le nom correspondant.
withFailureHandler(function) google.script.run Définit une fonction de rappel à exécuter si la fonction côté serveur génère une exception.
withSuccessHandler(function) google.script.run Définit une fonction de rappel à exécuter si la fonction côté serveur aboutit.
withUserObject(object) google.script.run Définit un objet à transmettre en tant que deuxième paramètre aux gestionnaires de réussite et d'échec.

Documentation détaillée

myFunction(...) (toute fonction côté serveur)

Exécute la fonction Apps Script côté serveur avec le nom correspondant.

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>
  <body>
  </body>
</html>

Paramètres

NomTypeDescription
...La plupart des types sont légaux, mais pas les éléments Date, Function ou DOM en plus de form (voir la description).Les paramètres légaux sont des primitives JavaScript, telles que Number, Boolean, String ou null, ainsi que des objets et des tableaux JavaScript composés 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. Les requêtes échouent si vous tentez de transmettre un élément Date, Function ou DOM en plus d'un form, ou tout autre type interdit, y compris des types interdits dans des objets ou des tableaux. Les objets qui créent des références circulaires échoueront é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 une fonction de serveur reçoit un objet et modifie ses propriétés, les propriétés du client ne sont pas affectées.

Renvois

void : cette méthode est asynchrone et ne renvoie pas directement. Toutefois, la fonction côté serveur peut renvoyer une valeur au client en tant que paramètre transmis à un gestionnaire de réussite. De plus, les types renvoyés sont soumis aux mêmes restrictions que les types de paramètres, à la différence qu'un élément form n'est pas un type renvoyé légal


withFailureHandler(function)

Définit une fonction de rappel à exécuter si la fonction côté serveur génère une exception. L'objet Error est transmis à la fonction en tant que premier argument, et l'objet utilisateur (le cas échéant) est transmis en tant que deuxième argument. Sans gestionnaire d'échecs, les échecs sont consignés dans la console JavaScript. Pour contourner ce problème, appelez withFailureHandler(null) ou fournissez un gestionnaire d'échecs qui ne fait rien.

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>

Paramètres

NomTypeDescription
functionFunctionUne fonction de rappel côté client à exécuter si la fonction côté serveur génère une exception. L'objet Error est transmis à la fonction en tant que premier argument, et l'objet utilisateur (le cas échéant) est transmis en tant que deuxième argument.

Renvois

google.script.run : cet "exécuteur de script" pour le chaînage


withSuccessHandler(function)

Définit une fonction de rappel à exécuter si la fonction côté serveur aboutit. La valeur renvoyée par le serveur est transmise à la fonction en tant que premier argument, et l'objet utilisateur (le cas échéant) est transmis en tant que deuxième argument.

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>

Paramètres

NomTypeDescription
functionFunctionUne fonction de rappel côté client à exécuter si la fonction côté serveur renvoie un résultat positif ; la valeur renvoyée par le serveur est transmise à la fonction en tant que premier argument et l'objet utilisateur (le cas échéant) est transmis en tant que deuxième argument

Renvois

google.script.run : cet "exécuteur de script" pour le chaînage


withUserObject(object)

Définit un objet à transmettre en tant que deuxième paramètre aux gestionnaires de réussite et d'échec. Cet "objet utilisateur" (à ne pas confondre avec la classe User) permet aux fonctions de rappel de répondre au contexte dans lequel le client a contacté le serveur. Étant donné que les objets utilisateur ne sont pas envoyés au serveur, ils ne sont pas soumis aux restrictions concernant les paramètres et les valeurs de retour pour les appels du serveur. En revanche, les objets utilisateur ne peuvent pas être des objets construits avec l'opérateur new.

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>

Paramètres

NomTypeDescription
objectObjectUn objet à transmettre en tant que deuxième paramètre aux gestionnaires de réussite et d'échec. Étant donné que les objets utilisateur ne sont pas envoyés au serveur, ils ne sont pas soumis aux restrictions concernant les paramètres et les valeurs de retour pour les appels du serveur. En revanche, les objets utilisateur ne peuvent pas être des objets construits avec l'opérateur new.

Renvois

google.script.run : cet "exécuteur de script" pour le chaînage