Esta página foi traduzida pela API Cloud Translation.

Ações do complemento

As ações de complementos oferecem um comportamento interativo para 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 cards do Apps Script. Cada Action é associado a uma função de callback quando você o cria. Implemente a função de callback para realizar as etapas desejadas quando o usuário interagir com o widget. Também é necessário vincular 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 ele precisa executar com todos 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 aplicar o comportamento necessário.

Funções do gerenciador de widgets

Para vincular um widget a um Action específico ou outro comportamento, use uma função gerenciadora de widgets. A função do 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 gerenciador também define quais etapas a interface executa, se houver, depois que a ação é concluída.

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

Função do gerenciador	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 e pressiona Enter. O gerenciador transmite automaticamente um objeto de evento para a função chamada. Se quiser, insira outras informações de parâmetro nesse objeto de evento.
`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 transmite automaticamente um objeto de evento para a função chamada. Você pode inserir informações de parâmetro opcionais neste objeto de evento.
`setComposeAction()`	O usuário clica no widget	`CardAction` `Image` `ImageButton` `DecoratedText` `TextButton`	Específico para o 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. É 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 criação de rascunho, ele passa um objeto de evento para a função de callback. Consulte Escrever rascunhos de mensagens para saber mais.
`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 ocorrer antes que o link seja aberto. Caso contrário, geralmente é mais simples usar `setOpenLink()`. Só é possível abrir o URL em uma nova janela. Quando fechado, você pode fazer com que a interface recarregue 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 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 fechado, você poderá fazer com que a interface recarregue o complemento.
`setSuggestionsAction()`	O usuário digita um 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 gerenciador transmite automaticamente um objeto de evento para a função chamada. 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 são funções do Apps Script, elas podem fazer quase tudo que qualquer outra função de script pode fazer.

Uma função de callback às vezes retorna um objeto de resposta específico. Esses tipos de resposta indicam outras operações que precisam acontecer após a execução do callback, como mostrar um novo card ou apresentar sugestões de preenchimento automático. Quando a função de callback precisa retornar um objeto de resposta específico, use uma classe builder no Serviço de cartão para criar esse objeto.

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

Tentativa de ação	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

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

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