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, é possível definir ações complementares 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 seguir 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 widgets apropriada que
define que 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 widgets
apropriada no widget usando o objeto
Action
. - Implemente a função de callback para criar o comportamento necessário.
Funções do gerenciador de widget
Para vincular um widget a um Action
específico ou a outro comportamento, use uma função de gerenciador
de widgets. A função do gerenciador determina o 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 IU segue,
se houver, após a conclusão da ação.
A tabela a seguir lista os diferentes tipos de gerenciador de 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 manipulador transmite automaticamente um objeto de evento para a função que chama.
É possível inserir outras informações do parâmetro neste objeto de evento,
se você 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 manipulador transmite automaticamente um objeto de evento para a função que chama.
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 do Gmail. Define um
Action
que cria um rascunho de e-mail e, em seguida, 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 manipulador 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 ver 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
criar o URL ou outras ações precisarem ser realizadas antes da abertura do link.
Caso contrário, normalmente será mais simples usar setOpenLink() .
Você só pode abrir o URL em uma nova janela. Quando fechado, você pode fazer com que a
IU 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 conhecer 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ê pode fazer com que a IU atualize 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 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 fazer quase
qualquer outra função de script que ela possa fazer.
Às vezes, uma função de callback retorna um objeto de resposta específico. Esses tipos de respostas indicam operações adicionais que precisam acontecer após a execução do callback, como exibir um novo cartão ou apresentar sugestões de preenchimento automático. Quando a função de callback precisa retornar um objeto de resposta específico, você usa uma classe builder no Serviço de Card 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 de hospedagem específico que o complemento está estendendo:
Tentativa de ação | A função de retorno de chamada deve retornar |
---|---|
Navegar entre os cards | ActionResponse |
Exibir uma 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 | 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 saber mais detalhes, consulte os guias a seguir:
Objetos de evento de ação
Quando seu complemento aciona uma Action
,
a IU constrói 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 cartão 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 de contexto é acionado para atualizar a tela do complemento.
Consulte Objetos de evento para ver uma explicação completa da estrutura do objeto de eventos.