Gatilhos para complementos do editor

Os acionadores do Apps Script fazem com que uma função de script especificada (a função de acionamento) seja executada sempre que um evento especificado ocorre. Somente alguns eventos podem acionar gatilhos, e cada aplicativo do Google Workspace é compatível com um conjunto diferente de eventos.

Quando um gatilho é acionado, um objeto de evento é criado. Essa estrutura JSON contém detalhes sobre o evento que ocorreu. As informações na estrutura do objeto de evento são organizadas de maneira diferente com base no tipo de gatilho.

Depois que o objeto de evento é criado, o Apps Script o transmite como um parâmetro para a função de acionamento. A função de gatilho é um callback que você precisa implementar para realizar as ações adequadas em resposta ao evento. Por exemplo, em um complemento do Editor, um gatilho é usado para criar itens de menu do complemento quando um documento é aberto. Nesse caso, você implementa uma função de acionamento onOpen(e) para criar os itens de menu que o complemento precisa, possivelmente usando os dados no objeto de evento.

Nesta página, fornecemos diretrizes sobre como usar gatilhos em projetos de complementos do editor.

Tipos de acionadores do complemento do editor

É possível usar a maioria dos tipos de acionadores genéricos disponíveis para projetos do Apps Script nos complementos do editor, incluindo acionadores simples e a maioria dos acionadores instaláveis. O conjunto exato de tipos de acionadores disponíveis depende do aplicativo que está sendo estendido.

A tabela a seguir mostra os tipos de gatilhos simples e instaláveis que os complementos do Editor podem usar e fornece links para os objetos de evento correspondentes:

Evento	Objeto de evento	Gatilhos simples	Gatilhos instaláveis
Abrir Um arquivo do editor é aberto.	Objeto de evento onOpen do Documentos Objeto de evento onOpen do Formulários Objeto de evento onOpen das Planilhas Objeto de evento onOpen das Apresentações	Documentos Formulários* Planilhas Apresentações function onOpen(e)	Documentos Formulários Planilhas
Instalar O complemento é instalado.	Objeto de evento onInstall	Documentos Formulários Planilhas Apresentações function onInstall(e)
Editar O conteúdo da célula da planilha é alterado.	Objeto de evento onEdit do Google Sheets	Planilhas function onEdit(e)	Planilhas
Alteração : o conteúdo de uma página é editado ou formatado.	Objeto de evento onChange do Planilhas		Planilhas
Form-submit Um Formulário Google é enviado.	Objeto de evento de envio de formulário do Formulários Objeto de evento de envio de formulário do Planilhas		Formulários Planilhas
Acionado por tempo (relógio) O gatilho é acionado em um horário ou intervalo especificado.	Objeto de evento baseado em tempo		Documentos Formulários Planilhas Apresentações

* O evento de abertura dos Formulários Google 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.

Acionadores simples em complementos

Os gatilhos simples usam um conjunto de nomes de funções reservadas, não podem usar serviços que exigem autorização e são ativados automaticamente para uso. Em alguns casos, um evento de acionamento simples pode ser processado por um acionador instalável.

Para adicionar um gatilho simples a um complemento, basta implementar uma função com um dos seguintes nomes reservados:

• onOpen(e) é executado quando um usuário abre um documento, uma planilha ou uma apresentação. O onOpen(e) também pode ser executado quando um formulário é aberto no editor, mas não ao responder a ele. Ele só é executado se o usuário tiver permissão para editar o arquivo em questão e é usado com mais frequência para criar itens de menu.
• onInstall(e) é executado quando um usuário instala um complemento. Normalmente, onInstall(e) é usado apenas para chamar onOpen(e). Isso garante que os menus do complemento apareçam imediatamente após a instalação, sem exigir que o usuário atualize a página.
• onEdit(e) é executado quando um usuário muda o valor de uma célula em uma planilha. Esse gatilho não é acionado em resposta a movimentos de células, formatação ou outras mudanças que não alteram os valores das células.

