Activadores sencillos

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Los activadores permiten que Apps Script ejecute una función automáticamente cuando se produce 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 capacidades que los activadores simples, pero deben activarse antes de usarlos. Para ambos tipos de activadores, Apps Script pasa a la función activada un 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 reservados:

  • onOpen(e) se ejecuta cuando un usuario abre una hoja de cálculo, un documento, una presentación o un formulario 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 aplicación web o un programa que envía una solicitud HTTP GET a una aplicación web.
  • doPost(e) se ejecuta cuando un programa envía una solicitud HTTP POST a una aplicación web.

El parámetro e en los nombres de función anteriores es un objeto de evento que se pasa a la función. El objeto contiene información sobre el contexto que causó la activación del activador, pero su uso es opcional.

Restricciones

Debido a que los activadores simples se activan de forma automática, sin solicitarle autorización al usuario, están sujetos a varias restricciones:

  • La secuencia de comandos debe estar vinculada a un archivo de Hojas de cálculo, Presentaciones, Documentos o Formularios de Google, o bien ser un complemento que extienda una de esas aplicaciones.
  • No se ejecutan si un archivo está abierto 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 los activadores. Por ejemplo, llamar a Range.setValue() para 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 porque el servicio de Gmail requiere autorización, pero un activador simple puede traducir una frase con el servicio de lenguaje, que es anónimo.
  • Pueden modificar el archivo al que están vinculadas, pero no pueden acceder a otros archivos, ya que esto requeriría autorización.
  • Pueden o no determinar la identidad del usuario actual, en función de un conjunto complejo de restricciones de seguridad.
  • No pueden ejecutarse por más de 30 segundos.
  • En ciertas circunstancias, los complementos de editor ejecutan sus activadores simples onOpen(e) y onEdit(e) en un modo sin autorización que presenta algunas complicaciones adicionales. Para obtener más información, consulta la guía del ciclo de vida de la autorización de complementos.
  • Los activadores simples están sujetos a los límites de cuota de los activadores de Apps Script.

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

onOpen(e)

El activador onOpen(e) se ejecuta de forma automática cuando un usuario abre una hoja de cálculo, un documento, una presentación o un formulario para el que tiene permiso de edición. (El activador no se ejecuta cuando se responde un formulario, solo cuando se abre el formulario para editarlo). onOpen(e) se usa con mayor frecuencia para agregar elementos de menú personalizados a Hojas de cálculo, Presentaciones, Documentos o Formularios de Google.

activadores/activadores.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 de forma automática 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 instale el complemento desde el sitio web de Google Workspace Marketplace. Ten en cuenta que existen ciertas restricciones sobre lo que puede hacer onInstall(e). Obtén más información sobre la 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 el archivo se vuelva a abrir.

activadores/activadores.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 de forma automática cuando un usuario cambia el valor de cualquier celda de una hoja de cálculo. La mayoría de los activadores onEdit(e) usan la información del objeto de evento para responder de manera adecuada. Por ejemplo, la siguiente función onEdit(e) establece un comentario en la celda que registra la última vez que se editó.

activadores/activadores.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 de forma automática cuando un usuario cambia la selección en una hoja de cálculo. Para activar este activador, debes actualizar la hoja de cálculo 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, es posible que se omitan algunos eventos de cambio de selección para reducir la latencia. Por ejemplo, si muchos cambios de selección se realizan dentro de los dos segundos posteriores, solo el primer y último cambio 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 el fondo de la celda en rojo.

activadores/activadores.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 una aplicación 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 aplicación web. Estos activadores se demuestran más en las guías sobre aplicaciones web, servicio HTML y servicio de contenido. Ten en cuenta que doGet(e) y doPost(e) no están sujetos a las restricciones mencionadas anteriormente.

Tipos de activadores disponibles

Si las restricciones en los activadores simples evitan que cumplan con tus necesidades, es posible que un activador instalable funcione. En la siguiente tabla, se resumen los tipos de activadores disponibles para cada tipo de evento. Por ejemplo, Hojas de cálculo, Presentaciones, Formularios y Documentos de Google admiten activadores simples y abiertos, pero solo Hojas de cálculo, Documentos y Formularios admiten activadores abiertos instalables.

Evento Activadores sencillos Activadores instalables
Abierto
Hojas de cálculo
Presentaciones
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
Presentaciones
Formularios
Documentos

function onInstall(e)

Cambiar
Hojas de cálculo
Envío de formulario
Hojas de cálculo
Formularios
En función del tiempo (reloj)
Hojas de cálculo
Presentaciones
Formularios
Documentos
Sites
Independiente
Obtener
Sites
Independiente

function doGet(e)

Publicación
Sites
Independiente

function doPost(e)

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