Los activadores de Apps Script hacen que se ejecute una función de secuencia de comandos específica (la función activadora) cada vez que se produce un evento especificado. Solo ciertos eventos pueden activar activadores y cada aplicación de Google Workspace admite un conjunto diferente de eventos.
Cuando se activa un activador, se crea un objeto de evento. Esta estructura JSON contiene detalles sobre el evento que ocurrió. La información en la estructura del objeto de evento se organiza de manera diferente según el tipo de activador.
Una vez que se crea el objeto de evento, Apps Script lo pasa como un parámetro a la función activador. La función de activación es una función de devolución de llamada que debes implementar, a fin de realizar las acciones adecuadas para responder al evento. Por ejemplo, en un complemento de editor, se usa un activador para crear elementos de menú de complementos cuando se abre un documento. En este caso, debes implementar en la función activadora onOpen(e)
para crear los elementos de menú que el complemento necesita, posiblemente con los datos del objeto de evento.
En esta página, se proporcionan lineamientos sobre el uso de activadores en proyectos de complementos del editor.
Tipos de activadores del complemento de editor
Puedes usar la mayoría de los tipos de activadores genéricos disponibles para proyectos de Apps Script en complementos del editor, incluidos los activadores simples y la mayoría de los activadores instalables. El conjunto exacto de tipos de activadores disponibles depende de la aplicación que se extienda.
En la siguiente tabla, se muestran los tipos de activadores simples e instalables que pueden usar los complementos de editor, y se proporcionan vínculos a los objetos de evento correspondientes:
Evento | Objeto de evento | Activadores simples | Activadores instalables |
---|---|---|---|
Abrir Se abre un archivo de editor. |
Objeto de evento onOpen de Documentos Objeto de evento de Formularios abierto Objeto de evento de Hojas de cálculo de Open Objeto de evento de Presentaciones onOpen |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Instalar El complemento está instalado. |
Objeto de evento onInstall |
![]() ![]() ![]() ![]()
|
|
Editar Se cambió el contenido de la celda de la hoja de cálculo. |
Objeto de evento onEdit de Hojas de cálculo |
![]()
|
![]() |
Cambiar El contenido de una hoja se edita o formatea. |
Objeto de evento onChange de Hojas de cálculo |
![]() |
|
Envío de formulario Se envía un formulario de Google. |
Objeto de evento de envío de formulario de formularios Objeto de evento de envío de formulario de Hojas de cálculo |
![]() ![]() |
|
Basado en el tiempo (reloj) El activador se activa en un intervalo o hora especificados. |
Objeto de evento basado en el tiempo |
![]() ![]() ![]() ![]() |
* El evento abierto para Formularios de Google no se produce cuando un usuario abre un formulario para responder, sino cuando un editor abre el formulario para modificarlo.
Activadores sencillos en complementos
Los activadores simples usan un conjunto de nombres de funciones reservados, no pueden usar servicios que requieren autorización y se habilitan automáticamente para su uso. En algunos casos, un activador instalable puede controlar un evento activador sencillo.
Puedes agregar un activador simple a un complemento mediante la implementación de una función con uno de los siguientes nombres reservados:
onOpen(e)
se ejecuta cuando un usuario abre un documento, una hoja de cálculo o una presentación.onOpen(e)
también se puede ejecutar cuando se abre un formulario en el editor (pero no cuando se responde al formulario). Solo se ejecuta si el usuario tiene permiso para editar el archivo en cuestión. Por lo general, se usa para crear elementos de menú.onInstall(e)
se ejecuta cuando un usuario instala un complemento. Por lo general,onInstall(e)
solo se usa para llamar aonOpen(e)
. Esto garantiza que los menús del complemento aparezcan inmediatamente después de la instalación sin necesidad de que el usuario actualice la página.onEdit(e)
se ejecuta cuando un usuario cambia el valor de una celda en una hoja de cálculo. Este activador no se activa en respuesta a los movimientos de la celda, el formato o demás cambios que no alteren los valores de la celda.
Restricciones
Los activadores simples en complementos están sujetos a las mismas restricciones que rigen los activadores simples en otros tipos de proyectos de Apps Script. Ten en cuenta estas restricciones en particular al diseñar complementos:
- Los activadores simples no se ejecutan si un archivo está abierto en modo de solo lectura (ver o comentar). Este comportamiento evita que se propaguen los menús de complementos.
- En ciertas circunstancias, los complementos de editor ejecutan sus activadores
onOpen(e)
yonEdit(e)
simples en un modo sin autorización. Este modo presenta algunas complicaciones adicionales, como se describe en el modelo de autorización de complementos. - Los activadores simples no pueden usar servicios ni realizar otras acciones que requieren autorización, excepto como se describe en el modelo de autorización de complementos.
- Los activadores simples no pueden ejecutarse durante más de 30 segundos. Asegúrate de minimizar la cantidad de procesamiento que se realiza en una función de activador simple.
- Los activadores simples están sujetos a los límites de cuota de los activadores de Apps Script.
Activadores instalables en complementos
Los complementos pueden crear y modificar de manera programática activadores instalables con el servicio Script
de Apps Script. Los activadores instalables de complementos no se pueden crear de forma manual. A diferencia de los activadores simples, los activadores instalables pueden usar servicios que requieren autorización.
Los activadores instalables en los complementos no envían correos electrónicos de error al usuario cuando encuentran errores, ya que, en la mayoría de los casos, un usuario no puede solucionar el problema. Debido a esto, debes diseñar tu complemento para manejar correctamente los errores en nombre del usuario siempre que sea posible.
Los complementos pueden usar los siguientes activadores instalables:
- Los activadores instalables abiertos se ejecutan cuando un usuario abre un documento, una hoja de cálculo o un formulario abierto en el editor (pero no cuando se responde al formulario).
- Editar los activadores instalables se ejecutan cuando un usuario cambia el valor de una celda en una hoja de cálculo. Este activador no se activa en respuesta al formato o a otros cambios que no alteren los valores de las celdas.
- Los activadores instalables se ejecutan cuando un usuario realiza un cambio en una hoja de cálculo, incluidas las modificaciones de formato y las modificaciones de la propia hoja de cálculo (como agregar una fila).
Los activadores instalables de Form-submit se ejecutan cuando se envía una respuesta de formulario de Google.
Los activadores basados en el tiempo (también llamados activadores de reloj) se activan a una hora específica o reiteradamente en un intervalo regular.
Autoriza los activadores instalables
Por lo general, si un desarrollador actualiza un complemento para usar servicios nuevos que requieren autorización adicional, se les solicita a los usuarios que vuelvan a autorizar el complemento la próxima vez que lo usen.
Sin embargo, los complementos que usan activadores se encuentran con desafíos de autorización especiales. Imagina un complemento que usa un activador para supervisar los envíos de formularios: un creador de formularios puede autorizar el complemento la primera vez que lo usa y, luego, dejar que se ejecute por meses o años sin tener que volver a abrir el formulario. Si el desarrollador del complemento actualizara el complemento para usar servicios nuevos que requieran autorización adicional, el creador del formulario nunca vería el diálogo de reautorización porque nunca volvió a abrir el formulario, y el complemento dejaría de funcionar.
A diferencia de los activadores de los proyectos normales de Apps Script, los activadores en los complementos se siguen activando, incluso si necesitan una nueva autorización. Sin embargo, la secuencia de comandos falla si llega a una línea de código que requiere autorización. Para evitar esta situación, los desarrolladores pueden usar el método ScriptApp.getAuthorizationInfo()
a fin de controlar el acceso a partes de código que cambiaron entre las versiones publicadas del complemento.
A continuación, se muestra un ejemplo de la estructura recomendada para usar en funciones de activación a fin de evitar errores de autorización. La función de activador de ejemplo responde a un evento de envío de formulario dentro de un complemento de Hojas de cálculo de Google y, si se requiere una nueva autorización, envía al usuario del complemento un correo electrónico de alerta mediante HTML con plantilla.
Code.gs
authorizationemail.html
Restricciones
Los activadores instalables en los complementos están sujetos a las mismas restricciones que rigen los activadores instalables en otros tipos de proyectos de Apps Script.
Además de estas restricciones, se aplican varias restricciones a los activadores instalables específicamente en los complementos:
- Cada complemento solo puede tener un activador de cada tipo, por usuario y por documento. Por ejemplo, en una hoja de cálculo determinada, un usuario determinado solo puede tener un activador de edición, aunque el usuario también podría tener un activador de envío de formulario o un activador basado en el tiempo en la misma hoja de cálculo. Un usuario diferente con acceso a la misma hoja de cálculo podría tener su propio conjunto de activadores independiente.
- Los complementos solo pueden crear activadores para el archivo en el que se usa el complemento. Es decir, un complemento que se usa en el Documento de Google A no puede crear un activador para supervisar cuando se abra el Documento de Google B.
- Los activadores basados en el tiempo no se pueden ejecutar más de una vez por hora.
- Los complementos no envían automáticamente un correo electrónico al usuario cuando el código que ejecuta un activador instalable genera una excepción. Depende del desarrollador verificar y manejar los casos de fallas con facilidad.
- Los activadores de complementos se desactivan en cualquiera de las siguientes situaciones:
- Si el usuario desinstala el complemento,
- Si el complemento está inhabilitado en un documento (si se vuelve a habilitar, el activador vuelve a estar en funcionamiento)
- Si el desarrollador anula la publicación del complemento o envía una versión con errores a la tienda de complementos
- Las funciones del activador de complementos se ejecutan hasta que alcanzan un código que usa un servicio no autorizado, momento en el que se detienen. Esto es así solo si se publica el complemento. El mismo activador en un proyecto normal de Apps Script o un complemento no publicado no se ejecuta en absoluto si alguna parte de la secuencia de comandos necesita autorización.
- Los activadores instalables están sujetos a los límites de cuota del activador de Apps Script.