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

A 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 no lado do servidor. Para interagir com caixas de diálogo ou barras laterais nos Documentos, Planilhas ou Formulários Google pelo código do lado do cliente, use google.script.host. Para mais informações, consulte o guia para comunicação com as 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 do 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 a ser transmitido como um segundo parâmetro para os gerenciadores de sucesso e falha.

Documentação detalhada

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

Executa a função do 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çãoOs parâmetros legais são primitivos de JavaScript, como Number, Boolean, String ou null, além de objetos e matrizes JavaScript que são compostos por primitivos, objetos e matrizes. Um elemento form na página também é válido como parâmetro, mas precisa ser o único parâmetro da função. As solicitações falham se você tentar transmitir um elemento Date, Function, DOM além de form ou outro tipo proibido, incluindo tipos proibidos dentro de objetos ou matrizes. Objetos que criam referências circulares também falham, e campos indefinidos dentro de matrizes se tornam null. Observe que um objeto passado para o servidor se torna uma cópia do original. Se uma função de servidor receber um objeto e alterar as propriedades dele, as propriedades no cliente não serão afetadas.

Retorno

void: esse método é assíncrono e não retorna diretamente. No entanto, a função do lado do servidor pode retornar um valor para o cliente como um parâmetro passado para um gerenciador de sucesso. Além disso, os tipos de retorno estão sujeitos às mesmas restrições que os 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 modificar 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 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.

Retorno

google.script.run: este "executor de script" 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 o primeiro argumento, e o objeto do usuário (se houver) é transmitido 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 for retornada com êxito. O valor de retorno do servidor é transmitido para a função como o primeiro argumento, e o objeto do usuário (se houver) é transmitido como um segundo argumento.

Retorno

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

withUserObject(object)

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

Retorno

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