Azioni componenti aggiuntivi

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 di schede di Apps Script. Ogni elemento Action è associato a una funzione di callback quando la crei. Puoi implementare 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 definisca il tipo di interazione che attiva il callback Action.

Per configurare un widget con una Action, segui questa procedura generale:

1. Crea l'oggetto Action, specificando la funzione di callback da eseguire insieme ai parametri richiesti.
2. Richiama la funzione di gestore del widget appropriata sul widget utilizzando l'oggetto Action.
3. Implementa la funzione di callback per applicare il comportamento richiesto.

Nota: non confondere gli oggetti Action con gli oggetti CardAction. Gli oggetti CardAction sono voci di menu dell'intestazione della scheda, mentre gli oggetti Action definiscono le risposte alle interazioni degli utenti con la UI.

Funzioni gestore widget

Per collegare un widget a uno specifico comportamento di Action o a un altro comportamento, utilizza 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) che attiva il comportamento dell'azione. La funzione gestore definisce anche i passaggi seguiti dall'interfaccia utente, se presenti, dopo il completamento dell'azione.

Nella tabella seguente sono elencati i diversi tipi di gestori dei widget e i widget con cui vengono utilizzati:

Funzione gestore	Attiva l'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 lo stato attivo, ad esempio quando l'utente inserisce testo in un input e premi 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	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. In questo oggetto evento puoi inserire informazioni facoltative sui parametri.
setComposeAction()	L'utente fa clic sul widget	CardAction Image ImageButton DecoratedText TextButton	specifici per Gmail. Imposta un Action che crea una bozza di email e poi 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 della creazione di bozze, 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 se devono essere eseguite altre azioni prima dell'apertura del link; altrimenti, in genere è più semplice usare setOpenLink(). Puoi aprire l'URL solo in una nuova finestra. Quando è chiuso, puoi fare in modo che la UI ricarichi il 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, altrimenti usa setOnClickOpenLinkAction(). Puoi aprire l'URL in una nuova finestra o in un overlay. Quando è chiuso, puoi fare in modo che la UI ricarichi il componente aggiuntivo.
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 un widget di input di testo. Il gestore passa automaticamente un oggetto evento alla funzione che chiama. Per ulteriori dettagli, consulta i suggerimenti di completamento automatico per gli input di testo.

Funzioni di callback

Le funzioni di callback vengono eseguite quando si attiva un Action. Poiché le funzioni di callback sono funzioni di Apps Script, puoi fare in modo che eseguano quasi qualsiasi altra funzione di script.

Avviso: il servizio schede di Apps Script limita le funzioni di callback a un massimo di 30 secondi di tempo di esecuzione. Se l'esecuzione richiede più tempo, la UI del componente aggiuntivo potrebbe non aggiornare correttamente la visualizzazione della scheda in risposta al Action.

Una funzione di callback a volte restituisce un oggetto di risposta specifico. Questi tipi di risposte indicano operazioni aggiuntive che devono essere eseguite al termine dell'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, puoi 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 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 di azioni che possono essere intraprese solo in quell'host. Per maggiori dettagli, consulta le seguenti guide:

• Azioni calendario
• Azioni di Drive
• Azioni di Gmail
• Azioni dell'editor

Nota: quando utilizzi le classi del generatore di risposte, assicurati di chiamare build() per produrre gli oggetti di risposta. Se non lo fai, si verifica un errore.

Nota: le azioni universali sono definite nel manifest del progetto e non hanno bisogno di oggetti Action, ma le loro funzioni di callback devono restituire un valore UniversalActionResponse.

Oggetti di eventi di azione

Quando il componente aggiuntivo attiva un Action, la UI genera 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 attuali di tutti i widget interattivi nella scheda visualizzata.

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

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

Nota: i componenti aggiuntivi di Gmail utilizzavano una versione semplificata di questa struttura di oggetti evento, che ora è deprecata. Per la compatibilità con le versioni precedenti, tutti i campi degli oggetti evento originali dei componenti aggiuntivi di Gmail sono ancora contenuti nella nuova struttura degli oggetti evento (vedi la struttura degli oggetti evento). Tuttavia, le stesse informazioni vengono riprodotte nelle sottostrutture degli oggetti evento comune e evento Gmail. Se esegui l'upgrade di un componente aggiuntivo di Gmail a un componente aggiuntivo di Google Workspace, devi modificare il codice per utilizzare i campi aggiornati degli oggetti evento. Alla fine, i campi originali degli oggetti evento di Gmail verranno rimossi.