google.script.run è un'API JavaScript lato client asincrona che consente alle pagine del servizio HTML di chiamare le funzioni di Apps Script lato server. L'esempio seguente mostra la funzionalità più semplice
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 suo URL, non vedrai nulla, ma se visualizzi i log, vedrai che è stata chiamata la funzione del server 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 immediatamente alla riga di codice successiva senza attendere una risposta. Ciò significa che le chiamate alle funzioni del server potrebbero non essere eseguite nell'ordine previsto. Se effettui due chiamate di funzione contemporaneamente, non è possibile sapere quale funzione viene eseguita per prima; il risultato potrebbe variare ogni volta che carichi la pagina. In questa situazione,
i gestori di successo e i gestori di errori
aiutano a 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 viene ritardata finché uno dei 10 slot non viene liberato. In pratica, raramente dovrai pensare a questa limitazione, soprattutto perché la maggior parte dei browser limita già il numero di richieste simultanee 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 le richieste del server in eccesso finché una delle richieste esistenti non viene completata.
Parametri e valori restituiti
Chiama una funzione del server con i parametri del client. Allo stesso modo, una funzione del server può restituire un valore al client come parametro passato a un gestore di successo.
I parametri e i valori restituiti legali sono primitive JavaScript come Number, Boolean, String o null, nonché oggetti e array JavaScript composti da primitive, oggetti e array. Anche 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 un elemento Date, Function, DOM oltre a un form o un altro tipo vietato, inclusi i tipi vietati all'interno di oggetti o array. Anche gli oggetti che creano riferimenti circolari non vanno a buon fine e i campi non definiti all'interno degli array diventano null.
Tieni presente che un oggetto passato al server diventa una copia dell'originale. Se una funzione del server riceve un oggetto e ne modifica le proprietà, le proprietà del client non vengono interessate.
Gestori di successo
Poiché le chiamate google.script.run sono asincrone, il codice lato client continua alla riga successiva senza attendere una risposta. Per specificare una funzione di callback
da eseguire quando il server risponde, utilizza
withSuccessHandler(function).
Se la funzione del server restituisce un valore, l'API passa questo valore alla funzione di callback come parametro.
L'esempio seguente mostra un avviso del browser quando il server risponde. Questo esempio di codice richiede l'autorizzazione perché la funzione lato server accede al tuo account Gmail. Per autorizzare lo script, esegui manualmente la funzione getUnreadEmails dall'editor di script una volta prima di caricare la pagina. In alternativa, quando
esegui il deployment dell'app web da
eseguire come "utente che accede all'app web", ti viene richiesta l'autorizzazione
durante il caricamento dell'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 di errori
Se il server non risponde o genera un errore, withFailureHandler(function) ti consente di specificare un gestore di errori da eseguire al posto di un gestore di successo.
Se si verifica un errore, l'API passa il
Error
oggetto come argomento al gestore di errori.
Per impostazione predefinita, se non specifichi un gestore di errori, gli errori vengono registrati nella console JavaScript. Per ignorare questo comportamento, chiama withFailureHandler(null) o fornisci un gestore di errori che non esegue alcuna operazione.
La sintassi dei gestori di errori è quasi identica a quella dei gestori di successo, come mostra questo esempio.
Code.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function getUnreadEmails() {
// 'got' instead of 'get' throws 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
Per riutilizzare lo stesso gestore di successo o di errori per più chiamate al
server, chiama
withUserObject(object)
per specificare un oggetto passato al gestore come secondo parametro.
Questo "oggetto utente", da non confondere con la
User classe, ti consente di rispondere al
contesto in cui il client ha contattato il server. Poiché gli oggetti utente non vengono inviati al server, possono essere quasi qualsiasi cosa, incluse funzioni ed elementi DOM, senza le limitazioni sui parametri e sui valori restituiti per le chiamate del server. Gli oggetti utente non possono essere oggetti creati con l'operatore new.
In questo esempio, se fai clic su uno dei due pulsanti, questo viene aggiornato con un valore del server, mentre l'altro pulsante rimane invariato, anche se condividono un unico gestore di 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 del server con un elemento form come parametro, il modulo diventa un singolo oggetto con i nomi dei campi come chiavi e i valori dei campi come valori. I
valori vengono tutti convertiti in stringhe, ad eccezione dei contenuti dei campi di input dei file, che diventano oggetti Blob.
Questo esempio elabora un modulo, incluso un campo di immissione dei file, senza ricaricare la pagina; carica il file su Google Drive e poi stampa l'URL del file nella pagina lato client. All'interno del gestore onsubmit, la parola chiave this si riferisce al modulo stesso. Tieni presente che al caricamento tutti i moduli della pagina hanno l'azione di invio predefinita disattivata da preventFormSubmit. In questo modo, la pagina non viene reindirizzata a un URL errato 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
Considera google.script.run come un generatore di un "esecutore di script". Se aggiungi un gestore di successo, un gestore di errori o un oggetto utente a un esecutore di script, non stai modificando l'esecutore esistente; al contrario, ricevi un nuovo esecutore di script con un nuovo comportamento.
Utilizza qualsiasi combinazione e qualsiasi ordine di withSuccessHandler, withFailureHandler e withUserObject. Chiama anche una delle funzioni di modifica su un esecutore di script che ha già un valore impostato. Il nuovo valore sostituisce il precedente.
Questo esempio imposta un gestore di errori comune per tutte e tre le chiamate del server, ma due gestori di 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 del 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 utilizzarli per nascondere i dettagli di implementazione che devono essere mantenuti segreti sul server. google.script non può visualizzare nemmeno le
funzioni all'interno delle librerie o le funzioni non
dichiarate al livello superiore dello script.
In questo esempio, la funzione getBankBalance è disponibile nel codice client; un utente che esamina il codice sorgente può scoprire il suo nome anche se non lo chiami. Tuttavia, le funzioni deepSecret_ e obj.objectMethod sono completamente invisibili al client.
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>Ridimensionare le finestre di dialogo nelle applicazioni Google Workspace
Le finestre di dialogo personalizzate in Documenti Google,
Fogli Google o Moduli Google possono essere ridimensionate chiamando i
google.script.host metodi
setWidth(width) o
setHeight(height) nel
codice lato client. (Per impostare le dimensioni iniziali di una finestra di dialogo, utilizza i HtmlOutput
metodi
setWidth(width)
e
setHeight(height).)
Tieni presente che le finestre di dialogo non vengono centrate nuovamente nella finestra principale quando vengono ridimensionate e
non è possibile ridimensionare le barre laterali.
Chiudere le finestre di dialogo e le barre laterali in Google Workspace
Se utilizzi il servizio HTML per visualizzare una finestra di dialogo o
barra laterale in Documenti, Fogli,
o Moduli Google, non puoi chiudere l'interfaccia chiamando
window.close. Al contrario, devi chiamare
google.script.host.close.
Per un esempio, consulta la sezione relativa alla pubblicazione di HTML come interfaccia
utente
di Google Workspace.
Spostare lo 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 alle}editor di Documenti, Fogli o Moduli Google, chiama il
metodo
google.script.host.editor.focus.
Questo metodo è particolarmente utile in combinazione con i metodi del servizio Documenti Document.setCursor(position)
e
Document.setSelection(range).