As ações de complementos oferecem 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 de complementos usando objetos
Action
fornecidos pelo serviço de cards do Apps Script.
Cada Action
é associada a
uma função de callback quando você a cria. Implemente a função de callback para realizar as etapas desejadas quando o usuário interagir com o widget. Também é preciso
vincular o Action
ao widget
usando uma função do gerenciador de widgets adequada que
defina o tipo de interação que 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 precisa ser executada com os parâmetros necessários. - Chame a função do gerenciador de widgets
adequada no widget usando o objeto
Action
. - Implemente a função de callback para ativar 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
de gerenciador 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 do 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 gerenciadores 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 é alterado. |
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 gerenciador transmite automaticamente um objeto de evento para a função chamada.
Se quiser, é possível inserir 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.
É 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
|
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 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 criaçã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 precisar construir o URL ou outras ações precisarão 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. Depois do fechamento, a IU pode
atualizar 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
gerenciador quando souber o URL e precisar apenas abri-lo. Caso contrário, use
setOnClickOpenLinkAction() .
Você pode abrir o URL em uma nova janela ou em uma sobreposição. Depois do fechamento, a IU pode recarregar 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 chama.
Consulte Sugestões de preenchimento automático para entradas de texto se quiser 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 praticamente 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 resposta indicam outras operações que precisam acontecer depois que o callback termina a execução, como mostrar um novo cartão ou apresentar sugestões de preenchimento automático. Quando a função de callback precisar 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 ações específicas. Essas ações são independentes do aplicativo host específico que o complemento está estendendo:
Tentativa de fazer uma ação | A função de callback precisa retornar |
---|---|
Navegar entre cards | ActionResponse |
Exibir uma 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 | Nada |
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 os seguintes 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 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 tela do complemento.
Consulte Objetos de evento para uma explicação completa da estrutura do objeto de evento.