Esta página foi traduzida pela API Cloud Translation.

Ações do complemento

As ações dos complementos fornecem um 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, você pode definir ações complementares usando objetos Action fornecidos pelo serviço de cartões do Apps Script. Cada Action está associado a uma função de callback quando você o cria. Implemente a função de callback para executar as etapas desejadas quando o usuário interagir com o widget. Também é necessário vincular o Action ao widget usando uma função de gerenciador de widget adequada que defina 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 ela precisa executar com os parâmetros necessários.
Chame a função de gerenciador de widget apropriada no widget usando o objeto Action.
Implemente a função de callback para ativar o comportamento necessário.

Funções de gerenciador de widget

Para vincular um widget a um Action ou outro comportamento específico, use uma função de gerenciamento de widgets. A função do gerenciador determina o tipo de interação, como clicar no widget ou editar um campo de texto, aciona o comportamento da ação. A função de gerenciador também define quais etapas a IU realiza, se houver, após a conclusão da ação.

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

Função do gerenciador	Ação de acionamento	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 digita texto em uma entrada e pressiona Enter. O gerenciador passa automaticamente um objeto de evento para a função que chama. É possível inserir outras informações de parâmetro nesse objeto de evento se quiser.
`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 gerenciador passa automaticamente um objeto de evento para a função que chama. É possível inserir informações de parâmetro opcionais nesse objeto de evento.
`setComposeAction()`	O usuário clica no widget.	`CardAction` `Image` `ImageButton` `DecoratedText` `TextButton`	E-mail específico do Gmail. Define um `Action` que cria um rascunho de e-mail e apresenta esse rascunho ao usuário em uma janela de texto da IU do Gmail. É possível criar o rascunho como uma nova mensagem ou uma resposta à mensagem aberta no Gmail. Quando o gerenciador chama a função de callback de compilação de rascunho, ele passa um objeto de evento para a função de callback. Consulte Escrever mensagens de rascunho 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 for preciso criar o URL ou outras ações precisam ser realizadas antes da abertura do link. Caso contrário, geralmente é mais simples usar `setOpenLink()`. Você só pode abrir o URL em uma nova janela. Quando a IU estiver fechada, você poderá recarregar o complemento.
`setOpenLink()`	O usuário clica no widget.	`CardAction` `Image` `ImageButton` `DecoratedText` `TextButton`	Abre diretamente um URL quando o usuário clica no widget. Use esse gerenciador 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 ela estiver fechada, você poderá atualizar a IU.
`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 digita texto em um widget de entrada de texto. O gerenciador 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 a função de callback é uma função do Apps Script, ela pode realizar praticamente qualquer outra função do script.

Às vezes, uma função de callback retorna um objeto de resposta específico. Esses tipos de resposta indicam operações adicionais que precisam acontecer após a conclusão do callback, como a exibição de um novo cartão ou a apresentação de sugestões de preenchimento automático. Quando sua função de callback precisa retornar um objeto de resposta específico, você usa uma classe builder no serviço de cards 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 realizada	A função de callback vai retornar
Navegar entre os cards	`ActionResponse`
Mostrar um `Notification`	`ActionResponse`
Abrir um link usando `setOnClickOpenLinkAction()`	`ActionResponse`
Exibir sugestões de preenchimento automático	`SuggestionResponse`
Use uma ação universal	`UniversalActionResponse`
Outras ações	Nothing

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

Objetos de evento de ação

Quando seu complemento aciona um Action, a IU 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 usuário no lado do cliente, como os valores atuais de todos os widgets interativos do card exibido.

Os objetos de eventos 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 acionador de página inicial é acionado para criar uma página inicial ou quando um acionador contextual é disparado para atualizar a exibição do complemento.

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