google.script.run
es una aplicación asíncrona
API de JavaScript del cliente que permite que las páginas de servicios HTML llamen al servidor
Funciones de Apps Script En el siguiente ejemplo, se muestra la funcionalidad más básica de google.script.run
: llamar a una función en el servidor desde JavaScript del cliente.
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> </html>
Si implementas esta secuencia de comandos como una aplicación web y visitas su URL, no verás los cambios.
pero si ves los registros, verás que la función del servidor
Se llamó a doSomething()
.
Las llamadas del cliente a las funciones del servidor son asíncronas: después de que el navegador
solicita que el servidor ejecute la función doSomething()
, el navegador continúa
a la siguiente línea de código
sin esperar una respuesta. Esto significa
que las llamadas a funciones del servidor
no se ejecuten en el orden esperado. Si realizas
dos llamadas a función al mismo tiempo, no hay forma de saber qué función se ejecutará
primero. El resultado puede diferir cada vez que cargas la página. En esta situación,
controladores de éxito y controladores de fallas
te ayudan a controlar el flujo de tu código.
La API de google.script.run
permite 10 llamadas simultáneas a las funciones del servidor. Si
si realizas una undécima llamada mientras 10 aún se están ejecutando, la función del servidor será
retrasado hasta que se libere uno de los 10 puestos. En la práctica, rara vez deberías tener que pensar en esta restricción, en especial, porque la mayoría de los navegadores ya limitan la cantidad de solicitudes simultáneas al mismo servidor a una cantidad inferior a 10.
Por ejemplo, en Firefox, el límite es 6. La mayoría de los navegadores retrasan de manera similar las solicitudes de servidor excesivas hasta que se completa una de las solicitudes existentes.
Parámetros y valores de muestra
Puedes llamar a una función del servidor con parámetros desde el cliente. De manera similar, un “server” puede mostrar un valor al cliente como un parámetro que se pasa a un controlador de éxito.
Los parámetros legales y los valores que se muestran son primitivas de JavaScript, como Number
.
Boolean
, String
o null
, así como los objetos y arrays de JavaScript que
constan de 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 y
no es legal como valor de retorno. Las solicitudes fallan si intentas pasar un
Date
, Function
, elemento DOM además de un form
o algún otro tipo prohibido,
incluidos los tipos prohibidos dentro de objetos o arrays. Objetos que crean
las referencias circulares también fallarán y los campos indefinidos de los arrays
null
Ten en cuenta que un objeto que se pasa al servidor se convierte en una copia del original. Si una “server” recibe un objeto y cambia sus propiedades, las propiedades en el cliente no se ven afectados.
Controladores de éxito
Debido a que el código del cliente continúa en la siguiente línea sin esperar a que se complete una llamada al servidor, withSuccessHandler(function)
te permite especificar una función de devolución de llamada del cliente para que se ejecute cuando el servidor responda. Si la función del servidor muestra un valor, la API lo pasa a la función nueva como un parámetro.
En el siguiente ejemplo, se muestra una alerta del navegador cuando el servidor responde. Nota
que esta muestra de código requiere autorización porque la función del servidor está
accediendo a tu cuenta de Gmail. La forma más sencilla de autorizar la secuencia de comandos es ejecutar
la función getUnreadEmails()
de forma manual desde el editor de secuencias de comandos una vez antes de
cargar la página. De manera alternativa, cuando
implementar la app web, puedes elegir
ejecutarla como “usuario que accede a la aplicación web”, en cuyo caso, serás
se te solicitará autorización cuando cargues la app.
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>
Controladores de fallas
En caso de que el servidor no responda o arroje un error, withFailureHandler(function)
te permite especificar un controlador de fallas en lugar de un controlador de éxito, con el objeto Error
(si corresponde) pasado como argumento.
De forma predeterminada, si no especificas un controlador de fallas, las fallas se registran en
Consola de JavaScript. Para anularlo, llama a withFailureHandler(null)
o proporciona
un controlador de fallas que no hace nada.
La sintaxis de los controladores de fallas es casi idéntica a la de los controladores de éxito, ya que de ejemplo.
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>
Objetos de usuario
Puedes volver a usar el mismo controlador de éxito o fracaso para varias llamadas al
de servicio llamando
withUserObject(object)
para especificar un objeto que se pasará al controlador como segundo parámetro.
Este “objeto de usuario” no debe confundirse con el
User
: te permite responder a las
contexto en el que el cliente se comunicó con el servidor. Dado que los objetos de usuario
enviados al servidor, pueden ser casi cualquier cosa, incluidas funciones, DOM
elementos, etcétera, sin restricciones de parámetros ni valores que se muestran
para las llamadas al servidor. Sin embargo, los objetos de usuario no pueden ser objetos construidos con el operador new
.
En este ejemplo, si haces clic en cualquiera de los dos botones, ese botón se actualizará con una
valor del servidor y dejar el otro botón sin modificar, aunque no
compartir un controlador de éxito. Dentro del controlador onclick
, la palabra clave this
se refiere al button
en sí.
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>
Formularios
Si llamas a una función de servidor con un elemento form
como parámetro, el formulario
se convierte en un único objeto con nombres de campo como claves y valores de campo como valores. Todos los valores se convierten en cadenas, excepto el contenido de los campos de entrada de archivo, que se convierten en objetos Blob
.
En este ejemplo, se procesa un formulario, incluido un campo de entrada de archivo, sin volver a cargar
la página; se sube el archivo a Google Drive y, luego, se imprime la URL del archivo
en la página del cliente. Dentro del controlador onsubmit
, la palabra clave this
se refiere al formulario en sí. Tenga en cuenta que, cuando se carguen, todos los formularios de la página
la acción de envío predeterminada inhabilitada por preventFormSubmit
. Esto evita que la página redireccione a una URL imprecisa en caso de que se produzca una excepción.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); } function processForm(formObject) { var formBlob = formObject.myFile; var driveFile = DriveApp.createFile(formBlob); return driveFile.getUrl(); }
Index.html
<!DOCTYPE html> <html> <head> <base target="_top"> <script> // Prevent forms from submitting. function preventFormSubmit() { var forms = document.querySelectorAll('form'); for (var i = 0; i < forms.length; i++) { forms[i].addEventListener('submit', function(event) { event.preventDefault(); }); } } window.addEventListener('load', preventFormSubmit); function handleFormSubmit(formObject) { google.script.run.withSuccessHandler(updateUrl).processForm(formObject); } function updateUrl(url) { var div = document.getElementById('output'); div.innerHTML = '<a href="' + url + '">Got it!</a>'; } </script> </head> <body> <form id="myForm" onsubmit="handleFormSubmit(this)"> <input name="myFile" type="file" /> <input type="submit" value="Submit" /> </form> <div id="output"></div> </body> </html>
Ejecutores de secuencias de comandos
Puedes pensar en google.script.run
como un compilador para un "ejecutor de secuencias de comandos". Si
agregar un controlador de éxito, un controlador de fallas
o un objeto de usuario a un ejecutor de secuencias de comandos
No cambien el ejecutor existente. en su lugar, obtendrás un nuevo ejecutor de secuencias de comandos
con el nuevo comportamiento.
Puedes usar cualquier combinación y cualquier orden de withSuccessHandler()
,
withFailureHandler()
y withUserObject()
. También puedes llamar a cualquiera de
modificar funciones en un ejecutor de secuencias de comandos que ya tiene un valor establecido. La nueva herramienta
valor anula al anterior.
En este ejemplo, se configura un controlador de fallas común para las tres llamadas al servidor, pero dos controladores de éxito separados:
var myRunner = google.script.run.withFailureHandler(onFailure);
var myRunner1 = myRunner.withSuccessHandler(onSuccess);
var myRunner2 = myRunner.withSuccessHandler(onDifferentSuccess);
myRunner1.doSomething();
myRunner1.doSomethingElse();
myRunner2.doSomething();
Funciones privadas
Las funciones de servidor cuyos nombres terminan con un guion bajo se consideran privadas.
google.script
no puede llamar a estas funciones, y sus nombres nunca son
enviados al cliente. Así, puedes usarlas para ocultar los detalles de implementación que
deben mantenerse en secreto en el servidor. google.script
tampoco puede ver las funciones dentro de las bibliotecas ni las funciones que no se declaran en el nivel superior de la secuencia de comandos.
En este ejemplo, la función getBankBalance()
está disponible en el código del cliente. Un usuario que inspecciona tu código fuente puede descubrir su nombre, incluso si no lo llamas. Sin embargo, las funciones deepSecret_()
y obj.objectMethod()
son completamente invisibles para
al cliente.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); } function getBankBalance() { var email = Session.getActiveUser().getEmail() return deepSecret_(email); } function deepSecret_(email) { // Do some secret calculations return email + ' has $1,000,000 in the bank.'; } var obj = { objectMethod: function() { // More secret calculations } };
Index.html
<!DOCTYPE html> <html> <head> <base target="_top"> <script> function onSuccess(balance) { var div = document.getElementById('output'); div.innerHTML = balance; } google.script.run.withSuccessHandler(onSuccess) .getBankBalance(); </script> </head> <body> <div id="output">No result yet...</div> </body> </html>
Cambiando el tamaño de los diálogos en Google Workspace las aplicaciones
Cuadros de diálogo personalizados en Documentos, Hojas de cálculo o
Para cambiar el tamaño de los formularios, llama al
Métodos google.script.host
setWidth(width)
o
setHeight(height)
in
el código del cliente. (Para establecer el tamaño inicial de un diálogo, usa HtmlOutput
métodos
setWidth(width)
y
setHeight(height)
).
Ten en cuenta que los diálogos no se vuelven a centrar en la ventana superior cuando se les cambia el tamaño, y es
No es posible cambiar el tamaño de las barras laterales.
Cierre de diálogos y barras laterales en Google Workspace
Si usas el servicio HTML para mostrar una
cuadro de diálogo o barra lateral en Documentos o Hojas de cálculo de Google
Formularios, no puedes cerrar la interfaz llamando a window.close()
. En cambio,
debe llamar
google.script.host.close()
Para ver un ejemplo, consulta la sección sobre
publicar HTML como una Google Workspace interfaz de usuario.
Cambiando el enfoque del navegador a Google Workspace
Para volver a cambiar el enfoque en el navegador del usuario de un diálogo o barra lateral a la
Solo debes llamar al método en Documentos, Hojas de cálculo o Formularios de Google.
google.script.host.editor.focus()
Este método es particularmente útil en combinación con el
Métodos de servicio de documentos
Document.setCursor(position)
y
Document.setSelection(range)
.