Classe google.script.run (API lato client)

google.script.run è un'API JavaScript lato client asincrona disponibile nelle pagine di servizio HTML in grado di chiamare funzioni Apps Script lato server. Per interagire con le finestre di dialogo o le barre laterali in Documenti, Fogli o Moduli Google dal codice lato client, utilizza google.script.host. Per maggiori informazioni, consulta la guida alla comunicazione con le funzioni server nel servizio HTML.

Metodi

MetodoTipo restituitoBreve descrizione
myFunction(...) (qualsiasi funzione lato server) void Esegue la funzione Apps Script lato server con il nome corrispondente.
withFailureHandler(function) google.script.run Imposta l'esecuzione di una funzione di callback se la funzione lato server genera un'eccezione.
withSuccessHandler(function) google.script.run Imposta l'esecuzione di una funzione di callback se la funzione lato server viene restituita correttamente.
withUserObject(object) google.script.run Imposta un oggetto da passare come secondo parametro ai gestori di operazione riuscita e di errore.

Documentazione dettagliata

myFunction(...) (qualsiasi funzione lato server)

Esegue la funzione Apps Script lato server con il nome corrispondente.

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>

Parametri

NomeTipoDescrizione
...La maggior parte dei tipi è legale, ma non gli elementi Date, Function o DOM oltre a form; consulta la descrizioneI parametri legali 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 anche come parametro, ma deve essere l'unico parametro della funzione. Le richieste non andranno a buon fine se tenti di passare un elemento Date, Function, DOM oltre a form o un altro tipo vietato, inclusi i tipi vietati all'interno di oggetti o array. 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.

Ritorni

void: questo metodo è asincrono e non restituisce direttamente. Tuttavia, la funzione lato server può restituire un valore al client come parametro passato a un gestore di operazione riuscita. Inoltre, i tipi restituiti sono soggetti alle stesse restrizioni dei tipi di parametro, ad eccezione del fatto che un elemento form non è un tipo legale restituito


withFailureHandler(function)

Imposta l'esecuzione di una funzione di callback se la funzione lato server genera un'eccezione. L'oggetto Error viene passato alla funzione come primo argomento, mentre l'oggetto utente (se presente) viene passato come secondo argomento. Senza 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 faccia nulla.

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>

Parametri

NomeTipoDescrizione
functionFunctionuna funzione di callback lato client da eseguire se la funzione lato server genera un'eccezione; l'oggetto Error viene passato alla funzione come primo argomento e l'oggetto utente (se presente) viene passato come secondo argomento

Ritorni

google.script.run: questo "script runner" per il concatenamento


withSuccessHandler(function)

Imposta l'esecuzione di una funzione di callback se la funzione lato server viene restituita correttamente. Il valore restituito del server viene passato alla funzione come primo argomento, mentre l'oggetto utente (se presente) viene passato come secondo argomento.

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>

Parametri

NomeTipoDescrizione
functionFunctionuna funzione di callback lato client da eseguire se la funzione lato server restituisce correttamente; il valore restituito dal server viene passato alla funzione come primo argomento e l'oggetto utente (se presente) viene passato come secondo argomento

Ritorni

google.script.run: questo "script runner" per il concatenamento


withUserObject(object)

Imposta un oggetto da passare come secondo parametro ai gestori di operazione riuscita e di errore. Questo "oggetto utente", da non confondere con la classe User, consente alle funzioni di callback di rispondere al contesto in cui il client ha contattato il server. Poiché gli oggetti utente non vengono inviati al server, non sono soggetti alle restrizioni sui parametri e restituiscono valori per le chiamate server. Tuttavia, gli oggetti utente non possono essere creati con l'operatore new.

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>

Parametri

NomeTipoDescrizione
objectObjectun oggetto da passare come secondo parametro ai gestori di operazione riuscita e di errore; poiché gli oggetti utente non vengono inviati al server, non sono soggetti alle limitazioni relative ai parametri e non restituiscono valori per le chiamate server. Tuttavia, gli oggetti utente non possono essere creati con l'operatore new

Ritorni

google.script.run: questo "script runner" per il concatenamento