Gatilhos simples

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Os gatilhos permitem que o Apps Script execute uma função automaticamente quando ocorre um determinado evento, como a abertura de um documento. Gatilhos simples são um conjunto de funções reservadas integrada ao Apps Script, como a função onOpen(e), que é executada quando um usuário abre um arquivo do Documentos, Planilhas, Apresentações ou Formulários Google. Os acionadores instaláveis oferecem mais recursos do que os acionadores simples, mas precisam ser ativados antes do uso. Para ambos os tipos de acionadores, o Apps Script transmite à função acionada um objeto de evento que contém informações sobre o contexto em que o evento ocorreu.

Primeiros passos

Para usar um gatilho simples, basta criar uma função que utilize um destes nomes de função reservada:

  • onOpen(e) é executado quando um usuário abre uma planilha, um documento, uma apresentação ou um formulário que o usuário tem permissão para editar.
  • O onInstall(e) é executado quando um usuário instala um complemento do Editor no Documentos, Planilhas, Apresentações ou Formulários Google.
  • A onEdit(e) é executada quando um usuário altera um valor em uma planilha.
  • A onSelectionChange(e) é executada quando um usuário altera a seleção em uma planilha.
  • A doGet(e) é executada quando um usuário visita um app da Web ou um programa envia uma solicitação HTTP GET para um app da Web.
  • O doPost(e) é executado quando um programa envia uma solicitação POST de HTTP para um app da Web.

O parâmetro e nos nomes de função acima é um objeto de evento que é transmitido para a função. O objeto contém informações sobre o contexto que acionou o disparo do acionador, mas o uso é opcional.

Restrições

Como os acionadores simples são acionados automaticamente, sem solicitar a autorização do usuário, eles estão sujeitos a várias restrições:

  • O script precisa estar vinculado a um arquivo do Planilhas, Apresentações, Documentos ou Formulários do Google. Caso contrário, será um complemento que estende um desses aplicativos.
  • Eles não serão executados se um arquivo for aberto no modo somente leitura (visualização ou comentário).
  • Execuções de script e solicitações de API não fazem com que acionadores sejam executados. Por exemplo, chamar Range.setValue() para editar uma célula não faz com que o acionador onEdit da planilha seja executado.
  • Eles não podem acessar serviços que exigem autorização. Por exemplo, um gatilho simples não pode enviar um e-mail porque o serviço do Gmail requer autorização, mas um acionador simples pode traduzir uma frase com o serviço de idioma, que é anônimo.
  • Eles podem modificar o arquivo ao qual estão vinculados, mas não podem acessar outros arquivos porque isso requer autorização.
  • Eles podem ou não conseguir determinar a identidade do usuário atual, dependendo de um conjunto complexo de restrições de segurança.
  • Eles não podem ser executados por mais de 30 segundos.
  • Em determinadas circunstâncias, os complementos do editor executam os acionadores simples onOpen(e) e onEdit(e) em um modo sem autorização que apresenta algumas complicações adicionais. Para mais informações, consulte o guia do ciclo de vida da autorização dos complementos.
  • Os acionadores simples estão sujeitos aos limites de cota do acionador do Apps Script.

Essas restrições não são válidas para doGet(e) ou doPost(e).

onOpen(e)

O gatilho onOpen(e) é executado automaticamente quando um usuário abre uma planilha, um documento, uma apresentação ou um formulário que ele tem permissão para editar. O acionador não é executado ao responder a um formulário, apenas ao abrir o formulário para editá-lo. onOpen(e) é o mais usado para adicionar itens de menu personalizados ao Planilhas Google, Apresentações, Documentos ou Formulários.

trigger/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)

O acionador onInstall(e) é executado automaticamente quando um usuário instala um complemento do editor no Documentos, Planilhas, Apresentações ou Formulários Google. O gatilho não será executado quando um usuário instalar o complemento pelo site do Google Workspace Marketplace. Existem algumas restrições sobre o que onInstall(e) pode fazer. Saiba mais sobre autorização. O uso mais comum do onInstall(e) é simplesmente chamar onOpen(e) para adicionar menus personalizados. Afinal, quando um complemento é instalado, o arquivo já está aberto e, portanto, onOpen(e) não é executado por conta própria, a menos que o arquivo seja reaberto.

trigger/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)

O gatilho onEdit(e) é executado automaticamente quando um usuário muda o valor de qualquer célula em uma planilha. A maioria dos acionadores onEdit(e) usa as informações no objeto de evento para responder de maneira adequada. Por exemplo, a função onEdit(e) abaixo define um comentário na célula que registra a última vez em que foi editado.

trigger/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)

O gatilho onSelectionChange(e) é executado automaticamente quando um usuário muda a seleção em uma planilha. Para ativar esse acionador, é necessário atualizar a planilha assim que o acionador for adicionado e sempre que a planilha for aberta.

Se a seleção passar de várias células em pouco tempo, alguns eventos de alteração de seleção poderão ser ignorados para reduzir a latência. Por exemplo, se muitas mudanças de seleção forem feitas em até dois segundos entre si, somente a primeira e a última alterações vão selecionar o acionador onSelectionChange(e).

No exemplo abaixo, se uma célula vazia for selecionada, a função onSelectionChange(e) definirá o plano de fundo da célula como vermelho.

trigger/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) e doPost(e)

O gatilho doGet(e) é executado automaticamente quando um usuário visita um app da Web ou um programa envia uma solicitação HTTP GET para um app da Web. O doPost(e) é executado quando um programa envia uma solicitação HTTP POST para um app da Web. Esses acionadores são demonstrados mais nos guias para apps da Web, serviço HTML e serviço de conteúdo. Observe que doGet(e) e doPost(e) não estão sujeitos às restrições listadas acima.

Tipos de gatilhos disponíveis

Se as restrições de acionadores simples impedirem que eles atendam às suas necessidades, um gatilho instalável poderá funcionar. A tabela abaixo resume os tipos de acionadores que estão disponíveis para cada tipo de evento. Por exemplo, o Planilhas, o Apresentações, o Formulários e o Documentos são compatíveis com acionadores abertos simples, mas apenas os Planilhas, Documentos e Formulários são compatíveis com acionadores abertos instaláveis.

Evento Gatilhos simples Gatilhos instaláveis
Aberto
Planilhas
Apresentações
Formulários*
Documentos

function onOpen(e)

Planilhas
Formulários*
Documentos
Editar
Planilhas

function onEdit(e)

Planilhas
Mudança na seleção
Planilhas

function onSelectionChange(e)

Instalar
Planilhas
Apresentações
Formulários
Documentos

function onInstall(e)

Mudar
Planilhas
Envio de formulário
Planilhas
Formulários
Baseado no tempo (relógio)
Planilhas
Apresentações
Formulários
Documentos
Sites
Independente
Get
Sites
Independente

function doGet(e)

Postar
Sites
Independente

function doPost(e)

* O evento de abertura do Formulários Google não ocorre quando um usuário abre um formulário para responder, mas quando um editor abre o formulário para modificá-lo.