As ações complementares 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, você pode definir ações complementares usando
Action
Objetos fornecidos pelo serviço Card do Apps Script.
Cada Action está associado a
uma função de callback quando você a cria. Implemente a função de callback
executar as etapas desejadas quando o usuário interagir com o widget. Você também deve
vincular Action ao widget
usando uma função gerenciadora de widget apropriada que
define que tipo de interação aciona
Callback Action.
Configurar um widget com um Action
usando este processo geral:
- Crie o objeto
Action. especificando a função de callback com todos os parâmetros necessários. - Chame a função de gerenciador de widget apropriada.
no widget usando
Actionobjeto. - Implemente a função de callback para aplicar o comportamento necessário.
Funções do gerenciador de widgets
Para vincular um widget a uma Action específica:
ou outro comportamento, você usa um widget
gerenciador de eventos. 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 de ação. A função de gerenciador também define as etapas realizadas pela interface,
se houver, após a conclusão da ação.
A tabela a seguir lista os diferentes tipos de manipuladores para widgets e quais widgets com os quais são usados:
| Função do gerenciador | Aciona a ação | Widgets aplicáveis | Descrição |
|---|---|---|---|
setOnChangeAction() |
O valor do widget muda |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Define um Action.
que executa uma função do Apps Script quando o widget perde o foco, como
como quando o usuário digita texto em uma entrada e pressiona Enter. A
automaticamente passa um
objeto de evento à função que ele chama.
É possível inserir mais informações de parâmetro neste objeto de evento
se quiser. |
setOnClickAction() |
O usuário clica no widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Define um Action.
que executa uma função do Apps Script quando o usuário clica no widget. A
automaticamente passa um
objeto de evento à função que ele chama.
Você pode inserir informações de parâmetro opcionais neste objeto de evento. |
setComposeAction() |
O usuário clica no widget |
CardActionImageImageButtonDecoratedTextTextButton
|
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
responda à mensagem aberta no Gmail. Quando o manipulador chama o método
função de retorno de chamada de criação de rascunho, ela passa uma
objeto de evento à função de callback.
Consulte
Escrever rascunhos de mensagens
para mais detalhes. |
setOnClickOpenLinkAction() |
O usuário clica no widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Define um Action.
para abrir um URL quando o usuário clicar no widget. Use esse gerenciador quando você
deve construir o URL ou outras ações devem ocorrer antes que o link
abre; 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 o
interface para recarregar o complemento. |
setOpenLink() |
O usuário clica no widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Abre diretamente um URL quando o usuário clica no widget. Usar
quando souber o URL e só precisar abri-lo. usar
setOnClickOpenLinkAction():
Você pode abrir o URL em uma nova janela ou em uma sobreposição. Quando fechado, você
pode 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 digita texto em um
widget de entrada de texto. O manipulador passa automaticamente um
objeto de evento à 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
gatilhos. Como elas são funções do Apps Script, elas podem ser usadas
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 os tipos de respostas indicam operações adicionais que precisam acontecer a execução do callback termina, por exemplo, a exibição de um novo cartão ou a apresentação sugestões de preenchimento automático. Quando sua função de callback precisar retornar um tipo objeto de resposta, você usa 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. Todas essas ações independente 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 hospedeiro possui o próprio conjunto de que só podem ser realizadas nele. Para mais detalhes, consulte as seguintes informações: guias:
.Objetos de evento de ação
Quando seu complemento acionar um Action,
a interface constrói automaticamente um objeto de evento JSON e o passa como uma
argumento de venda para o callback Action
função. Esse objeto de evento contém informações sobre o estado atual do usuário
contexto do lado do cliente, como os valores atuais de todas as interações
widgets no cartão exibido.
Os objetos de evento de ação têm uma estrutura JSON específica que organiza informações que eles contêm. A mesma estrutura é usada acionador da página inicial dispara para criar uma página inicial ou quando uma acionador contextual dispara para atualizar a tela do complemento.
Consulte Objetos de evento para ver um explicação sobre a estrutura do objeto de evento.