Azioni componenti aggiuntivi

Le azioni aggiuntive costituiscono un comportamento interattivo per i widget. Quando crei un'azione, definisci cosa accade quando l'utente seleziona o aggiorna un widget.

Nella maggior parte dei casi puoi definire azioni aggiuntive utilizzando gli oggetti Action forniti dal servizio schede Apps Script. Ogni Action viene associata a una funzione di callback quando lo crei. Implementa la funzione di callback per eseguire i passaggi desiderati quando l'utente interagisce con il widget. Devi inoltre collegare Action al widget utilizzando una funzione di gestore widget appropriata che definisce il tipo di interazione che attiva il callback Action.

Configura un widget con una Action utilizzando questa procedura generale:

  1. Crea l'oggetto Action, specificando la funzione di callback che deve essere eseguita insieme ai parametri necessari.
  2. Chiama la funzione di gestore widget appropriata sul widget utilizzando l'oggetto Action.
  3. Implementare la funzione di callback per mettere in atto il comportamento richiesto.

Funzioni dei gestori dei widget

Per collegare un widget a un Action o a un altro comportamento specifico, devi utilizzare una funzione di gestione dei widget. La funzione gestore determina il tipo di interazione (ad esempio, il clic sul widget o la modifica di un campo di testo) attiva il comportamento dell'azione. La funzione gestore definisce inoltre i passaggi dell'interfaccia utente (se presenti) al termine dell'azione.

La seguente tabella elenca i diversi tipi di gestori per i widget e i widget con cui vengono utilizzati:

Funzione gestore Attivatore dell'azione Widget applicabili Descrizione
setOnChangeAction() Il valore del widget cambia DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker
Imposta un Action che esegue una funzione Apps Script quando il widget perde l'elemento attivo, ad esempio quando l'utente inserisce un testo in un input e preme Invio. Il gestore passa automaticamente un oggetto evento alla funzione che chiama. Se vuoi, puoi inserire ulteriori informazioni sul parametro in questo oggetto evento.
setOnClickAction() L'utente fa clic sul widget CardAction
Image
ImageButton
DecoratedText
TextButton
Imposta un Action che esegue una funzione Apps Script quando l'utente fa clic sul widget. Il gestore passa automaticamente un oggetto evento alla funzione che chiama. Puoi inserire informazioni facoltative sui parametri in questo oggetto evento.
setComposeAction() L'utente fa clic sul widget CardAction
Image
ImageButton
DecoratedText
TextButton
Specifico per Gmail. Imposta una Action che crea una bozza dell'email, quindi la presenta all'utente in una finestra di composizione della UI di Gmail. Puoi creare la bozza come nuovo messaggio o rispondere al messaggio aperto in Gmail. Quando il gestore chiama la funzione di callback di creazione della bozza, passa un oggetto evento alla funzione di callback. Per ulteriori dettagli, vedi Scrivere bozze di messaggi.
setOnClickOpenLinkAction() L'utente fa clic sul widget CardAction
Image
ImageButton
DecoratedText
TextButton
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; altrimenti è generalmente più semplice utilizzare setOpenLink(). Puoi aprire l'URL solo in una nuova finestra. Quando è chiuso, puoi ricaricare l'interfaccia utente del componente aggiuntivo.
setOpenLink() L'utente fa clic sul widget CardAction
Image
ImageButton
DecoratedText
TextButton
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 causare il ricaricamento del componente aggiuntivo.
setSuggestionsAction() L'utente inserisce un testo inserito TextInput Imposta un Action che esegue una funzione Apps Script quando l'utente inserisce testo in un widget di input di testo. Il gestore passa automaticamente un oggetto evento alla funzione chiamata. Per ulteriori dettagli, consulta Suggerimenti di completamento automatico per l'inserimento del 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 farle eseguire praticamente qualsiasi altra funzione di script.

A volte una funzione di callback restituisce un oggetto di risposta specifico. Questi tipi di risposta indicano operazioni aggiuntive che devono essere eseguite dopo l'esecuzione del callback, 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 di risposta specifico, devi utilizzare una classe del builder nel servizio Card per costruire tale oggetto.

La tabella seguente mostra quando le funzioni di callback devono restituire un oggetto di risposta specifico per azioni specifiche. Queste azioni sono tutte indipendenti dall'applicazione specifica dell'host che il componente aggiuntivo estende:

Azione tentata La funzione di callback dovrebbe tornare
Navigare tra le schede ActionResponse
Mostra una Notification ActionResponse
Aprire un link utilizzando setOnClickOpenLinkAction() ActionResponse
Mostra suggerimenti di completamento automatico SuggestionResponse
Utilizzare un'azione universale UniversalActionResponse
Altre azioni Nulla

Oltre a queste azioni, ogni applicazione host ha il proprio insieme di azioni che possono essere eseguite solo in quell'host. Per i dettagli, consulta le seguenti guide:

Oggetti evento di azione

Quando il componente aggiuntivo attiva un Action, l'UI crea automaticamente un oggetto evento JSON e lo trasmette come argomento alla funzione di callback Action. Questo oggetto evento contiene informazioni sull'attuale contesto lato client dell'utente, ad esempio i valori correnti di tutti i widget interattivi nella scheda visualizzata.

Gli oggetti evento azione hanno una struttura JSON specifica che organizza le informazioni che contengono. La stessa struttura viene utilizzata quando si attiva un attivatore della home page per creare una home page oppure quando viene attivato un attivatore contestuale per aggiornare la visualizzazione del componente aggiuntivo.

Consulta Oggetti evento per una spiegazione completa della struttura degli oggetti evento.