Los activadores de Apps Script generan una secuencia de comandos especificada función (la función de activador) para que se ejecute cada vez que un evento especificado de que ocurra. Solo algunos eventos pueden hacer que se activen los activadores La 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 se produjo. La información del evento de objetos está organizada de manera diferente según el tipo de activador.
Una vez que se crea el objeto de evento, Apps Script lo pasa como parámetro al objeto
función de activación. La función trigger es una función de devolución de llamada que debes
implementar por tu cuenta, tomar las medidas adecuadas para responder al
para cada evento. Por ejemplo, en un complemento de editor, un activador
se usa para crear elementos del menú de complementos cuando se abre un documento. En este caso,
implementar en la función de activador onOpen(e)
para crear los elementos de menú del complemento
y las necesidades de la organización, y usar los datos en el objeto de evento.
En esta página, se brindan lineamientos sobre el uso de activadores Editor proyectos complementarios.
Tipos de activadores para el complemento del editor
Puedes usar la mayoría de los tipos de activadores genéricos disponibles para los proyectos de Apps Script. en complementos de Editor, incluidos los activadores simples y la mayoría de los activadores instalables. El 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 Los complementos de Editor pueden usar y proporcionar vínculos a los objetos de eventos correspondientes:
Evento | Objeto de evento | Activadores simples | Activadores instalables |
---|---|---|---|
Abrir Se abre un archivo del editor. |
Objeto de evento onOpen de Documentos Objeto de evento onOpen de Formularios Objeto de evento onOpen de Hojas de cálculo Objeto de evento onOpen de Presentaciones |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
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 |
![]()
|
![]() |
Cambio El contenido de una hoja está editado o se le da formato. |
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 momento o intervalo específico. |
Objeto de evento basado en el tiempo |
![]() ![]() ![]() ![]() |
* El evento abierto de Formularios de Google no tiene lugar cuando un usuario abre un formulario para responder, sino cuando un editor abra el formulario para modificarlo.
Activadores simples en complementos
Los activadores simples usan un conjunto de las funciones, no puedes usar servicios que requieran autorización y se habilitar automáticamente para su uso. En algunos casos, un evento activador simple ser manejadas por un activador instalable en su lugar.
Puedes agregar un activador simple a un complemento con solo implementar 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 presentación.onOpen(e)
también se puede ejecutar cuando se abre un formulario en el editor (pero no al responder el formulario). Solo se ejecuta si el usuario tiene permiso para editar el archivo en cuestión y, a menudo, se usa para crear elementos del 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 de complementos aparezcan inmediatamente después de la instalación sin que el usuario tenga que actualizar 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, el formateo o el uso de celdas. otros cambios que no alteran los valores de las celdas.
Restricciones
Los activadores simples de los complementos están sujetos a la misma restricciones que rigen las relaciones activadores en otros tipos de proyectos de Apps Script. Presta mucha atención restricciones en el diseño de complementos:
- Los activadores simples no se ejecutan si un archivo se abre en modo de solo lectura (ver o de comentarios). Este comportamiento evita que se propaguen los menús de tus complementos.
- En determinadas circunstancias, los complementos de editor ejecutan sus
onOpen(e)
y Se activaonEdit(e)
simple 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 tomar otras acciones que requieran autorización, excepto que descritos en las modelo de autorización de complementos.
- Los activadores simples no se pueden ejecutar durante más de 30 segundos. Asegúrate de minimizar la cantidad de procesamiento realizado en una función de activación simple.
- Los activadores simples están sujetos al activador de Apps Script límites de cuota.
Activadores instalables en complementos
Los complementos pueden
crear y modificar de manera programática activadores instalables
con el servicio Script
de Apps Script. complemento
pero no se pueden crear manualmente activadores instalables. A diferencia de los activadores simples,
Los activadores instalables pueden usar servicios que requieren autorización.
Los activadores instalables de los complementos no envían correos electrónicos de error al usuario cuando encuentra errores, ya que en la mayoría de los casos un usuario no puede para abordar el problema. Por este motivo, debes diseñar tu complemento para manejar los errores de forma correcta en nombre del usuario siempre que sea posible.
Los complementos pueden usar los siguientes activadores instalables:
- Los activadores Abrir instalables se ejecutan cuando un usuario abre un documento. o cuando se abre un formulario en el editor (pero no al responder al formulario).
- Los activadores instalables Editar se ejecutan cuando un usuario cambia el valor de una celda en una en una hoja de cálculo. Este activador no se activa en respuesta al formato o a otras cambios que no alteran los valores de las celdas.
- Los activadores instalables Change se ejecutan cuando un usuario realiza cualquier cambio en una en la hoja de cálculo, incluidas las ediciones de formato y las modificaciones de la hoja de cálculo a sí mismo (como agregar una fila).
Los activadores instalables que envían formularios se ejecutan cuando una respuesta de Formularios de Google enviados.
Activadores basados en el tiempo (también llamados desencadenantes de reloj) se activan a una hora específica o de forma repetida en un en un intervalo de tiempo regular.
Autoriza activadores instalables
Normalmente, si un desarrollador actualiza un complemento para usar servicios nuevos que requieren autorización adicional, se les solicitará a los usuarios que vuelvan a autorizar el complemento la próxima cada vez que lo usan.
Sin embargo, los complementos que usan activadores encuentran desafíos de autorización especiales. Imagina un complemento que usa un activador para supervisar los envíos de formularios: un formulario el creador puede autorizar el complemento la primera vez que lo usa y, luego, dejarlo en se publica durante meses o años sin volver a abrir el formulario. Si el desarrollador del complemento actualizara el complemento para usar nuevos servicios que requieren autorización adicional, el creador del formulario nunca verá el en el diálogo de nueva autorización porque nunca reabrieron el formulario, y el complemento dejarían de funcionar.
A diferencia de los activadores en los proyectos normales de Apps Script, los activadores en
los complementos se siguen activando incluso si se necesita volver a autorizarlo. Sin embargo, el guion
falla si llega a una línea de código que requiere autorización de la secuencia de comandos
que no contiene. Para evitar esta situación, los desarrolladores pueden usar el método
ScriptApp.getAuthorizationInfo()
para restringir el acceso a partes del código que han cambiado entre versiones publicadas del
el complemento.
A continuación, se muestra un ejemplo de la estructura recomendada para usar en las funciones de activación para evitar errores de autorización. La función de activador de ejemplo responde a un un evento de envío de formulario en un complemento de Hojas de cálculo de Google y, en caso de que se deba volver a autorizar obligatorio, envía al usuario del complemento un correo electrónico de alerta mediante HTML con plantilla.
Code.gs
authorizationemail.html
Restricciones
Los activadores instalables de 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 activadores en complementos específicamente:
- 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 una edición de envío de formulario, aunque el usuario también podría tener un activador de envío de formulario activador controlado por el tiempo en la misma hoja de cálculo. Otro usuario con acceso en la misma hoja de cálculo podría tener su propio conjunto de activadores.
- 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 A de Google 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 con una frecuencia mayor a una por hora.
- Los complementos no envían automáticamente un correo electrónico al usuario cuando se ejecuta un código con un y el activador instalable arroja una excepción. Depende del desarrollador verificar y manejar los casos de falla con facilidad.
- Los activadores de complementos dejan de activarse en cualquiera de las siguientes situaciones:
- Si el usuario desinstala el complemento, haz lo siguiente:
- Si el complemento está inhabilitado en un documento (si se vuelve a habilitar, el activador vuelve a funcionar) o
- Si el desarrollador anula la publicación del complemento o envía una versión dañada al en la tienda de complementos.
- Las funciones de activación del complemento se ejecutan hasta que alcanzan el código que usa un servicio no autorizado y, en ese momento, se detiene. 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 ejecutan si alguna parte de la secuencia de comandos necesita autorización.
- Los activadores instalables están sujetos al activador de Apps Script límites de cuota.