Klasse google.script.run (Clientseitiges API)

google.script.run ist eine asynchrone clientseitige JavaScript API, die auf HTML-Dienstseiten verfügbar ist und serverseitige Apps Script-Funktionen aufrufen kann. Verwenden Sie google.script.host, um über clientseitigen Code mit Dialogfeldern oder Seitenleisten in Google Docs, Google Tabellen oder Google Formulare zu interagieren. Weitere Informationen findest du im Leitfaden zur Kommunikation mit Serverfunktionen im HTML-Dienst.

Methoden

MethodeRückgabetypKurzbeschreibung
myFunction(...) (beliebige serverseitige Funktion) void Führt die serverseitige Apps Script-Funktion mit dem entsprechenden Namen aus.
withFailureHandler(function) google.script.run Legt eine Callback-Funktion fest, die ausgeführt werden soll, wenn die serverseitige Funktion eine Ausnahme auslöst.
withSuccessHandler(function) google.script.run Legt eine Callback-Funktion fest, die ausgeführt werden soll, wenn die serverseitige Funktion erfolgreich zurückgegeben wird.
withUserObject(object) google.script.run Legt ein Objekt fest, das als zweiter Parameter an die Erfolgs- und Fehler-Handler übergeben wird.

Detaillierte Dokumentation

myFunction(...) (beliebige serverseitige Funktion)

Führt die serverseitige Apps Script-Funktion mit dem entsprechenden Namen aus.

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>

Parameter

NameTypBeschreibung
...Die meisten Typen sind zulässig, außer Date-, Function- oder DOM-Elementen außer form (siehe Beschreibung).Zulässige Parameter sind JavaScript-Primitive wie Number, Boolean, String oder null sowie JavaScript-Objekte und -Arrays, die aus Primitiven, Objekten und Arrays bestehen. Ein form-Element auf der Seite kann auch als Parameter verwendet werden, muss jedoch der einzige Parameter der Funktion sein. Anfragen schlagen fehl, wenn Sie versuchen, ein Date-, Function-, DOM-Element neben form oder einen anderen unzulässigen Typ zu übergeben, einschließlich unzulässiger Typen innerhalb von Objekten oder Arrays. Objekte, die Zirkelbezüge erstellen, schlagen ebenfalls fehl und nicht definierte Felder in Arrays werden zu null. Ein an den Server übergebenes Objekt wird zu einer Kopie des Originals. Wenn eine Serverfunktion ein Objekt empfängt und seine Attribute ändert, sind die Attribute des Clients nicht betroffen.

Return

void: Diese Methode ist asynchron und gibt nicht direkt zurück. Die serverseitige Funktion kann jedoch einen Wert als Parameter, der an einen Erfolgs-Handler übergeben wird, an den Client zurückgeben. Rückgabetypen unterliegen außerdem denselben Einschränkungen wie Parametertypen, außer dass das Element form kein zulässiger Rückgabetyp ist.

withFailureHandler(function)

Legt eine Callback-Funktion fest, die ausgeführt werden soll, wenn die serverseitige Funktion eine Ausnahme auslöst. Das Objekt Error wird als erstes Argument an die Funktion und gegebenenfalls das Nutzerobjekt als zweites Argument übergeben. Ohne einen Fehler-Handler werden Fehler in der JavaScript-Konsole protokolliert. Rufen Sie zum Überschreiben withFailureHandler(null) auf oder geben Sie einen Fehler-Handler an, der nichts ausführt.

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>

Parameter

NameTypBeschreibung
functionFunctionEine clientseitige Callback-Funktion, die ausgeführt wird, wenn die serverseitige Funktion eine Ausnahme auslöst. Das Error-Objekt wird als erstes Argument an die Funktion und das Nutzerobjekt (falls vorhanden) als zweites Argument an die Funktion übergeben.

Return

google.script.run – dieser Skript-Runner zum Verketten

withSuccessHandler(function)

Legt eine Callback-Funktion fest, die ausgeführt werden soll, wenn die serverseitige Funktion erfolgreich zurückgegeben wird. Der Rückgabewert des Servers wird als erstes Argument an die Funktion und gegebenenfalls das Nutzerobjekt als zweites Argument übergeben.

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>

Parameter

NameTypBeschreibung
functionFunctionEine clientseitige Callback-Funktion, die ausgeführt wird, wenn die serverseitige Funktion erfolgreich zurückgibt. Der Rückgabewert des Servers wird als erstes Argument an die Funktion übergeben. Das Nutzerobjekt (falls vorhanden) wird als zweites Argument übergeben.

Return

google.script.run – dieser Skript-Runner zum Verketten

withUserObject(object)

Legt ein Objekt fest, das als zweiter Parameter an die Erfolgs- und Fehler-Handler übergeben wird. Durch dieses „Nutzerobjekt“, das nicht mit der Klasse User zu verwechseln ist, können die Callback-Funktionen auf den Kontext reagieren, in dem der Client den Server kontaktiert hat. Da Nutzerobjekte nicht an den Server gesendet werden, unterliegen sie nicht den Parametereinschränkungen und geben Werte für Serveraufrufe zurück. Nutzerobjekte können jedoch keine Objekte sein, die mit dem Operator new erstellt wurden.

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>

Parameter

NameTypBeschreibung
objectObjectEin Objekt, das als zweiter Parameter an die Erfolgs- und Fehler-Handler übergeben wird. Da Nutzerobjekte nicht an den Server gesendet werden, unterliegen sie nicht den Parametereinschränkungen und Rückgabewerten für Serveraufrufe. Nutzerobjekte können jedoch keine Objekte sein, die mit dem Operator new erstellt wurden.

Return

google.script.run – dieser Skript-Runner zum Verketten