Activadores para complementos del editor

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	Documentos Formularios* Hojas de cálculo Presentaciones function onOpen(e)	Documentos Formularios Hojas de cálculo
Instalar El complemento está instalado.	Objeto de 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 de evento onEdit de Hojas de cálculo	Hojas de cálculo function onEdit(e)	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		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		Formularios 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		Documentos Formularios Hojas de cálculo Presentaciones

* 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 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 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 activa onEdit(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.

/**
 * 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.
  }
}

<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 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.