Activadores simples

Los activadores permiten que Apps Script ejecute una función automáticamente cuando un evento determinado, como abrir un documento. Los activadores simples son un conjunto de funciones reservadas integradas en Apps Script, como la función onOpen(e), que se ejecuta cuando un usuario abre un archivo de Documentos, Hojas de cálculo, Presentaciones o Formularios de Google. Los activadores instalables ofrecen más que los activadores simples, pero deben activarse antes de su uso. Para ambos tipos de activadores, Apps Script pasa la función activada una objeto de evento que contiene información sobre el contexto en el que ocurrió el evento.

Cómo comenzar

Para usar un activador simple, simplemente crea una función que use uno de estos nombres de funciones reservadas:

  • onOpen(e) se ejecuta cuando un usuario abre una hoja de cálculo, un documento, una presentación o formulario para el que el usuario tiene permiso para editar.
  • onInstall(e) se ejecuta cuando un usuario instala un Complemento de editor desde Documentos, Hojas de cálculo, Presentaciones o Formularios de Google
  • onEdit(e) se ejecuta cuando un usuario cambia un valor en una hoja de cálculo.
  • onSelectionChange(e) se ejecuta cuando un usuario cambia la selección en una hoja de cálculo.
  • doGet(e) se ejecuta cuando un usuario visita una app web o un programa envía una solicitud HTTP GET a una aplicación web.
  • doPost(e) se ejecuta cuando un programa envía una solicitud POST HTTP a una app web.

El parámetro e en los nombres de las funciones anteriores es un objeto de evento que se pasa al . El objeto contiene información sobre el contexto que provocó el activador se active, pero su uso es opcional.

Restricciones

Debido a que los activadores simples se activan automáticamente, sin pedirle al usuario que están sujetas a varias restricciones:

  • La secuencia de comandos debe estar vinculada a una cuenta de Google un archivo de Hojas de cálculo, Presentaciones, Documentos o Formularios, complemento que extiende uno de esas aplicaciones.
  • No se ejecutan si un archivo se abre en modo de solo lectura (ver o comentar).
  • Las ejecuciones de secuencias de comandos y las solicitudes a la API no provocan la ejecución de activadores. Por ejemplo: llamando a Range.setValue() editar una celda no hace que se ejecute el activador onEdit de la hoja de cálculo.
  • No pueden acceder a los servicios que requieren autorización. Por ejemplo: un activador simple no puede enviar un correo electrónico El servicio de Gmail requiere autorización, pero un activador simple puede traducir una frase con el Servicio lingüístico, que es anónimo.
  • Pueden modificar el archivo al que están vinculados, pero no pueden acceder a otros archivos ya que eso requeriría autorización.
  • Pueden o no determinar la identidad del usuario actual. según una conjunto complejo de restricciones de seguridad.
  • No pueden ejecutarse durante más de 30 segundos.
  • En ciertas circunstancias, Los complementos de editores ejecutan su onOpen(e). y onEdit(e) activadores simples en un modo sin autorización que presenta algunas complicaciones adicionales. Para obtener más información, consulta la guía sobre el ciclo de vida de los complementos.
  • Los activadores simples están sujetos al activador de Apps Script límites de cuota.

Estas restricciones no se aplican a doGet(e) ni a doPost(e).

onOpen(e)

El activador onOpen(e) se ejecuta automáticamente cuando un usuario abre una hoja de cálculo. documento, presentación o formulario para el cual tenga permiso de edición. (El cuando se responde a un formulario, solo cuando se abre para editarla). onOpen(e) se usa con mayor frecuencia para agregar elementos del menú a Hojas de cálculo de Google, Presentaciones, Documentos o Formularios.

triggers/triggers.gs
/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

El activador onInstall(e) se ejecuta automáticamente cuando un usuario instala un Complemento de editor desde Documentos, Hojas de cálculo, Presentaciones o Formularios de Google El activador no se ejecutará cuando un usuario instala el complemento desde la Google Workspace Marketplace sitio web. Ten en cuenta que hay ciertas restricciones sobre lo que puede hacer onInstall(e), obtén más información sobre autorización. El uso más común de onInstall(e) es simplemente llamar a onOpen(e) para agregar menús personalizados. Después de todo, cuando se instala un complemento, el archivo ya está abierto, y, por lo tanto, onOpen(e) no se ejecuta por su cuenta, a menos que se vuelva a abrir el archivo.

triggers/triggers.gs
/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

El activador onEdit(e) se ejecuta automáticamente cuando un usuario cambia el valor de cualquier celda en una hoja de cálculo. La mayoría de los activadores onEdit(e) usan la información del objeto de evento para que responda de forma adecuada. Por ejemplo, la función onEdit(e) a continuación establece un comentario en la celda que registra la última vez que se editó.

triggers/triggers.gs
/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

onSelectionChange(e)

El activador onSelectionChange(e) se ejecuta automáticamente cuando un usuario cambia el selección en una hoja de cálculo. Para activar este activador, debes actualizar el una vez que se agrega el activador y cada vez que se abre la hoja de cálculo.

Si la selección se mueve entre varias celdas en poco tiempo, alguna selección pueden omitirse para reducir la latencia. Por ejemplo, si muchas opciones los cambios se hacen con dos segundos de diferencia, solo el primero y el último los cambios de selección activarán el activador onSelectionChange(e).

En el siguiente ejemplo, Si se selecciona una celda vacía, la función onSelectionChange(e) establece los valores de el fondo a rojo.

triggers/triggers.gs
/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) y doPost(e)

El activador doGet(e) se ejecuta automáticamente cuando un usuario visita un aplicación web o un programa envía una solicitud GET HTTP a una app web. doPost(e) se ejecuta cuando un programa envía una solicitud POST HTTP a un aplicación web. Estos activadores se demuestran más en las guías para aplicaciones web, servicio HTML y Servicio de contenido. Ten en cuenta que doGet(e) y doPost(e) no están sujetas a las restricciones mencionadas anteriormente.

Tipos de activadores disponibles

Si las restricciones para activadores simples impiden que se cumplan según tus necesidades, un activador instalable podría funcionar en su lugar. En la siguiente tabla, se resumen los tipos de activadores que se disponibles para cada tipo de evento. Por ejemplo, Hojas de cálculo, Presentaciones, Formularios de Google y Documentos admite activadores abiertos simples, pero solo es compatible con Hojas de cálculo, Documentos y Formularios. activadores abiertos instalables.

Evento Activadores simples Activadores instalables
Abrir
Hojas de cálculo
Diapositivas
Formularios*
Documentos

function onOpen(e)
Hojas de cálculo
Formularios*
Documentos
Editar
Hojas de cálculo

function onEdit(e)
Hojas de cálculo
Cambio de selección
Hojas de cálculo

function onSelectionChange(e)
Instalar
Hojas de cálculo
Diapositivas
Formularios
Documentos

function onInstall(e)
Cambiar
Hojas de cálculo
Envío de formulario
Hojas de cálculo
Formularios
Basadas en el tiempo (reloj)
Hojas de cálculo
Diapositivas
Formularios
Documentos
Independiente
Obtener
Independiente

function doGet(e)
Publicar
Independiente

function doPost(e)

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