As ações de complementos oferecem 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 de complementos usando objetos Action fornecidos pelo serviço de cartão do Apps Script.
Cada Action é associado a
uma função de callback quando você o cria. Você implementa a função de callback
para realizar as etapas desejadas quando o usuário interage com o widget. Você também precisa
vincular o Action ao widget
usando uma função de gerenciador de widgets adequada 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 ele precisa executar 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 acionar o comportamento necessário.
Funções de gerenciador de widgets
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 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 interface segue,
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 de gerenciador | Aciona 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
quando o usuário insere texto em uma entrada e pressiona Enter. O
gerenciador transmite automaticamente um
objeto de evento para a função que ele chama.
Se quiser, você pode inserir outras informações de parâmetro nesse objeto de evento. |
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. O gerenciador transmite automaticamente um
objeto de evento para a função que ele chama.
É possível inserir informações de parâmetro opcionais nesse objeto de evento. |
setComposeAction() |
O usuário clica no widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Específico do Gmail. Define um
Action
que cria um rascunho de e-mail e o apresenta ao usuário em uma
janela de composição da interface do Gmail. Você pode 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 transmite 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 |
CardActionImageImageButtonDecoratedTextTextButton
|
Define um Action
para abrir um URL quando o usuário clica no widget. Use esse manipulador quando precisar
criar o URL ou outras ações precisarem acontecer 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 |
CardActionImageImageButtonDecoratedTextTextButton
|
Abre diretamente um URL quando o usuário clica no widget. Use esse
gerenciador quando você 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. Quando fechado, você
pode fazer com que a interface recarregue o complemento. |
setSuggestionsAction() |
O usuário insere texto em um campo de 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 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
fazer quase tudo que qualquer outra função de script pode 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 depois que o callback terminar a execução, 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 de 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 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 um conjunto de ações que só podem ser realizadas nesse host. Para mais detalhes, consulte estes guias:
Objetos de eventos de ação
Quando o complemento aciona um Action,
a interface 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 usuário no lado do cliente, 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 gatilho da página inicial é acionado para criar uma página inicial ou quando um gatilho contextual é acionado para atualizar a exibição do complemento.
Consulte Objetos de evento para uma explicação completa da estrutura de objetos de evento.