Gatilhos simples

Os gatilhos permitem que o Apps Script execute uma função automaticamente quando um determinado evento, como abrir um documento, ocorre. 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 apps Documentos, Planilhas, Apresentações ou Formulários Google. Os acionadores instaláveis oferecem mais do que os gatilhos simples, mas precisam ser ativados antes do uso. Para ambos tipos de acionador, o Apps Script transmite à função acionada uma 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 use uma dessas nomes de funções reservados:

• A onOpen(e) é executada quando um usuário abre uma planilha, um documento, uma apresentação ou formulário que o usuário tem permissão para editar.
• O onInstall(e) é executado quando um usuário instala um complemento do Editor Documentos, Planilhas, Apresentações ou Formulários Google.
• onEdit(e) é executado quando um usuário altera um valor em uma planilha.
• A 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 é uma objeto de evento transmitido à função. O objeto contém informações sobre o contexto que causou a para disparar, mas usá-lo é opcional.

Restrições

Porque acionadores simples são disparados automaticamente, sem pedir ao usuário autorização, eles estão sujeitos a diversas restrições:

• O script precisa estar vinculado a um Planilhas, Apresentações, Documentos ou Formulários, ou ainda ser um complemento que estende uma das esses aplicativos.
• Eles não serão executados se um arquivo for aberto no modo somente leitura (visualização ou comentário).
• As execuções de script e as solicitações da API não fazem com que os gatilhos sejam executados. Por exemplo: Ligando para 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 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 a que 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 conjunto complexo de restrições de segurança.
• Eles não podem ser executados por mais de 30 segundos.
• Em certas circunstâncias, Os Complementos do Editor executam onOpen(e). e onEdit(e) gatilhos simples em um modo sem autorização que apresenta com algumas complicações adicionais. Para mais informações, consulte a guia do ciclo de vida da autorização de complementos.
• Acionadores simples estão sujeitos ao acionador do Apps Script limites de cota.

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. documento, apresentação ou formulário que eles têm permissão para editar. O não é executado ao responder a um formulário, somente ao abrir o formulário para editá-la. O onOpen(e) é usado com mais frequência para adicionar anúncios itens de menu para o Planilhas, Apresentações, Documentos ou Formulários.

/**
 * 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 Documentos, Planilhas, Apresentações ou Formulários Google. O gatilho não será executado quando um usuário instala o complemento pelo Google Workspace Marketplace site. Observe que há determinadas restrições sobre o que o onInstall(e) pode fazer. Saiba mais sobre 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, o onOpen(e) não é executado sozinho, 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 gatilho onEdit(e) é executado automaticamente quando um usuário altera o valor de qualquer célula em uma planilha. A maioria dos gatilhos 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 em que foi editado.

/**
 * 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 altera o seleção em uma planilha. Para ativar esse gatilho, é necessário atualizar o planilha assim 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, parte da seleção eventos de alteração podem ser ignorados para reduzir a latência. Por exemplo, se muitas seleções as alterações são feitas com pelo menos dois segundos de diferença, somente a primeira e a última mudanças na seleção vão ativar o acionador onSelectionChange(e).

No exemplo abaixo, se uma célula vazia for selecionada, a função onSelectionChange(e) definirá o valor para 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 acionador doGet(e) é executado automaticamente quando um usuário acessa um um web app ou um programa envia uma solicitação HTTP GET. para um app da Web. doPost(e) é executado quando um programa envia uma solicitação HTTP POST para um app da Web. Esses gatilhos 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 aos acionadores simples impedirem que às suas necessidades, um gatilho instalável pode funcionar. A tabela abaixo resume os tipos de gatilhos disponíveis para cada tipo de evento. Por exemplo, os apps Planilhas, Apresentações, Formulários e Todos os Documentos são compatíveis com gatilhos abertos simples, mas apenas os apps Planilhas, Documentos e Formulários são compatíveis com esses arquivos. e gatilhos abertos instaláveis.

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

* O evento de abertura dos 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.