Le azioni dei componenti aggiuntivi forniscono un comportamento interattivo widget. Creando un'azione, definisci cosa succede quando l'utente seleziona o aggiorna un widget.
Nella maggior parte dei casi puoi definire azioni aggiuntive utilizzando
Action
forniti dal servizio di carte di Apps Script.
Ogni Action è associato a
una funzione di callback quando la crei. Implementi la funzione di callback
per eseguire i passaggi desiderati quando l'utente interagisce con il widget. Devi inoltre
collega Action al widget
utilizzando una funzione di gestore widget appropriata che
definisce il tipo di interazione che attiva
Chiamata di Action.
Configurare un widget con una Action
utilizzando questa procedura generale:
- Crea l'oggetto
Action, che specifichi la funzione di callback insieme ai parametri di cui ha bisogno. - Chiamare la funzione di gestore widget appropriata.
sul widget utilizzando
Action. - Implementa la funzione di callback per applicare il comportamento richiesto.
Funzioni gestore widget
Per collegare un widget a una Action specifica
o in un altro comportamento, usi un widget
di Google Cloud. La funzione gestore determina il tipo di interazione
(ad esempio, facendo clic sul widget o modificando un campo di testo) attiva la
comportamento dell'azione. La funzione gestore definisce anche i passaggi eseguiti dall'interfaccia utente,
se presente, al termine dell'azione.
La tabella seguente elenca i diversi tipi di gestori per i widget e i i widget con cui vengono utilizzati:
| Funzione gestore | Attiva l'azione | Widget applicabili | Descrizione |
|---|---|---|---|
setOnChangeAction() |
Il valore del widget cambia |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Imposta un Action
che esegue una funzione Apps Script quando il widget perde lo stato attivo, ad esempio
come quando l'utente inserisce testo in un input e preme Invio. La
trasmette automaticamente
oggetto evento alla funzione che chiama.
In questo oggetto evento puoi inserire ulteriori informazioni sui parametri
se lo desideri. |
setOnClickAction() |
L'utente fa clic sul widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Imposta un Action
che esegue una funzione Apps Script quando l'utente fa clic sul widget. La
trasmette automaticamente
oggetto evento alla funzione che chiama.
In questo oggetto evento puoi inserire informazioni facoltative sui parametri. |
setComposeAction() |
L'utente fa clic sul widget |
CardActionImageImageButtonDecoratedTextTextButton
|
specifici per Gmail. Imposta un
Action
che crea una bozza di email e la presenta all'utente in un
Finestra di composizione nell'interfaccia utente di Gmail. Puoi creare la bozza come nuovo messaggio o
rispondi al messaggio aperto in Gmail. Quando il gestore chiama
funzione di callback di creazione di bozze, passa
oggetto evento alla funzione di callback.
Consulta
Scrivere bozze di messaggi
per ulteriori dettagli. |
setOnClickOpenLinkAction() |
L'utente fa clic sul widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Imposta un Action
per aprire un URL quando l'utente fa clic sul widget. Utilizza questo gestore quando
l'URL, altrimenti le altre azioni devono essere eseguite prima del collegamento
si apre; altrimenti è di solito più semplice usare setOpenLink().
Puoi aprire l'URL solo in una nuova finestra. Quando è chiuso, puoi causare
UI per ricaricare il componente aggiuntivo. |
setOpenLink() |
L'utente fa clic sul widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Apre direttamente un URL quando l'utente fa clic sul widget. Usa questa
quando conosci l'URL e devi solo aprirlo; altrimenti usa
setOnClickOpenLinkAction().
Puoi aprire l'URL in una nuova finestra o in un overlay. Una volta chiuso,
può causare il ricaricamento del componente aggiuntivo nell'interfaccia utente. |
setSuggestionsAction() |
L'utente inserisce del testo in un input |
TextInput
|
Imposta un Action
che esegue una funzione Apps Script quando l'utente inserisce testo in una
widget per l'inserimento di testo. Il gestore trasmette automaticamente
oggetto evento alla funzione che chiama.
Consulta
Suggerimenti di completamento automatico
per gli input di testo per ulteriori dettagli. |
Funzioni di callback
Le funzioni di callback vengono eseguite quando una Action
trigger. Poiché le funzioni di callback sono funzioni Apps Script, puoi utilizzarle
consente di fare quasi tutto ciò che può fare qualsiasi altra funzione di script.
Una funzione di callback a volte restituisce un oggetto di risposta specifico. Questi i tipi di risposta indicano operazioni aggiuntive che devono essere eseguite dopo termina l'esecuzione del callback, ad esempio mostrando una nuova scheda o presentando suggerimenti di completamento automatico. Quando la funzione di callback deve restituire uno specifico , utilizzi una classe builder nel servizio Card per creare quell'oggetto.
La tabella seguente mostra quando le funzioni di callback devono restituire un specifico per azioni specifiche. Queste azioni sono tutte Indipendentemente dall'applicazione host specifica che il componente aggiuntivo sta estendendo:
| Azione tentata | La funzione di callback deve restituire |
|---|---|
| Navigare tra le schede | ActionResponse |
Mostra un Notification |
ActionResponse |
Aprire un link utilizzando setOnClickOpenLinkAction() |
ActionResponse |
| Mostra suggerimenti di completamento automatico | SuggestionResponse |
| Utilizza un'azione universale | UniversalActionResponse |
| Altre azioni | Nothing |
Oltre a queste azioni, ogni applicazione host ha il proprio insieme azioni che possono essere eseguite solo nell'host. Per maggiori dettagli, consulta le seguenti risorse: guide:
di Gemini Advanced.Oggetti di eventi di azione
Quando il componente aggiuntivo attiva una Action,
la UI genera automaticamente un oggetto evento JSON e lo passa come
al callback Action
personalizzata. Questo oggetto evento contiene informazioni sulla configurazione attuale
contesto lato client, come i valori correnti di tutte le
widget nella scheda visualizzata.
Gli oggetti di eventi azione hanno una struttura JSON specifica che organizza le informazioni che contengono. La stessa struttura viene utilizzata quando attivatore home page viene attivata per creare una home page oppure quando attivatore contestuale per aggiornare il display del componente aggiuntivo.
Consulta Oggetti evento per una panoramica spiegazione della struttura degli oggetti evento.