Azioni componenti aggiuntivi

Le azioni dei componenti aggiuntivi forniscono un comportamento interattivo ai widget. Quando crei 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 Action è associato a una funzione di callback al momento della creazione. Implementa la funzione di callback per eseguire i passaggi selezionati quando l'utente interagisce con il widget. Devi anche collegare Action al widget utilizzando una funzione di gestione dei widget appropriata che definisce il tipo di interazione che attiva il callback Action.

Configura un widget con un Action utilizzando questa procedura generale:

1. Crea l'oggetto Action, specificando la funzione di callback da eseguire insieme a tutti i parametri richiesti.
2. Chiama la funzione di gestione dei widget appropriata sul widget utilizzando l'oggetto Action.
3. Implementa la funzione di callback per attivare 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 utente con la UI.

Funzioni di gestione dei widget

Per collegare un widget a un Action specifico o a un altro comportamento, utilizza una funzione di gestione dei widget. La funzione di gestione 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 gestione definisce anche i passaggi che l'interfaccia utente esegue, se presenti, al termine dell'azione.

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

Funzione di gestione	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 del testo in un input e preme Invio. Il gestore passa automaticamente un oggetto evento alla funzione che chiama. Se selezionato, 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. Puoi inserire informazioni sui parametri facoltativi in questo oggetto evento.
setComposeAction()	L'utente fa clic sul widget	CardAction Image ImageButton DecoratedText TextButton	Specifico per Gmail. Imposta un Action che crea una bozza di email, quindi 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 di creazione della bozza, passa un oggetto evento alla funzione di callback. Per ulteriori dettagli, vedi Comporre messaggi in bozza.
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 che il link si apra; altrimenti, di solito è più semplice utilizzare setOpenLink(). Puoi aprire l'URL solo in una nuova finestra. Quando viene chiuso, puoi fare in modo che l'interfaccia utente 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 utilizza setOnClickOpenLinkAction(). Puoi aprire l'URL in una nuova finestra o in una sovrapposizione. Quando viene chiuso, puoi far ricaricare il componente aggiuntivo all'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 un widget di input di testo. Il gestore passa automaticamente un oggetto evento alla funzione che chiama. Per ulteriori dettagli, vedi 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 Apps Script, puoi farle fare quasi tutto ciò che può fare qualsiasi altra funzione di script.

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

A volte una funzione di callback restituisce un oggetto di risposta specifico. Questi tipi di risposte indicano operazioni aggiuntive che devono essere eseguite dopo il completamento 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, utilizzi una classe builder nel servizio di schede per costruire 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 indipendenti dall'applicazione host specifica che il componente aggiuntivo sta estendendo:

Azione tentata	La funzione di callback deve restituire
Navigare tra le schede	ActionResponse
Visualizzare un Notification	ActionResponse
Aprire un link utilizzando setOnClickOpenLinkAction()	ActionResponse
Visualizzare i suggerimenti di completamento automatico	SuggestionResponse
Utilizzare un'azione universale	UniversalActionResponse
Altre azioni	Nothing

Azioni per le applicazioni host di Google Workspace

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

• Azioni di Calendar
• Azioni chat
• Incentivare le azioni
• Azioni di Gmail
• Azioni dell'editor

Nota: quando utilizzi le classi di creazione delle risposte, assicurati di chiamare build() per produrre gli oggetti di risposta. In caso contrario, si verifica un errore.

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

Oggetti evento azione

Quando il componente aggiuntivo attiva un Action, l'interfaccia utente 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 azione hanno una struttura JSON specifica che organizza le informazioni che contengono. La stessa struttura viene utilizzata quando un attivatore della home page si attiva per creare una home page o quando un attivatore contestuale si attiva per aggiornare la visualizzazione del componente aggiuntivo.

Per una spiegazione completa della struttura dell'oggetto evento, vedi Oggetti evento.

Nota: i componenti aggiuntivi Gmail utilizzavano una versione semplificata di questa struttura dell'oggetto evento, ora ritirata. Per la compatibilità con le versioni precedenti, tutti i campi dell'oggetto evento dei componenti aggiuntivi di Gmail originali sono ancora contenuti nella nuova struttura dell'oggetto evento (vedi struttura dell'oggetto evento). Tuttavia, le stesse informazioni vengono riprodotte nelle sottostrutture degli oggetti evento comune ed 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 dell'oggetto evento aggiornati. Alla fine, i campi dell'oggetto evento di Gmail originali verranno rimossi.