Ações do complemento

As ações de complementos oferecem comportamento interativo aos widgets. Ao criar uma ação, você define o que acontece quando o usuário seleciona ou atualiza um widget.

Na maioria dos casos, é possível definir ações de complementos usando objetos Action fornecidos pelo serviço de card do Google Apps Script. Cada Action é associado a uma função de callback quando você o cria. Você implementa a função de callback para executar as etapas selecionadas quando o usuário interage com o widget. Também é necessário vincular o Action ao widget usando uma função de gerenciador de widget adequada que define qual tipo de interação aciona o callback Action.

Configure um widget com um Action usando este processo:

  1. Crie o objeto Action, especificando a função de callback que ele precisa executar junto com os parâmetros necessários.
  2. Chame a função de gerenciador de widget apropriada no widget usando o objeto Action.
  3. Implemente a função de callback para ativar o comportamento necessário.

Não confunda objetos Action com objetos CardAction. Os objetos CardAction são itens de menu do cabeçalho do card, enquanto os objetos Action definem respostas às interações do usuário com a interface.

Funções de manipulador de widget

Para vincular um widget a um Action ou outro comportamento, use uma função de gerenciador de widgets. A função de gerenciador determina que tipo de interação (por exemplo, clicar no widget ou editar um campo de texto) aciona o comportamento da ação. A função de manipulador também define quais etapas a interface realiza, se houver, após a conclusão da ação.

A tabela a seguir lista os diferentes tipos de manipuladores para widgets e com quais widgets eles são usados:

Função de manipulador Aciona a ação Widgets aplicáveis Descrição
setOnChangeAction O valor do widget muda DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker 		Define um Action que executa uma função do Apps Script quando o widget perde o foco, como quando o usuário insere texto em uma entrada e pressiona "Enter". O manipulador transmite automaticamente um objeto de evento para a função que ele chama. Você pode inserir informações extras de parâmetro nesse objeto de evento, se selecionado.
setOnClickAction O usuário clica no widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Define um Action que executa uma função do Apps Script quando o usuário clica no widget. O manipulador transmite automaticamente um objeto de evento para a função que ele chama. Você pode inserir informações de parâmetros opcionais nesse objeto de evento.
setComposeAction O usuário clica no widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Específico do Gmail. Define um Action que cria um rascunho de e-mail e o apresenta ao usuário em uma janela de texto da interface do Gmail. Você pode criar o rascunho como uma nova mensagem ou uma resposta à mensagem aberta no Gmail. Quando o manipulador chama a função de callback de criação de rascunho, ele transmite um objeto de evento para a função de callback. Consulte Escrever mensagens de rascunho no Gmail para mais detalhes.
setOnClickOpenLinkAction O usuário clica no widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Define um Action para abrir um URL quando o usuário clica no widget. Use esse gerenciador quando precisar construir o URL ou outras ações precisarem ser realizadas antes da abertura do link. Caso contrário, geralmente é mais simples usar setOpenLink. Só é possível abrir o URL em uma nova janela. Quando fechada, você pode fazer com que a interface recarregue o complemento.
setOpenLink O usuário clica no widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Abre um URL diretamente quando o usuário clica no widget. Use esse manipulador quando você souber o URL e só precisar abri-lo. Caso contrário, use setOnClickOpenLinkAction. Você pode abrir o URL em uma nova janela ou em uma sobreposição. Quando fechada, você pode fazer com que a interface recarregue o complemento.
setSuggestionsAction O usuário digita texto em uma entrada TextInput Define um Action que executa uma função do Apps Script quando o usuário insere texto em um widget de entrada de texto. O manipulador transmite automaticamente um objeto de evento para a função que ele chama. Consulte Sugestões de preenchimento automático para entradas de texto para mais detalhes.

Funções de callback

As funções de callback são executadas quando um Action é acionado. Como as funções de callback são funções do Apps Script, elas podem fazer quase tudo que qualquer outra função de script faz.

Às vezes, uma função de callback retorna um objeto de resposta específico. Esses tipos de respostas indicam outras operações que precisam acontecer depois que o callback termina de ser executado, como mostrar um novo card ou apresentar sugestões de preenchimento automático. Quando sua função de callback precisa retornar um objeto de resposta específico, use uma classe builder no serviço de card para construir esse objeto.

A tabela a seguir mostra quando suas funções de callback precisam retornar um objeto de resposta específico para ações específicas. Essas ações são todas independentes do aplicativo host específico que o complemento está estendendo:

Ação tentada A função de callback precisa retornar
Navegar ActionResponse
Mostrar um Notification ActionResponse
Abrir um link usando setOnClickOpenLinkAction ActionResponse
Mostrar sugestões de preenchimento automático SuggestionResponse
Usar uma ação universal UniversalActionResponse
Outras ações Nothing

Ações para aplicativos host do Google Workspace

Além dessas ações, cada aplicativo host tem um conjunto próprio de ações que só podem ser realizadas nesse host. Para mais detalhes, consulte os seguintes guias:

Ao usar as classes de criador de respostas, chame o método build para produzir os objetos de resposta. Se isso não acontecer, haverá um erro.

As ações universais são definidas no manifesto do projeto e não precisam de objetos Action, mas as funções de callback precisam retornar um UniversalActionResponse.

Objetos de eventos de ação

Quando o complemento aciona um Action, a interface cria automaticamente um objeto de evento JSON e o transmite como um argumento para a função de callback Action. Esse objeto de evento contém informações sobre o contexto atual do lado do cliente do usuário, como os valores atuais de todos os widgets interativos no card exibido.

Os objetos de evento de ação têm uma estrutura JSON específica que organiza as informações que eles contêm. A mesma estrutura é usada quando um gatilho da página inicial é acionado para criar uma página inicial ou quando um gatilho contextual é acionado para atualizar a exibição do complemento.

Consulte Objetos de evento para uma explicação completa da estrutura do objeto de evento.

Os complementos do Gmail usavam uma versão simplificada dessa estrutura de objeto de evento, que agora está descontinuada. Para compatibilidade com versões anteriores, todos os campos do objeto de evento dos complementos originais do Gmail ainda estão contidos na nova estrutura de objeto de evento (consulte estrutura de objeto de evento). No entanto, as mesmas informações são reproduzidas nas subestruturas de commonEventObject e objeto de evento do Gmail. Se você estiver fazendo upgrade de um complemento do Gmail para um complemento do Google Workspace, ajuste seu código para usar os campos de objeto de evento atualizados. Com o tempo, os campos originais do objeto de evento do Gmail serão removidos.