Clase google.script.run (API del cliente)

google.script.run es una API de JavaScript del cliente asíncrona disponible en páginas de servicios HTML que pueden llamar a funciones de Apps Script del servidor. Para interactuar con los diálogos o las barras laterales de Documentos, Hojas de cálculo o Formularios de Google a partir del código del cliente, usa google.script.host. Si deseas obtener más información, consulta la guía para comunicarse con las funciones del servidor en el servicio HTML.

Métodos

MétodoTipo de datos que se muestraDescripción breve
myFunction(...) (cualquier función del servidor) void Ejecuta la función Apps Script del servidor con el nombre correspondiente.
withFailureHandler(function) google.script.run Establece una función de devolución de llamada para que se ejecute si la función del servidor arroja una excepción.
withSuccessHandler(function) google.script.run Establece una función de devolución de llamada para que se ejecute si la función del servidor se muestra correctamente.
withUserObject(object) google.script.run Establece un objeto para pasar como un segundo parámetro a los controladores de éxito y falla.

Documentación detallada

myFunction(...) (cualquier función del servidor)

Ejecuta la función Apps Script del servidor con el nombre correspondiente.

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

NombreTipoDescripción
...La mayoría de los tipos son legales, pero no Date, Function ni los elementos del DOM además de form; consulta la descripción.Los parámetros legales son primitivos de JavaScript, como Number, Boolean, String o null, así como arrays y objetos de JavaScript compuestos por primitivas, objetos y arrays. Un elemento form dentro de la página también es legal como parámetro, pero debe ser el único parámetro de la función. Las solicitudes fallan si intentas pasar un elemento Date, Function o DOM además de una form o algún otro tipo prohibido, incluidos los tipos prohibidos dentro de objetos o arrays. Los objetos que crean referencias circulares también fallarán y los campos no definidos dentro de los arrays se convertirán en null. Ten en cuenta que un objeto que se pasa al servidor se convierte en una copia del original. Si una función del servidor recibe un objeto y cambia sus propiedades, las propiedades del cliente no se ven afectadas.

Devolvedor

void: Este método es asíncrono y no muestra resultados directamente. Sin embargo, la función del servidor puede mostrar un valor al cliente como un parámetro que se pasa a un controlador de éxito. Además, los tipos de datos que se muestran están sujetos a las mismas restricciones que los tipos de parámetros, con la excepción de que un elemento form no es un tipo de datos legal que se muestra.

withFailureHandler(function)

Establece una función de devolución de llamada para que se ejecute si la función del servidor arroja una excepción. El objeto Error se pasa a la función como el primer argumento y el objeto de usuario (si corresponde) se pasa como un segundo argumento. Sin un controlador de fallas, las fallas se registran en la Consola de JavaScript. Para anular esto, llama a withFailureHandler(null) o proporciona un controlador de fallas que no realice ninguna acción.

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

NombreTipoDescripción
functionFunctionSe debe ejecutar una función de devolución de llamada del cliente si la función del servidor genera una excepción; el objeto Error se pasa a la función como primer argumento y el objeto de usuario (si existe) se pasa como un segundo argumento.

Devolvedor

google.script.run: Este “ejecutor de secuencias de comandos” para encadenar

withSuccessHandler(function)

Establece una función de devolución de llamada para que se ejecute si la función del servidor se muestra correctamente. El valor que se muestra del servidor se pasa a la función como el primer argumento y el objeto del usuario (si existe) se pasa como un 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

NombreTipoDescripción
functionFunctionuna función de devolución de llamada del cliente que se ejecute si la función del servidor se muestra correctamente; el valor que se muestra del servidor se pasa a la función como primer argumento y el objeto del usuario (si existe) se pasa como un segundo argumento.

Devolvedor

google.script.run: Este “ejecutor de secuencias de comandos” para encadenar

withUserObject(object)

Establece un objeto para pasar como un segundo parámetro a los controladores de éxito y falla. Este "objeto del usuario", que no debe confundirse con la clase User, permite que las funciones de devolución de llamada respondan al contexto en el que el cliente se comunicó con el servidor. Debido a que los objetos de usuario no se envían al servidor, no están sujetos a las restricciones de los parámetros ni muestran valores para las llamadas al servidor. Sin embargo, los objetos de usuario no pueden ser objetos construidos con el 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

NombreTipoDescripción
objectObjectun objeto para pasar como segundo parámetro a los controladores de éxito y falla; debido a que los objetos del usuario no se envían al servidor, no están sujetos a las restricciones de los parámetros ni a los valores de retorno para las llamadas al servidor. Sin embargo, los objetos de usuario no pueden ser objetos construidos con el operador new.

Devolvedor

google.script.run: Este “ejecutor de secuencias de comandos” para encadenar