Restrições

Os acionadores simples em complementos estão sujeitos às mesmas restrições que regem os acionadores simples em outros tipos de projetos do Apps Script. Preste atenção especial a estas restrições ao projetar complementos:

• Gatilhos simples não são executados se um arquivo for aberto no modo somente leitura (visualização ou comentário). Esse comportamento impede que os menus de complementos sejam preenchidos.
• Em determinadas circunstâncias, os complementos do Editor executam os gatilhos simples onOpen(e) e onEdit(e) em um modo sem autorização. Esse modo apresenta algumas complicações adicionais, conforme descrito no modelo de autorização de complemento.
• Os acionadores simples não podem usar serviços nem realizar outras ações que exijam autorização, exceto conforme descrito no modelo de autorização de complemento.
• Os gatilhos simples não podem ser executados por mais de 30 segundos. Tome cuidado para minimizar a quantidade de processamento feita em uma função de acionamento simples.
• Os acionadores simples estão sujeitos aos limites de cota dos acionadores do Apps Script.

Acionadores instaláveis em complementos

Os complementos podem criar e modificar acionadores instaláveis de maneira programática com o serviço Script do Apps Script. Os acionadores instaláveis de complementos não podem ser criados manualmente. Ao contrário dos gatilhos simples, os gatilhos instaláveis podem usar serviços que exigem autorização.

Os gatilhos instaláveis em complementos não enviam e-mails de erro ao usuário quando encontram erros, já que, na maioria dos casos, o usuário não consegue resolver o problema. Por isso, crie seu complemento para lidar com erros em nome do usuário sempre que possível.

Os complementos podem usar os seguintes gatilhos instaláveis:

• Os gatilhos instaláveis Abrir são executados quando um usuário abre um documento, uma planilha ou um formulário no editor (mas não ao responder ao formulário).
• Os gatilhos editáveis são executados quando um usuário muda o valor de uma célula em uma planilha. Esse gatilho não é acionado em resposta a formatação ou outras mudanças que não alteram os valores das células.
• Os gatilhos instaláveis de mudança são executados quando um usuário faz qualquer alteração em uma planilha, incluindo edições de formatação e modificações na planilha em si (como adicionar uma linha).

• Os acionadores instaláveis de envio de formulário são executados quando uma resposta do Formulários Google é enviada.

• Acionadores baseados em tempo (também chamados de acionadores de relógio) são disparados em um horário específico ou repetidamente em um intervalo de tempo regular.

Como autorizar acionadores instaláveis

Normalmente, se um desenvolvedor atualiza um complemento para usar novos serviços que exigem autorização adicional, os usuários são solicitados a autorizar novamente o complemento na próxima vez que o usarem.

No entanto, os complementos que usam gatilhos enfrentam desafios especiais de autorização. Imagine um complemento que usa um gatilho para monitorar envios de formulários: um criador de formulários pode autorizar o complemento na primeira vez que o usa e deixá-lo em execução por meses ou anos sem nunca reabrir o formulário. Se o desenvolvedor do complemento atualizasse o complemento para usar novos serviços que exigem autorização adicional, o criador do formulário nunca veria a caixa de diálogo de reautorização porque nunca reabriu o formulário, e o complemento pararia de funcionar.

Ao contrário dos gatilhos em projetos regulares do Apps Script, os gatilhos em complementos continuam sendo acionados mesmo que precisem de nova autorização. No entanto, o script ainda falhará se atingir uma linha de código que exija uma autorização que o script não tenha. Para evitar essa situação, os desenvolvedores podem usar o método ScriptApp.getAuthorizationInfo() para restringir o acesso a partes do código que mudaram entre as versões publicadas do complemento.

Confira abaixo um exemplo da estrutura recomendada para usar em funções de gatilho e evitar problemas de autorização. A função de acionamento de exemplo responde a um evento de envio de formulário em um complemento do Google Sheets e, se for necessária uma nova autorização, envia ao usuário do complemento um e-mail de alerta usando HTML com modelo.

