Gatilhos simples

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

Como começar

Para usar um gatilho simples, basta criar uma função que use um destes nomes reservados:

• A onOpen(e) é executada 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 nos Documentos, Planilhas, Apresentações ou Formulários Google.
• A função onEdit(e) é executada quando um usuário muda um valor em uma planilha.
• A função onSelectionChange(e) é executada quando um usuário muda a seleção em uma planilha.
• O doGet(e) é executado 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.

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

Restrições

Como gatilhos simples são disparados automaticamente, sem solicitar autorização ao usuário, eles estão sujeitos a várias restrições:

• O script precisa estar vinculado a um arquivo das Planilhas, Apresentações, Documentos ou Formulários Google ou ser um complemento que estenda um desses aplicativos.
• Elas não funcionam quando um arquivo é aberto no modo somente leitura (visualização ou comentário).
• Execuções de script e solicitações de API não causam a execução de acionadores. 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 gatilho 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 exigiria autorização.
• Eles podem ou não determinar a identidade do usuário atual, dependendo de um conjunto complexo de restrições de segurança.
• Elas não podem ser executadas por mais de 30 segundos.
• Em determinadas circunstâncias, os complementos do editor executam os gatilhos simples onOpen(e) e onEdit(e) em um modo sem autorização que apresenta mais algumas complicações. Para mais informações, consulte o guia para o ciclo de vida de autorização de complementos.
• Os acionadores simples estão sujeitos aos limites de cota de acionadores do Apps Script.

Essas restrições não se aplicam a doGet(e) ou doPost(e).

onOpen(e)

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

/**
 * 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 nos Documentos, Planilhas, Apresentações ou Formulários Google. O acionador não será executado quando um usuário instalar o complemento no site do Google Workspace Marketplace. Existem algumas restrições sobre o que onInstall(e) pode fazer. Saiba mais sobre a autorização. O uso mais comum de 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 será executado por conta própria, a menos que o arquivo seja reaberto.

/**
 * 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 acionador onEdit(e) é executado automaticamente quando um usuário altera 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 ela foi editada.

/**
 * 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 acionador onSelectionChange(e) é executado automaticamente quando um usuário muda a seleção em uma planilha. Para ativar esse acionador, atualize a planilha sempre que o acionador for adicionado e toda vez que a planilha for aberta.

Se a seleção se mover entre várias células em um curto período, alguns eventos de mudança de seleção poderão ser ignorados para reduzir a latência. Por exemplo, se muitas mudanças de seleção forem feitas dentro de dois segundos uma da outra, apenas a primeira e a última mudanças vão ativar o gatilho 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.

/**
 * 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 GET HTTP a um app da Web. O doPost(e) é executado quando um programa envia uma solicitação HTTP POST a um app da Web. Esses gatilhos são demonstrados em mais detalhes nos guias sobre 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 acionadores disponíveis

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

Evento	Gatilhos simples	Acionadores instaláveis
Abrir	function onOpen(e)
Editar	function onEdit(e)
Mudança na seleção	function onSelectionChange(e)
Instalar	function onInstall(e)
Mudar
Envio de formulário
Orientado por tempo (relógio)
Get	function doGet(e)
Postagem	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.