Activadores para complementos del editor

Los activadores de Apps Script hacen que se ejecute una función de secuencia de comandos especificada (la función de activación) cada vez que se produce un evento especificado. Solo ciertos eventos pueden activar los activadores, y cada aplicación de Google Workspace admite un conjunto diferente de eventos.

Cuando se activa un disparador, se crea un objeto de evento. Esta estructura JSON contiene detalles sobre el evento que ocurrió. La información de 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 parámetro a la función de activación. La función de activación es una función de devolución de llamada que debes implementar por tu cuenta para realizar las acciones adecuadas en respuesta al evento. Por ejemplo, en un complemento del Editor, se usa un activador para crear elementos de menú del complemento cuando se abre un documento. En este caso, implementarás la función de activación onOpen(e) para crear los elementos de menú que necesita el complemento, posiblemente usando los datos del objeto de evento.

En esta página, se proporcionan lineamientos para usar activadores en proyectos de complementos del editor.

Tipos de activadores de complementos del editor

Puedes usar la mayoría de los tipos de activadores genéricos disponibles para los proyectos de Apps Script en los 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 extiende.

Nota: A diferencia de los complementos del Editor, los complementos de Google Workspace actualmente no pueden usar activadores genéricos simples o instalables de Apps Script. En cambio, usan activadores diseñados específicamente para los complementos de Google Workspace. Para obtener más información, consulta Activadores de complementos de Google Workspace.

En la siguiente tabla, se muestran los tipos de activadores simples y que se pueden instalar que pueden usar los complementos del Editor, y se proporcionan 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	Documentos Formularios* Hojas de cálculo Presentaciones function onOpen(e)	Documentos Formularios Hojas de cálculo
Instalar Se instaló el complemento.	Objeto del evento onInstall	Documentos Formularios Hojas de cálculo Presentaciones function onInstall(e)
Editar Se cambió el contenido de la celda de la hoja de cálculo.	Objeto del evento onEdit de Hojas de cálculo	Hojas de cálculo function onEdit(e)	Hojas de cálculo
Cambio Se edita o se da formato al contenido de una hoja.	Objeto de evento onChange de Sheets		Hojas de cálculo
Form-submit Se envió un formulario de Google.	Objeto de evento form-submit de Forms Objeto de evento form-submit de Sheets		Formularios Hojas de cálculo
Controlado por tiempo (reloj) El activador se dispara en un momento o intervalo especificados.	Objeto de evento controlado por tiempo		Documentos Formularios Hojas de cálculo Presentaciones

* El evento de apertura de Formularios de Google no se produce cuando un usuario abre un formulario para responderlo, sino cuando un editor lo abre para modificarlo.

Activadores simples 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 evento de activación simple se puede controlar con un activador instalable.

Para agregar un activador simple a un complemento, solo debes 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 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 y, con mayor frecuencia, 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 a onOpen(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 movimientos de celdas, formato ni otros cambios que no alteren los valores de las celdas.

Restricciones

Los activadores simples en los 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 cuando diseñes complementos:

• Los activadores simples no se ejecutan si un archivo se abre en modo de solo lectura (visualización o comentarios). Este comportamiento impide que se completen los menús de tu complemento.
• En ciertas circunstancias, los complementos del Editor ejecutan sus activadores simples onOpen(e) y onEdit(e) 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 requieran autorización, excepto según se describe en el modelo de autorización de complementos.
• Los activadores simples no pueden ejecutarse durante más de 30 segundos. Ten cuidado de minimizar la cantidad de procesamiento que se realiza en una función de activación 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 forma 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 se producen errores, ya que, en la mayoría de los casos, el usuario no puede solucionar el problema. Por este motivo, debes diseñar tu complemento para que controle los errores de forma correcta en nombre del usuario siempre que sea posible.

Los complementos pueden usar los siguientes activadores instalables:

• Los activadores instalables Open se ejecutan cuando un usuario abre un documento o una hoja de cálculo, o cuando se abre un formulario en el editor (pero no cuando se responde el formulario).
• Los activadores instalables de edición se ejecutan cuando un usuario cambia el valor de una celda en una hoja de cálculo. Este activador no se activa en respuesta a cambios de formato o de otro tipo que no alteren los valores de las celdas.
• Los activadores instalables de cambio se ejecutan cuando un usuario realiza cualquier cambio en una hoja de cálculo, incluidas las ediciones de formato y las modificaciones en la hoja de cálculo en sí (como agregar una fila).

• Los activadores instalables Form-submit se ejecutan cuando se envía una respuesta de un formulario de Google.

  Nota: Hay dos versiones de los activadores de envío de formularios, una para Hojas de cálculo (donde se recopilan las respuestas del formulario) y otra para Formularios de Google. El objeto de evento que se pasa a una función de activador de envío de formularios de Hojas de cálculo es más simple y devuelve los valores de respuesta en arrays simples. El objeto de evento que se pasa a una función de activador de envío de formularios de Forms proporciona más información, que se incluye en un objeto FormResponse.

• Activadores basados en el tiempo (también llamados activadores de reloj) se activan en un momento específico o de forma reiterada 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 solicita a los usuarios que vuelvan a autorizar el complemento la próxima vez que lo usen.

Sin embargo, los complementos que usan activadores tienen desafíos especiales de autorización. Imagina un complemento que usa un activador para supervisar los envíos de formularios: un creador de formularios podría autorizar el complemento la primera vez que lo use y, luego, dejar que se ejecute durante meses o años sin volver a abrir el formulario. Si el desarrollador del complemento actualizara el complemento para usar servicios nuevos que requieren 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 en los proyectos regulares de Apps Script, los activadores en los complementos se siguen activando incluso si necesitan una nueva autorización. Sin embargo, la secuencia de comandos seguirá fallando si llega a una línea de código que requiere una autorización que no tiene. Para evitar esta situación, los desarrolladores pueden usar el método ScriptApp.getAuthorizationInfo() para restringir el acceso a partes del código que cambiaron entre las versiones publicadas del complemento.

A continuación, se muestra un ejemplo de la estructura recomendada para usar en las funciones de activación y evitar problemas de autorización. La función de activación 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 con HTML basado en plantillas.

Code.gs

triggers/form/Code.gs

Ver en GitHub

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.html

Ver en GitHub

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Restricciones

Los activadores instalables en 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 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 un activador de edición, aunque 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. Otro usuario con acceso a 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 usan. Es decir, un complemento que se usa en el documento A de Google Docs no puede crear un activador para supervisar cuándo se abre el documento B de Google Docs.
• Los activadores basados en el tiempo no pueden ejecutarse con una frecuencia mayor a 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 arroja una excepción. Depende del desarrollador verificar y controlar los casos de falla correctamente.
• Los activadores de complementos dejan de activarse 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 funcionar)
  • Si el desarrollador anula la publicación del complemento o envía una versión dañada a la tienda de complementos
• Las funciones de activación de complementos se ejecutan hasta que alcanzan código que usa un servicio no autorizado, momento en el que se detienen. Esto solo se aplica si el complemento está publicado. El mismo activador en un proyecto de Apps Script normal o en 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 de los activadores de Apps Script.