Gatilhos simples

Com os gatilhos, o Google Apps Script executa uma função automaticamente quando um determinado evento ocorre, como abrir um documento. Os 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, das Planilhas, das Apresentações ou dos Formulários Google. Os gatilhos instaláveis oferecem mais recursos do que os gatilhos 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 que contém informações sobre o contexto em que o evento ocorreu.

Para informações sobre como usar gatilhos em projetos de complementos do Google Workspace, consulte Gatilhos para complementos do Google Workspace.

Primeiros passos

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

• O onOpen(e) é executado quando um usuário abre uma planilha, um documento, uma apresentação ou um formulário que ele tem permissão para editar.
• onInstall(e) é executado quando um usuário instala um complemento do editor nos Documentos, Planilhas, Apresentações ou Formulários Google.
• onEdit(e) é executado quando um usuário muda um valor em uma planilha.
• onSelectionChange(e) é executado 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 a 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 acionamento, mas o uso dele é opcional.

Restrições

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

• O script precisa estar vinculado a um arquivo do Google Planilhas, Apresentações, Documentos ou Formulários ou ser um complemento que estende um desses aplicativos.
• Elas não são executadas se um arquivo for aberto no modo somente leitura (visualização ou comentário).
• Execuções de scripts e solicitações de API não fazem com que os acionadores sejam executados. Por exemplo, chamar Range.setValue() para editar uma célula não faz com que o gatilho onEdit da planilha seja executado.
• Não é possível 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 exige autorização, mas ele pode traduzir uma frase com o serviço de linguagem, que é anônimo.
• Eles podem modificar o arquivo a que estão vinculados, mas não podem acessar outros arquivos porque isso exigiria 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 durar mais de 30 segundos.
• Em certas 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 sobre o ciclo de vida da autorização de complementos.
• Os acionadores simples estão sujeitos aos limites de cota dos acionadores do Apps Script.

Essas restrições não se aplicam a 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 gatilho não é executado ao responder a um formulário, apenas ao abrir o formulário para edição. O onOpen(e) é usado com mais frequência para adicionar itens de menu personalizados às Planilhas Google, 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 gatilho onInstall(e) é executado automaticamente quando um usuário instala um complemento do editor nos apps Documentos, Planilhas, Apresentações ou Formulários Google. O gatilho não é executado quando um usuário instala o complemento no site do Google Workspace Marketplace. O uso mais comum de onInstall(e) é chamar onOpen(e) para adicionar menus personalizados. Depois que um complemento é instalado, o arquivo já está aberto. Assim, onOpen(e) não é executado por conta própria, a menos que o arquivo seja reaberto. Há algumas restrições sobre o que o onInstall(e) pode fazer. Saiba mais sobre autorização.

/**
 * 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 de onEdit(e) usa as informações no objeto de evento para responder adequadamente. Por exemplo, a função onEdit(e) abaixo define um comentário na célula que registra a última vez 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()}`);
}

O acionador onEdit() só enfileira até dois eventos de acionamento.

onSelectionChange(e)

O gatilho onSelectionChange(e) é executado automaticamente quando um usuário muda a seleção em uma planilha. Para ativar esse acionador, atualize a planilha depois que ele for adicionado e sempre que ela 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 em um intervalo de dois segundos, apenas a primeira e a última vão ativar o gatilho onSelectionChange(e).

No exemplo a seguir, se uma célula vazia for selecionada, a função onSelectionChange(e) vai 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 web app ou um programa envia uma solicitação HTTP GET para um web app. O doPost(e) é executado quando um programa envia uma solicitação HTTP POST para um web app. Esses gatilhos são demonstrados mais nos guias de web apps, serviço HTML e serviço de conteúdo. 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 pode funcionar. A tabela abaixo resume os tipos de gatilhos disponíveis para cada tipo de evento. Por exemplo, o Google Planilhas, Apresentações, Formulários e Documentos são compatíveis com gatilhos de abertura simples, mas apenas o Planilhas, Documentos e Formulários são compatíveis com gatilhos de abertura instaláveis.

Evento	Gatilhos simples	Gatilhos instaláveis
Abrir	function onOpen(e)
Editar	function onEdit(e)
Mudança de seleção	function onSelectionChange(e)
Instalar	function onInstall(e)
Mudar
Envio de formulário
Baseado no tempo (relógio)
Get	function doGet(e)
Postar	function doPost(e)

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