Classe google.script.run (API do lado do cliente)

google.script.run é uma API JavaScript assíncrona do lado do cliente disponível em páginas de serviço HTML que podem chamar funções do Apps Script do servidor. Para interagir com caixas de diálogo ou barras laterais nos Documentos, Planilhas ou Formulários Google usando o código do lado do cliente, use google.script.host. Para mais informações, consulte o guia de comunicação com funções do servidor no serviço HTML.

Métodos

MétodoTipo de retornoBreve descrição
myFunction(...) (qualquer função do lado do servidor) void Executa a função Apps Script do lado do servidor com o nome correspondente.
withFailureHandler(function) google.script.run Define uma função de retorno de chamada a ser executada se a função do lado do servidor gerar uma exceção.
withSuccessHandler(function) google.script.run Define uma função de retorno de chamada a ser executada se a função do lado do servidor retornar com êxito.
withUserObject(object) google.script.run Define um objeto para transmitir como um segundo parâmetro aos gerenciadores de sucesso e falha.

Documentação detalhada

myFunction(...) (qualquer função do lado do servidor)

Executa a função Apps Script do lado do servidor com o nome correspondente.

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>

Parâmetros

NomeTipoDescrição
...A maioria dos tipos é legal, mas não Date, Function ou elemento DOM além de form. Consulte a descrição.Os parâmetros legais são primitivos do JavaScript, como Number, Boolean, String ou null, além de objetos e matrizes do JavaScript compostos por primitivos, objetos e matrizes. Um elemento form na página também é legal como um parâmetro, mas precisa ser o único parâmetro da função. As solicitações vão falhar se você tentar passar um elemento Date, Function, DOM além de um form ou outro tipo proibido, incluindo tipos proibidos dentro de objetos ou matrizes. Os objetos que criam referências circulares também vão falhar, e os campos indefinidos em matrizes vão se tornar null. Observe que um objeto transmitido ao servidor se torna uma cópia do original. Se uma função do servidor receber um objeto e mudar as propriedades, as propriedades no cliente não serão afetadas.

Retornar

void: esse método é assíncrono e não retorna diretamente. No entanto, a função do lado do servidor pode retornar um valor ao cliente como um parâmetro transmitido a um gerenciador de sucesso. Além disso, os tipos de retorno estão sujeitos às mesmas restrições dos tipos de parâmetro, exceto que um elemento form não é um tipo de retorno legal.

withFailureHandler(function)

Define uma função de retorno de chamada a ser executada se a função do lado do servidor gerar uma exceção. O objeto Error é transmitido para a função como o primeiro argumento, e o objeto do usuário (se houver) é transmitido como um segundo argumento. Sem um gerenciador de falhas, as falhas são registradas no Console JavaScript. Para substituir isso, chame withFailureHandler(null) ou forneça um gerenciador de falhas que não faça nada.

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>

Parâmetros

NomeTipoDescrição
functionFunctionuma função de callback do lado do cliente a ser executada se a função do lado do servidor gerar uma exceção. O objeto Error é transmitido para a função como o primeiro argumento e o objeto do usuário (se houver) é passado como um segundo argumento.

Retornar

google.script.run: este "script executor" para encadeamento

withSuccessHandler(function)

Define uma função de retorno de chamada a ser executada se a função do lado do servidor retornar com êxito. O valor de retorno do servidor é transmitido para a função como primeiro argumento, e o objeto de usuário (se houver) é passado como um segundo argumento.

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>

Parâmetros

NomeTipoDescrição
functionFunctionuma função de retorno de chamada do lado do cliente a ser executada se a função do lado do servidor retornar com êxito. O valor de retorno do servidor é passado para a função como o primeiro argumento e o objeto de usuário (se houver) é transmitido como um segundo argumento.

Retornar

google.script.run: este "script executor" para encadeamento

withUserObject(object)

Define um objeto para transmitir como um segundo parâmetro aos gerenciadores de sucesso e falha. Este objeto do usuário, que não deve ser confundido com a classe User, permite que as funções de retorno de chamada respondam ao contexto em que o cliente entrou em contato com o servidor. Como os objetos do usuário não são enviados para o servidor, eles não estão sujeitos às restrições de parâmetros e valores de retorno para chamadas do servidor. Os objetos de usuário não podem, no entanto, ser objetos construídos com o operador 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>

Parâmetros

NomeTipoDescrição
objectObjectum objeto a ser passado como um segundo parâmetro para os gerenciadores de sucesso e falha. Como os objetos de usuários não são enviados para o servidor, eles não estão sujeitos às restrições de parâmetros e valores de retorno para chamadas do servidor. Os objetos de usuário não podem, no entanto, ser objetos construídos com o operador new

Retornar

google.script.run: este "script executor" para encadeamento