google.script.run
ist ein asynchroner
clientseitige JavaScript API, die es HTML-Dienstseiten ermöglicht, serverseitige
Apps Script-Funktionen Das folgende Beispiel zeigt die grundlegendsten Funktionen
von google.script.run
—
Funktion auf dem Server aufrufen
aus clientseitigem JavaScript.
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>
Wenn Sie dieses Skript als Web-App bereitstellen und dessen URL aufrufen,
etwas anderes, aber in den Protokollen sehen Sie, dass die Serverfunktion
doSomething()
wurde angerufen.
Clientseitige Aufrufe serverseitiger Funktionen erfolgen asynchron: nach dem Browser
anfordert, dass der Server die Funktion doSomething()
ausführt, fährt der Browser fort,
direkt in die nächste Codezeile, ohne auf eine Antwort warten zu müssen. Das bedeutet,
dass Serverfunktionsaufrufe
möglicherweise nicht in der erwarteten Reihenfolge ausgeführt werden. Wenn Sie
zwei Funktionsaufrufe gleichzeitig. Dann lässt sich nicht erkennen, welche Funktion
als Erstes ausführen; kann das Ergebnis bei jedem Laden der Seite abweichen. In dieser Situation
Erfolgs-Handler und Fehler-Handler
Ihren Code zu steuern.
Die google.script.run
API ermöglicht zehn gleichzeitige Aufrufe von Serverfunktionen. Wenn
und einen elften Aufruf ausführen, während 10 noch ausgeführt werden, wird die Serverfunktion
bis einer der zehn Plätze frei ist. In der Praxis sollten Sie
über diese Einschränkung nachdenken, zumal die meisten Browser bereits
die Anzahl gleichzeitiger Anfragen an denselben Server unter 10
In Firefox zum Beispiel beträgt die Beschränkung 6. Die meisten Browser verzögern ähnliche
Serveranfragen, bis eine der
bestehenden Anfragen abgeschlossen ist.
Parameter und Rückgabewerte
Sie können eine Serverfunktion mit Parametern aus dem Client aufrufen. Ähnlich verhält es sich bei einem Server-Funktion kann einen Wert an den Client als Parameter zurückgeben, der an einen Erfolgs-Handler.
Zulässige Parameter und Rückgabewerte sind JavaScript-Primitive wie Number
,
Boolean
, String
oder null
sowie JavaScript-Objekte und -Arrays, die
aus Primitiven, Objekten und Arrays. Ein form
-Element auf der Seite
ist auch als Parameter zulässig, muss aber der einzige Parameter der Funktion sein.
ist kein Rückgabewert zulässig. Anfragen schlagen fehl, wenn Sie versuchen, eine
Date
, Function
, DOM-Element außer form
oder einem anderen unzulässigen Typ
einschließlich unzulässiger Typen in Objekten oder Arrays. Objekte, durch die
Zirkelbezüge schlagen ebenfalls fehl und undefinierte Felder innerhalb von Arrays werden zu
null
Beachten Sie, dass ein an den Server übergebenes Objekt zu einer Kopie des Originals wird. Wenn ein Serverfunktion ein Objekt empfängt und seine Eigenschaften ändert, die Eigenschaften von nicht betroffen sind.
Erfolgs-Handler
Weil clientseitiger Code in der nächsten Zeile fortgesetzt wird, ohne auf einen Server zu warten
um einen entsprechenden Anruf zu tätigen,
withSuccessHandler(function)
können Sie eine clientseitige Callback-Funktion angeben, die ausgeführt wird, wenn der Server
antwortet. Wenn die Serverfunktion einen Wert zurückgibt, übergibt die API den Wert an
die neue Funktion als Parameter.
Im folgenden Beispiel wird eine Browserwarnung angezeigt, wenn der Server antwortet. Hinweis
dass dieses Codebeispiel eine Autorisierung erfordert, da die serverseitige Funktion
auf Ihr Gmail-Konto zugreifen. Die einfachste Möglichkeit, das Skript zu autorisieren, ist die Ausführung
manuell über den Script-Editor die getUnreadEmails()
-Funktion, bevor Sie
um die Seite zu laden. Wenn Sie alternativ
die Webanwendung bereitstellen, können Sie
und es als „Nutzer, der auf die Webanwendung zugreift“ auszuführen. In diesem Fall
zur Autorisierung aufgefordert, wenn Sie die App laden.
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>
Fehler-Handler
Falls der Server nicht
reagiert oder einen Fehler ausgibt,
withFailureHandler(function)
können Sie einen Fehler-Handler anstelle eines Erfolgs-Handlers angeben, mit dem
Error
-Objekt (falls vorhanden), das als Argument übergeben wird.
Wenn Sie keinen Fehler-Handler angeben, werden Fehler standardmäßig im
JavaScript-Konsole. Rufen Sie zum Überschreiben withFailureHandler(null)
auf oder geben Sie
Fehler-Handler, der nichts tut.
Die Syntax für Fehler-Handler ist fast identisch mit Erfolgs-Handlern, da Beispiel-Shows.
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>
Nutzerobjekte
Sie können denselben Erfolgs- oder Fehler-Handler für mehrere Aufrufe der
mit einem Aufruf von
withUserObject(object)
, um ein Objekt anzugeben, das als zweiter Parameter an den Handler übergeben wird.
Dieses „Nutzerobjekt“ ist nicht zu verwechseln mit dem
Klasse User
: Sie können auf die
Kontext, in dem der Client den Server kontaktiert hat. Da Nutzerobjekte nicht
an den Server gesendet werden, können sie fast alles sein, einschließlich Funktionen, DOM-
Elemente usw. ohne die Einschränkungen für Parameter und Rückgabewerte
für Serveraufrufe. Nutzerobjekte können jedoch nicht mit dem
Operator new
.
In diesem Beispiel wird durch Klicken auf eine der beiden Schaltflächen
vom Server übergeben, während die andere Schaltfläche unverändert lässt, obwohl sie
teilen Sie einen Erfolgs-Handler. Im onclick
-Handler wird das Schlüsselwort this
bezieht sich auf das button
selbst.
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>
Formulare
Wenn Sie eine Serverfunktion mit einem form
-Element als Parameter aufrufen, wird das Format
wird ein einzelnes Objekt mit Feldnamen als Schlüsseln und Feldwerten als Werte. Die
-Werte werden alle in Strings konvertiert, mit Ausnahme des Inhalts von file-input
-Feldern, die zu Blob
-Objekten werden.
In diesem Beispiel wird ein Formular einschließlich Dateieingabefeld verarbeitet, ohne es neu zu laden.
der Seite; wird die Datei in Google Drive hochgeladen und dann die URL für den
-Datei auf der clientseitigen Seite. Im onsubmit
-Handler wird das Schlüsselwort this
bezieht sich auf das Formular selbst. Nach dem Laden müssen alle Formulare auf der Seite
Die standardmäßige Aktion zum Senden ist von preventFormSubmit
deaktiviert. Dadurch wird verhindert,
im Falle einer Ausnahme
die Weiterleitung zu einer fehlerhaften URL deaktiviert.
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>
Script-Runner
Stellen Sie sich google.script.run
als Builder für einen Script-Runner vor. Wenn Sie
Erfolgs-Handler, Fehler-Handler oder Nutzerobjekt zu einem Skript-Runner hinzufügen,
den vorhandenen Läufer nicht ändern; erhalten Sie stattdessen einen
neuen Skript-Runner zurück,
mit neuen Verhaltensmustern.
Sie können eine beliebige Kombination und Reihenfolge von withSuccessHandler()
verwenden,
withFailureHandler()
und withUserObject()
. Sie können auch eine der
Funktionen eines Skript-Ausführers ändern, für den bereits ein Wert festgelegt ist. Das neue
überschreibt einfach den vorherigen Wert.
In diesem Beispiel wird ein allgemeiner Fehler-Handler für alle drei Serveraufrufe festgelegt, aber zwei separate Erfolgs-Handler:
var myRunner = google.script.run.withFailureHandler(onFailure);
var myRunner1 = myRunner.withSuccessHandler(onSuccess);
var myRunner2 = myRunner.withSuccessHandler(onDifferentSuccess);
myRunner1.doSomething();
myRunner1.doSomethingElse();
myRunner2.doSomething();
Private Funktionen
Serverfunktionen, deren Namen mit einem Unterstrich enden, gelten als privat.
Diese Funktionen können nicht von google.script
aufgerufen werden und ihre Namen werden niemals
an den Client gesendet. Sie können damit Implementierungsdetails ausblenden, die
auf dem Server geheim gehalten werden müssen. google.script
kann auch nichts sehen
Funktionen in Bibliotheken und Funktionen, die nicht
das auf oberster Ebene des Skripts festgelegt wurde.
In diesem Beispiel ist die Funktion getBankBalance()
im Client verfügbar.
Code; kann ein Nutzer, der Ihren Quellcode überprüft, seinen Namen auch dann finden, wenn Sie
nennen Sie ihn nicht. Die Funktionen deepSecret_()
und obj.objectMethod()
sind jedoch für
Kundschaft.
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>
Größe von Dialogfeldern in Google Workspace Anwendungen anpassen
Benutzerdefinierte Dialogfelder in Google Docs, Google Tabellen oder
Sie können die Größe von Formularen durch Aufrufen der
google.script.host
-Methoden
setWidth(width)
oder
setHeight(height)
in
clientseitigen Code. Um die anfängliche Größe eines Dialogfelds festzulegen, verwenden Sie die HtmlOutput
Methoden
setWidth(width)
und
setHeight(height)
.
Beachten Sie, dass Dialogfelder beim Ändern der Größe nicht im übergeordneten Fenster neu zentriert werden.
Die Größe der Seitenleisten kann nicht geändert werden.
Dialogfelder und Seitenleisten in Google Workspacewerden geschlossen
Wenn Sie mit dem HTML-Dienst eine
Dialogfeld oder Seitenleiste in Google Docs, Google Tabellen oder
Formulare können Sie die Oberfläche nicht durch Aufrufen von window.close()
schließen. Stattdessen müssen Sie
muss anrufen
google.script.host.close()
Ein Beispiel finden Sie im Abschnitt
HTML-Bereitstellung als Google Workspace Benutzeroberfläche.
Fokus des Browsers wird nach Google Workspaceverschoben
Um den Fokus im Browser des Nutzers von einem Dialogfeld oder einer Seitenleiste zurück auf den
Google Docs-, Google Tabellen- oder Google Formulare-Editoren, rufen Sie einfach die Methode
google.script.host.editor.focus()
Diese Methode ist besonders nützlich in Kombination mit der
Document service-Methoden
Document.setCursor(position)
und
Document.setSelection(range)