Esta página foi traduzida pela API Cloud Translation.

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 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 widgets adequada que define qual tipo de interação aciona o callback Action.

Configure um widget com um Action usando este processo geral:

Crie o objeto Action, especificando a função de callback que ele precisa executar junto com os parâmetros necessários.
Chame a função de manipulador de widget adequada no widget usando o objeto Action.
Implemente a função de callback para realizar o comportamento necessário.

Para vincular um widget a um Action específico ou outro comportamento, use uma função de manipulador de widget. A função de manipulador 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âmetros 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 composição 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 manipulador 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 insere 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 cartão 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 independentes do aplicativo host específico que o complemento está estendendo:

Ação tentada	A função de callback precisa retornar
Navegar entre cards	`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:

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.