/**  * Responds to a form when submitted.  * @param {event} e The Form submit event.  */ function respondToFormSubmit(e) {   const addonTitle = 'My Add-on Title';   const props = PropertiesService.getDocumentProperties();   const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);    // Check if the actions of the trigger requires authorization that has not   // been granted yet; if so, warn the user via email. This check is required   // when using triggers with add-ons to maintain functional triggers.   if (authInfo.getAuthorizationStatus() ===     ScriptApp.AuthorizationStatus.REQUIRED) {     // Re-authorization is required. In this case, the user needs to be alerted     // that they need to re-authorize; the normal trigger action is not     // conducted, since it requires authorization first. Send at most one     // "Authorization Required" email per day to avoid spamming users.     const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');     const today = new Date().toDateString();     if (lastAuthEmailDate !== today) {       if (MailApp.getRemainingDailyQuota() > 0) {         const html = HtmlService.createTemplateFromFile('AuthorizationEmail');         html.url = authInfo.getAuthorizationUrl();         html.addonTitle = addonTitle;         const message = html.evaluate();         MailApp.sendEmail(Session.getEffectiveUser().getEmail(),             'Authorization Required',             message.getContent(), {               name: addonTitle,               htmlBody: message.getContent()             }         );       }       props.setProperty('lastAuthEmailDate', today);     }   } else {     // Authorization has been granted, so continue to respond to the trigger.     // Main trigger logic here.   } }

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically     whenever a form is submitted. The add-on was recently updated and it needs you     to re-authorize it to run on your behalf.</p>  <p>The add-on's automatic functions are temporarily disabled until you     re-authorize it. To do so, open Google Sheets and run the add-on from the     Add-ons menu. Alternatively, you can click this link to authorize it:</p>  <p><a href="<?= url ?>">Re-authorize the add-on.</a></p>  <p>This notification email will be sent to you at most once per day until the     add-on is re-authorized.</p>

Restrições

Os gatilhos instaláveis em complementos estão sujeitos às mesmas restrições que regem os gatilhos instaláveis em outros tipos de projetos do Apps Script.

Além dessas restrições, várias outras se aplicam especificamente a acionadores instaláveis em complementos:

• Cada complemento pode ter apenas um gatilho de cada tipo por usuário e por documento. Por exemplo, em uma determinada planilha, um usuário só pode ter um gatilho de edição, mas também pode ter um gatilho de envio de formulário ou um gatilho baseado em tempo na mesma planilha. Outro usuário com acesso à mesma planilha pode ter um conjunto separado de acionadores.
• Os complementos só podem criar acionadores para o arquivo em que são usados. Ou seja, um complemento usado no documento A não pode criar um acionador para monitorar quando o documento B é aberto.
• Os gatilhos baseados em tempo não podem ser executados com mais frequência do que uma vez por hora.
• Os complementos não enviam um e-mail automaticamente ao usuário quando o código executado por um gatilho instalável gera uma exceção. É responsabilidade do desenvolvedor verificar e lidar com casos de falha de maneira adequada.
• Os gatilhos de complementos param de ser acionados em qualquer uma das seguintes situações:
  • Se o usuário desinstalar o complemento,
  • Se o complemento estiver desativado em um documento (se ele for reativado, o gatilho voltará a funcionar) ou
  • Se o desenvolvedor cancelar a publicação do complemento ou enviar uma versão corrompida para a loja de complementos.
• As funções de acionamento de complementos são executadas até atingir um código que usa um serviço não autorizado, momento em que são interrompidas. Isso só é válido se o complemento for publicado. O mesmo gatilho em um projeto normal do Apps Script ou em um complemento não publicado não será executado se qualquer parte do script precisar de autorização.
• Os gatilhos instaláveis estão sujeitos aos limites de cota de gatilho do Apps Script.