google.script.run è un servizio asincrono
API JavaScript lato client che consente alle pagine del servizio HTML di chiamare lato server
Funzioni di Apps Script. L'esempio seguente mostra le funzionalità di base
di google.script.run -
chiamare una funzione sul server
da JavaScript lato 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>
Se esegui il deployment di questo script come app web e visiti il relativo URL, non vedrai
ma se visualizzi i log, vedrai che la funzione del server
Hai ricevuto una chiamata doSomething().
Le chiamate lato client alle funzioni lato server sono asincrone: dopo che il browser
richiede al server di eseguire la funzione doSomething(), il browser continua
passare immediatamente alla riga di codice successiva senza aspettare una risposta. Ciò significa
che le chiamate di funzione del server non vengano eseguite nell'ordine previsto. Se effettui
due chiamate di funzione contemporaneamente, non c'è modo di sapere quale funzione
esegui prima l'esecuzione; il risultato potrebbe essere diverso ogni volta che carichi la pagina. In questa situazione,
gestori degli errori e gestori degli errori
per controllare il flusso del codice.
L'API google.script.run consente 10 chiamate simultanee alle funzioni del server. Se
effettui un'undicesima chiamata mentre 10 sono ancora in esecuzione, la funzione del server
ritardato fino a quando uno dei 10 posti non viene liberato. Nella pratica, raramente si dovrebbero
pensare a questa restrizione, soprattutto perché la maggior parte dei browser già limitano
il numero di richieste in parallelo allo stesso server a un numero inferiore a 10.
In Firefox, ad esempio, il limite è 6. La maggior parte dei browser ritarda in modo simile l'eccesso
richieste del server fino al completamento di una delle richieste esistenti.
Parametri e valori restituiti
Puoi chiamare una funzione server con parametri dal client. Analogamente, funzione server può restituire un valore al client come parametro passato a una funzione gestore del successo.
I parametri legali e i valori restituiti sono elementi primitivi JavaScript come Number,
Boolean, String o null, nonché gli oggetti e gli array JavaScript che
sono composte da primitive, oggetti e array. Un elemento form all'interno della pagina
è legale come parametro, ma deve essere l'unico parametro della funzione, e
non è legale come valore restituito. Le richieste non vanno a buon fine se tenti di passare
Date, Function, elemento DOM oltre a form o altro tipo vietato,
inclusi tipi vietati all'interno di oggetti o array. Oggetti che creano
anche i riferimenti circolari non riusciranno e i campi non definiti all'interno degli array
null.
Tieni presente che un oggetto passato al server diventa una copia dell'originale. Se una funzione server riceve un oggetto e ne modifica le proprietà, il client non ne è interessato.
Gestori del successo
Perché il codice lato client continua nella riga successiva senza attendere un server
per completare la chiamata,
withSuccessHandler(function)
consente di specificare una funzione di callback lato client da eseguire quando il server
risponde. Se la funzione server restituisce un valore, l'API lo passa a
la nuova funzione come parametro.
L'esempio seguente mostra un avviso del browser quando il server risponde. Nota
che questo esempio di codice richiede l'autorizzazione perché la funzione lato server è
quando accede al tuo account Gmail. Il modo più semplice per autorizzare lo script è eseguire
la funzione getUnreadEmails() manualmente dall'editor di script una volta prima di
per caricare la pagina. In alternativa, quando
eseguire il deployment dell'app web, puoi scegliere
eseguirla come "utente che accede all'app web", nel qual caso
viene richiesta l'autorizzazione quando carichi l'app.
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>
Gestori degli errori
Se il server non risponde o genera un errore,
withFailureHandler(function)
consente di specificare un gestore degli errori anziché un gestore del successo, con
Error
Oggetto (se presente) passato come argomento.
Per impostazione predefinita, se non specifichi un gestore degli errori, gli errori vengono registrati nel
nella console JavaScript. Per eseguire l'override, chiama withFailureHandler(null) o fornisci
un gestore degli errori che non fa nulla.
La sintassi per i gestori degli errori è quasi identica a quella dei gestori degli errori, in quanto come mostra un esempio.
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>
Oggetti utente
Puoi riutilizzare lo stesso gestore di operazioni riuscite o non riuscite per più chiamate al
al server richiamando
withUserObject(object)
per specificare un oggetto che verrà passato al gestore come secondo parametro.
Questo "oggetto utente" - da non confondere con
User. Ti consente di rispondere alle
contesto in cui il client ha contattato il server. Poiché gli oggetti utente non sono
inviati al server, possono essere praticamente qualsiasi cosa, tra cui funzioni,
elementi e così via, senza le restrizioni sui parametri e sui valori restituiti
per le chiamate al server. Tuttavia, gli oggetti utente non possono essere creati con
Operatore new.
In questo esempio, se fai clic su uno dei due pulsanti, il pulsante verrà aggiornato con una
valore dal server lasciando invariato l'altro pulsante, anche se
condividi un gestore del successo. All'interno del gestore onclick, la parola chiave this
si riferisce al button stesso.
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>
Moduli
Se chiami una funzione server con un elemento form come parametro, il formato
diventa un singolo oggetto con i nomi dei campi come chiavi e i valori dei campi come valori. La
vengono tutti convertiti in stringhe, ad eccezione dei contenuti dei campi
che diventano oggetti Blob.
In questo esempio viene elaborato un modulo, incluso un campo di input del file, senza ricaricare
la pagina; il file viene caricato su Google Drive e quindi stampa l'URL per
nella pagina lato client. All'interno del gestore onsubmit, la parola chiave this
fa riferimento al modulo stesso. Tieni presente che, al caricamento di tutti i moduli nella pagina,
l'azione di invio predefinita è disabilitata da preventFormSubmit. In questo modo
pagina di reindirizzamento a un URL impreciso in caso di eccezione.
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>
Esecutori di script
google.script.run può essere considerato un generatore per un "esecutore di script". Se
aggiungi un gestore degli errori, un gestore degli errori o un oggetto utente a un runner di script,
non stanno cambiando il runner esistente: viene restituito un nuovo runner dello script
con un nuovo comportamento.
Puoi utilizzare qualsiasi combinazione e qualsiasi ordine di withSuccessHandler(),
withFailureHandler() e withUserObject(). Puoi anche chiamare uno qualsiasi dei
Modifica delle funzioni su un runner di script che ha già un valore impostato. Il nuovo
sostituisce semplicemente il valore precedente.
Questo esempio imposta un gestore degli errori comune per tutte e tre le chiamate al server, gestori del successo separati:
var myRunner = google.script.run.withFailureHandler(onFailure);
var myRunner1 = myRunner.withSuccessHandler(onSuccess);
var myRunner2 = myRunner.withSuccessHandler(onDifferentSuccess);
myRunner1.doSomething();
myRunner1.doSomethingElse();
myRunner2.doSomething();
Funzioni private
Le funzioni server i cui nomi terminano con un trattino basso sono considerate private.
Queste funzioni non possono essere chiamate da google.script e i loro nomi non vengono mai
inviati al client. Puoi quindi utilizzarle per nascondere i dettagli di implementazione
devono essere segrete sul server. Inoltre google.script non può vedere
all'interno delle librerie e funzioni che non sono
dichiarate al primo livello dello script.
In questo esempio, la funzione getBankBalance() è disponibile nel client
codice; un utente che ispeziona il tuo codice sorgente può scoprirne il nome anche se
non chiamarla. Tuttavia, le funzioni deepSecret_() e obj.objectMethod() sono completamente invisibili per
il cliente.
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>
Ridimensionamento delle finestre di dialogo nelle Google Workspace applicazioni
Finestre di dialogo personalizzate in Documenti, Fogli Google o
I moduli possono essere ridimensionati richiamando il metodo
Metodi google.script.host
setWidth(width) oppure
setHeight(height) in
il codice lato client. Per impostare le dimensioni iniziali di una finestra di dialogo, utilizza HtmlOutput
metodi
setWidth(width)
e
setHeight(height)).
Tieni presente che le finestre di dialogo non vengono centrate nuovamente nella finestra principale quando vengono ridimensionate
impossibile ridimensionare le barre laterali.
Chiusura di finestre di dialogo e barre laterali in Google Workspace
Se utilizzi il servizio HTML per visualizzare
finestra di dialogo o barra laterale in Documenti, Fogli Google oppure
Moduli, non puoi chiudere l'interfaccia chiamando window.close(). Invece,
deve chiamare
google.script.host.close()
Per un esempio, consulta la sezione
pubblicare il codice HTML come Google Workspace interfaccia utente.
Spostamento dello stato attivo del browser in Google Workspace
Per spostare lo stato attivo nel browser dell'utente da una finestra di dialogo o una barra laterale a uno
Editor di Documenti, Fogli o Moduli Google: chiama semplicemente il metodo
google.script.host.editor.focus()
Questo metodo è particolarmente utile in combinazione con
Metodi del servizio di documenti
Document.setCursor(position)
e
Document.setSelection(range).