Questa pagina è stata tradotta dall'API Cloud Translation.

Servizio HTML: comunicazione con le funzioni server

google.script.run è un'API JavaScript lato client asincrona che consente alle pagine di servizio HTML di chiamare funzioni Apps Script lato server. L'esempio seguente mostra la funzionalità più di base di google.script.run: chiamare una funzione sul server dal codice 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 un'app web e ne visiti l'URL, non vedrai nulla, ma se visualizzi i log vedrai che è stata chiamata la funzione 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 passa immediatamente alla riga di codice successiva senza attendere una risposta. Ciò significa che le chiamate di funzioni del server potrebbero non essere eseguite nell'ordine previsto. Se esegui due chiamate di funzione contemporaneamente, non puoi sapere quale funzione verrà eseguita per prima; il risultato potrebbe essere diverso ogni volta che carichi la pagina. In questa situazione, i gestori dei successi e i gestori degli 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 verrà ritardata fino alla liberazione di uno dei 10 spot. In pratica, raramente è necessario considerare questa limitazione, soprattutto perché la maggior parte dei browser limita già il numero di richieste in parallelo allo stesso server con un numero inferiore a 10. In Firefox, ad esempio, il limite è 6. Allo stesso modo, la maggior parte dei browser ritarda le richieste del server in eccesso fino al completamento di una delle richieste esistenti.

Parametri e valori restituiti

Puoi chiamare una funzione server con i parametri dal client. In modo analogo, una funzione server può restituire un valore al client sotto forma di parametro passato a un gestore di operazione riuscita.

I parametri legali e i valori restituiti sono primitive JavaScript come Number, Boolean, String o null, nonché oggetti e array JavaScript composti da primitive, oggetti e array. Un elemento form all'interno della pagina è consentito come parametro, ma deve essere l'unico parametro della funzione e non è consentito come valore restituito. Se tenti di passare un elemento DOM Date, Function oltre a form o un altro tipo vietato, inclusi i tipi vietati all'interno di oggetti o array, le richieste non vanno a buon fine. Anche gli oggetti che creano riferimenti circolari avranno esito negativo e i campi non definiti all'interno degli array diventeranno 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à, le proprietà sul client non sono interessate.

Gestori del successo

Poiché il codice lato client passa alla riga successiva senza attendere il completamento di una chiamata al server, withSuccessHandler(function) ti consente di specificare una funzione di callback lato client da eseguire quando il server risponde. Se la funzione server restituisce un valore, l'API passa il valore alla nuova funzione come parametro.

L'esempio seguente mostra un avviso del browser quando il server risponde. Tieni presente che questo esempio di codice richiede l'autorizzazione perché la funzione lato server sta accedendo al tuo account Gmail. Il modo più semplice per autorizzare lo script è eseguire manualmente la funzione getUnreadEmails() dall'editor di script prima di caricare la pagina. In alternativa, quando esegui il deployment dell'app web, puoi scegliere di eseguirla come "utente che accede all'app web". In questo caso, ti verrà chiesta l'autorizzazione al momento del 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

Nel caso in cui il server non risponda o restituisca un errore, withFailureHandler(function) ti consente di specificare un gestore di errori anziché un gestore di operazioni riuscite, con l'oggetto Error (se presente) passato come argomento.

Per impostazione predefinita, se non specifichi un gestore degli errori, gli errori vengono registrati 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 per i gestori di successi, come mostrato in questo 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 per operazioni riuscite o errori per più chiamate al server chiamando withUserObject(object) per specificare un oggetto che verrà passato al gestore come secondo parametro. Questo "oggetto utente", da non confondere con la classe User, consente di rispondere al contesto in cui il client ha contattato il server. Poiché gli oggetti utente non vengono inviati al server, possono essere praticamente qualsiasi cosa, incluse funzioni, elementi DOM e così via, senza le restrizioni sui parametri e i valori restituiti per le chiamate al server. Tuttavia, gli oggetti utente non possono essere creati con l'operatore new.

In questo esempio, se fai clic su uno dei due pulsanti, il pulsante viene aggiornato con un valore del server e l'altro pulsante rimane invariato, anche se condividono un solo gestore delle operazioni riuscite. All'interno del gestore onclick, la parola chiave this fa riferimento allo stesso button.

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>

Forms

Se chiami una funzione 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. Tutti i valori vengono convertiti in stringhe, ad eccezione dei contenuti dei campi di input di file, 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 poi viene stampato l'URL del file 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 della pagina, l'azione di invio predefinita viene disattivata da preventFormSubmit. In questo modo, la pagina non reindirizza 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

Puoi considerare google.script.run come un generatore di "script runner". Se aggiungi un gestore di operazione riuscita, un gestore degli errori o un oggetto utente a un runner, il runner esistente non viene cambiato, ma viene restituito un nuovo esecutore di script con un nuovo comportamento.

Puoi utilizzare qualsiasi combinazione e qualsiasi ordine tra withSuccessHandler(), withFailureHandler() e withUserObject(). Puoi anche chiamare una qualsiasi delle funzioni di modifica su un'esecuzione di script che ha già un valore impostato. Il nuovo valore sostituisce semplicemente il valore precedente.

Questo esempio imposta un gestore degli errori comune per tutte e tre le chiamate al server, ma due gestori delle operazioni riuscite 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. google.script non può chiamare queste funzioni e i loro nomi non vengono mai inviati al client. Puoi quindi utilizzarle per nascondere i dettagli di implementazione che devono essere tenuti segreti sul server. Inoltre, google.script non è in grado di vedere le funzioni all'interno delle librerie e le funzioni non dichiarate al livello superiore dello script.

In questo esempio, la funzione getBankBalance() è disponibile nel codice client; un utente che controlla il tuo codice sorgente può scoprirne il nome anche se non la 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>

Ridimensionamento delle finestre di dialogo nelle Google Workspace applicazioni

Le finestre di dialogo personalizzate in Documenti, Fogli o Moduli Google possono essere ridimensionate chiamando i metodi google.script.host setWidth(width) o setHeight(height) nel codice lato client. Per impostare le dimensioni iniziali di una finestra di dialogo, utilizza i metodi HtmlOutput setWidth(width) e setHeight(height). Tieni presente che le finestre di dialogo non vengono nuovamente centrate nella finestra principale quando vengono ridimensionate e non è possibile ridimensionare le barre laterali.

Chiusura delle finestre di dialogo e delle barre laterali in Google Workspace

Se utilizzi il servizio HTML per visualizzare una finestra di dialogo o una barra laterale in Documenti, Fogli o Moduli Google, non puoi chiudere l'interfaccia chiamando window.close(). Devi invece chiamare google.script.host.close(). Per un esempio, consulta la sezione sulla pubblicazione del codice HTML come Google Workspace interfaccia utente.

Spostamento dello stato attivo del browser all'interno Google Workspace

Per impostare lo stato attivo nel browser dell'utente da una finestra di dialogo o una barra laterale all'editor di Documenti, Fogli o Moduli Google, richiama il metodo google.script.host.editor.focus(). Questo metodo è particolarmente utile in combinazione con i metodi Servizio documenti Document.setCursor(position) e Document.setSelection(range).