Le azioni dei componenti aggiuntivi forniscono un comportamento interattivo ai widget. Creando un'azione, definisci cosa succede quando l'utente seleziona o aggiorna un widget.
Nella maggior parte dei casi, puoi definire le azioni dei componenti aggiuntivi utilizzando gli oggetti
Action
forniti dal servizio Card di Apps Script.
Ogni Action è associato a una funzione di callback al momento della creazione. Implementa la funzione di callback per eseguire i passaggi desiderati quando l'utente interagisce con il widget. Devi anche collegare Action al widget utilizzando una funzione di gestore del widget appropriata che definisce il tipo di interazione che attiva il callback Action.
Configura un widget con un Action
utilizzando questa procedura generale:
- Crea l'oggetto
Action, specificando la funzione di callback da eseguire insieme a eventuali parametri richiesti. - Chiama la funzione di gestore del widget appropriata sul widget utilizzando l'oggetto
Action. - Implementa la funzione di callback per applicare il comportamento richiesto.
Funzioni di gestore dei widget
Per collegare un widget a un Action specifico o a un altro comportamento, utilizza una funzione di gestore del widget. La funzione di gestore determina il tipo di interazione
(ad esempio, fare clic sul widget o modificare un campo di testo) che attiva il
comportamento dell'azione. La funzione di gestore definisce anche i passaggi, se presenti, che l'interfaccia utente esegue al termine dell'azione.
La tabella seguente elenca i diversi tipi di gestori per i widget e i widget con cui vengono utilizzati:
| Funzione di gestore | Azione di attivazione | Widget applicabili | Descrizione |
|---|---|---|---|
setOnChangeAction() |
Il valore del widget cambia |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Imposta un Action
che esegue una funzione di Apps Script quando il widget perde il focus, ad esempio quando l'utente inserisce del testo in un input e preme Invio. Il
gestore passa automaticamente un
oggetto evento alla funzione che chiama.
Se vuoi, puoi inserire ulteriori informazioni sui parametri in questo oggetto evento. |
setOnClickAction() |
L'utente fa clic sul widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Imposta un Action
che esegue una funzione di Apps Script quando l'utente fa clic sul widget. Il
gestore passa automaticamente un
oggetto evento alla funzione che chiama.
In questo oggetto evento puoi inserire informazioni facoltative sui parametri. |
setComposeAction() |
L'utente fa clic sul widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Specifiche di Gmail. Imposta un
Action
che crea una bozza di email, poi la presenta all'utente in una
finestra di composizione dell'interfaccia utente di Gmail. Puoi creare la bozza come nuovo messaggio o come risposta al messaggio aperto in Gmail. Quando il gestore chiama la funzione di callback per la creazione della bozza, passa un oggetto evento alla funzione di callback.
Per ulteriori dettagli, consulta la sezione Creare bozze di messaggi. |
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
devi creare l'URL o devono essere eseguite altre azioni prima dell'apertura del link;
in caso contrario, in genere è più semplice utilizzare setOpenLink().
Puoi aprire l'URL solo in una nuova finestra. Quando è chiuso, puoi causare il ricaricamento del componente aggiuntivo nell'interfaccia utente. |
setOpenLink() |
L'utente fa clic sul widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Apre direttamente un URL quando l'utente fa clic sul widget. Utilizza questo
gestore quando conosci l'URL e devi solo aprirlo; in caso contrario, utilizza
setOnClickOpenLinkAction().
Puoi aprire l'URL in una nuova finestra o in un overlay. Quando è chiuso, puoi fare in modo che l'interfaccia utente ricarichi il componente aggiuntivo. |
setSuggestionsAction() |
L'utente inserisce del testo in un campo di immissione |
TextInput
|
Imposta un Action
che esegue una funzione di Apps Script quando l'utente inserisce testo in un
widget di immissione di testo. Il gestore passa automaticamente un
oggetto evento alla funzione che chiama.
Per ulteriori dettagli, consulta la sezione Suggerimenti di completamento automatico per gli input di testo. |
Funzioni di callback
Le funzioni di callback vengono eseguite quando viene attivato un Action. Poiché le funzioni di callback sono funzioni di Apps Script, puoi chiedere loro di fare quasi tutto ciò che può fare qualsiasi altra funzione di script.
A volte una funzione di callback restituisce un oggetto di risposta specifico. Questi tipi di risposte indicano operazioni aggiuntive che devono essere eseguite al termine dell'esecuzione del riavvio, ad esempio la visualizzazione di una nuova scheda o la presentazione di suggerimenti di completamento automatico. Quando la funzione di callback deve restituire un oggetto risposta specifico, utilizza una classe di builder nel servizio Schede per creare l'oggetto.
La tabella seguente mostra quando le funzioni di callback devono restituire un oggetto di risposta specifico per azioni specifiche. Queste azioni sono tutte indipendente dall'applicazione host specifica estesa dal componente aggiuntivo:
| Azione tentata | La funzione di callback deve restituire |
|---|---|
| Spostarsi tra le schede | ActionResponse |
Mostrare un Notification |
ActionResponse |
Aprire un link utilizzando setOnClickOpenLinkAction() |
ActionResponse |
| Visualizzare i suggerimenti di completamento automatico | SuggestionResponse |
| Utilizzare un'azione universale | UniversalActionResponse |
| Altre azioni | Nothing |
Oltre a queste azioni, ogni applicazione host ha il proprio insieme di azioni che possono essere intraprese solo in quell'host. Per maggiori dettagli, consulta le seguenti guide:
Oggetti evento di azioni
Quando il tuo componente aggiuntivo attiva un Action,
la UI crea automaticamente un oggetto evento JSON e lo passa come
argomento alla funzione di callback Action. Questo oggetto evento contiene informazioni sul contesto lato client corrente dell'utente, ad esempio i valori correnti di tutti i widget interattivi nella scheda visualizzata.
Gli oggetti evento di azioni hanno una struttura JSON specifica che organizza le informazioni che contengono. La stessa struttura viene utilizzata quando viene attivato un attivatore della home page per creare una home page o un attivatore contestuale per aggiornare la visualizzazione del componente aggiuntivo.
Per una spiegazione completa della struttura dell'oggetto evento, consulta Oggetti evento.