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ços HTML que podem chamar o Apps Script do lado do servidor . Interagir com caixas de diálogo ou barras laterais em Documentos, Planilhas ou Formulários Google no lado do cliente use google.script.host. Para mais informações, consulte a guia para comunicação com funções de 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 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 sucesso.
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 é válida, mas não Date, Function, ou elemento DOM além de form. ver descriçãoOs parâmetros legais são JavaScript primitivos, como Number, Boolean, String ou null, bem como objetos JavaScript e matrizes compostas de primitivos, objetos e matrizes. Um elemento form na página também é válido como parâmetro, mas ele precisa ser o único parâmetro da função. As solicitações falharão se você tentar passar um Date, Function, um elemento DOM além de um form ou outro proibido, incluindo tipos proibidos dentro de objetos ou matrizes. Objetos que criam formas circulares as referências também vão falhar, e os campos indefinidos dentro das matrizes se tornarão null. Observe que um objeto passado para o servidor torna-se uma cópia do original. Se uma função de servidor receber um e alterar suas propriedades, as propriedades do cliente não serão afetadas.

Retornar

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

withFailureHandler(function)

Define uma função de retorno de chamada a ser executada se a função do servidor gerar uma exceção. A Error é passado para a função como o primeiro argumento, e o objeto de usuário (se houver) é transmitido como um segundo argumento. Sem um gerenciador de falhas, as falhas são registradas no Console JavaScript. Para substituir isto, chame withFailureHandler(null) ou forneça um gerenciador de falhas que não faz 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 executar se a função do lado do servidor gerar uma exceção; as Error é passado para a função como o primeiro argumento, e o O objeto de usuário (se houver) é transmitido como um segundo argumento.

Retornar

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 sucesso. O servidor valor de retorno é passado para a função como o primeiro argumento, e o user object (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 callback do lado do cliente executar se a função do lado do servidor retornar com êxito; o valor de retorno do servidor é passado ao como primeiro argumento, e o objeto user (se houver) é passado como um segundo argumento

Retornar

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 "usuário object&quot; Não confunda com o User: permite que o callback respondem ao contexto em que o cliente entrou em contato com o servidor. Como os objetos do usuário não forem enviados ao servidor, eles não estão sujeitos às restrições de parâmetros e valores de retorno para chamadas do servidor. No entanto, os objetos de usuário não podem ser objetos construído 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 transmitido como um segundo parâmetro aos gerenciadores de sucesso e falha. como os objetos de usuário não são enviados ao servidor, eles não são sujeito à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 construídos com o operador new

Retornar

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