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 pouvant appeler des fonctions Apps Script côté serveur. Pour interagir avec des boîtes de dialogue ou des 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 sur la 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 second 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 Date, Function ni un élément DOM en plus de form. Voir la descriptionLes paramètres juridiques sont des primitives JavaScript comme 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 d'un autre type interdit, y compris les types interdits dans les objets ou les tableaux. Les objets qui créent des références circulaires échouent également, et les champs non définis dans des tableaux deviennent null. Notez qu'un objet transmis au serveur devient une copie de l'original. Si une fonction du serveur reçoit un objet et modifie ses propriétés, les propriétés sur le client ne sont pas affectées.

Aller-retour

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, sauf qu'un élément form n'est pas un type renvoyé.


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 résoudre ce problème, appelez withFailureHandler(null) ou fournissez un gestionnaire d'échecs n'ayant aucun effet.

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 à cette fonction en tant que premier argument, et l'objet utilisateur (le cas échéant) est transmis en tant que deuxième argument.

Aller-retour

google.script.run : 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 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 second argument.

Aller-retour

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


withUserObject(object)

Définit un objet à transmettre en tant que second 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. Comme les objets utilisateur ne sont pas envoyés au serveur, ils ne sont pas soumis aux restrictions applicables aux paramètres et aux valeurs renvoyées pour les appels au serveur. Toutefois, 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
objectObjectObjet à transmettre en tant que second 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 sur les paramètres et aux valeurs renvoyées pour les appels au serveur. Toutefois, les objets utilisateur ne peuvent pas être des objets construits avec l'opérateur new.

Aller-retour

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