Os acionadores 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 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 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.
Como começar
Para usar um acionador simples, basta criar uma função que use um destes nomes de função reservados:
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 de editor no Documentos, Planilhas, Apresentações ou Formulários Google. onEdit(e)
é executado quando um usuário altera um valor em uma planilha.onSelectionChange(e)
é executado quando um usuário altera a seleção em uma planilha.doGet(e)
é executado quando um usuário visita um app da Web ou um programa envia uma solicitação HTTPGET
a um app da Web.- O
doPost(e)
é executado quando um programa envia uma solicitação HTTPPOST
a 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 causou o disparo do acionador, mas o uso dele é opcional.
Restrições
Como os acionadores simples são disparados automaticamente, sem uma 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 Google. Caso contrário, precisa ser um complemento que estenda 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 gatilhoonEdit
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 Linguagem, 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.
- Eles não podem ser exibidos 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, o que apresenta algumas complicações adicionais. Para mais informações, consulte o guia do ciclo de vida da autorização do complemento. - 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 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 quando ele é aberto para editá-lo. onOpen(e)
é usado com mais frequência para adicionar itens de menu personalizados ao Planilhas, Apresentações, Documentos ou Formulários Google.
onInstall(e)
O gatilho onInstall(e)
é executado automaticamente quando um usuário instala um complemento do Editor no Documentos, Planilhas, Apresentações ou Formulários Google. O acionador não será executado quando um usuário
instalar o complemento pelo
site do
Google Workspace Marketplace. Há algumas 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 que ela 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 depois que o acionador for adicionado e sempre que a planilha for aberta.
Se a seleção se mover entre várias células em um curto período, alguns eventos de alteração de seleção poderão ser ignorados para reduzir a latência. Por exemplo, se muitas alterações de seleção forem feitas em até dois segundos umas das outras, somente a primeira e a última alterações de seleção ativarão 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.
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
a um app da Web. 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 gatilho 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 disponíveis para cada tipo de evento. O Planilhas, o Apresentações, o Formulários e o Documentos, por exemplo, são compatíveis com acionadores simples abertos, mas somente com o Planilhas, o Documentos e o Formulários.
Evento | Acionadores simples | Acionadores instaláveis |
---|---|---|
Abrir |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Editar |
![]()
|
![]() |
Alteração na seleção |
![]()
|
|
Instalar |
![]() ![]() ![]() ![]()
|
|
Mudar |
![]() |
|
Envio de formulário |
![]() ![]() |
|
Baseado no tempo (relógio) |
![]() ![]() ![]() ![]() ![]() ![]() |
|
Get |
![]() ![]()
|
|
Postar |
![]() ![]()
|
* O evento aberto 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.