Com os acionadores, o Apps Script executa uma função automaticamente quando um determinado evento,
como a abertura de um documento, ocorre. 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 apps Documentos, Planilhas, Apresentações ou Formulários Google.
Os gatilhos instaláveis oferecem mais
recursos do que os acionáveis, mas precisam ser ativados antes do uso. Para os dois tipos de acionador, 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 use um desses 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 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. 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 quando um programa envia uma solicitação HTTPGET
para um app da Web. - O
doPost(e)
é executado quando um programa envia uma solicitação HTTPPOST
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 os acionadores 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 das Planilhas, Apresentações, Documentos ou Formulários Google ou ser um complemento que amplia um desses aplicativos.
- Elas não são executadas se um arquivo for aberto no modo somente leitura (visualização ou comentário).
- As execuções de script e as 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 gatilhoonEdit
da planilha seja executado. - Eles não podem acessar serviços que exigem autorização. Por exemplo, um acionador simples não pode enviar um e-mail porque o serviço do Gmail exige autorização, mas um acionador 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 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)
eonEdit(e)
em um modo sem autorização que apresenta outras complicações. 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 do acionador 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,
um documento, uma apresentação ou um formulário que 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. O onOpen(e)
é mais usado para adicionar itens de menu personalizados às Planilhas, Apresentações, Documentos ou Formulários Google.
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. Há
certas restrições sobre o que 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 por conta própria, a menos que o arquivo seja reaberto.
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 editada.
onSelectionChange(e)
O gatilho onSelectionChange(e)
é executado automaticamente quando um usuário altera a
seleção em uma planilha. Para ativar esse acionador, atualize a planilha sempre que o acionador for adicionado e toda a planilha for aberta.
Se a seleção for movida 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 até dois segundos, apenas as primeiras e as últimas mudanças de seleção vão acionar o acionador onSelectionChange(e)
.
No exemplo abaixo,
se uma célula vazia for selecionada, a função onSelectionChange(e)
vai definir o plano de fundo
da célula como vermelho.
doGet(e)
e doPost(e)
O acionador 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 nos guias para
apps da Web, serviço de 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 acionadores 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 |
|
|
Editar |
|
|
Mudança na seleção |
|
|
Instalar |
|
|
Mudar |
|
|
Envio de formulário |
|
|
Baseado no tempo (relógio) |
|
|
Get |
|
|
Postar |
|
* O evento de abertura do Google Forms não ocorre quando um usuário abre um formulário para responder, mas quando um editor abre o formulário para modificá-lo.