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 azioni aggiuntive utilizzando gli oggetti Action forniti dal servizio schede di Apps Script. Ogni 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 inoltre collegare Action al widget utilizzando una funzione di gestore del widget appropriata che definisca 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 che deve eseguire insieme ai parametri richiesti.
2. Richiama la funzione gestore 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 di 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 Action o a un altro comportamento, puoi utilizzare una funzione di gestione dei widget. La funzione gestore determina il tipo di interazione (ad esempio, clic sul widget o 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.

La seguente tabella elenca i diversi tipi di gestori per i 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 valore Action che esegue una funzione Apps Script quando il widget perde lo stato attivo, ad esempio quando l'utente inserisce un 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 sul parametro.
setComposeAction()	L'utente fa clic sul widget	CardAction Image ImageButton DecoratedText TextButton	Specifico per Gmail. Imposta un valore 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 bozza, passa un oggetto evento alla funzione di callback. Per ulteriori dettagli, consulta 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, di solito è più semplice utilizzare setOpenLink(). Puoi aprire l'URL solo in una nuova finestra. Una volta chiusa, la UI può ricaricare 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. Una volta chiusa, la UI può ricaricare il componente aggiuntivo.
setSuggestionsAction()	L'utente inserisce del testo in un input	TextInput	Imposta un valore Action che esegue una funzione di Apps Script quando l'utente inserisce un testo in un widget di immissione 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 elemento Action. Poiché le funzioni di callback sono funzioni di Apps Script, puoi farle svolgere quasi tutto ciò che può fare 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 delle schede 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 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 risposta specifico, utilizza una classe builder in Card service per costruire quell'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 estesa dal componente aggiuntivo:

Azione tentata	La funzione di callback deve restituire
Navigare tra le schede	ActionResponse
Mostra un Notification	ActionResponse
Apri un link utilizzando setOnClickOpenLinkAction().	ActionResponse
Mostra suggerimenti di completamento automatico	SuggestionResponse
Utilizzare un'azione universale	UniversalActionResponse
Altre azioni	Niente

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

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

Nota: quando utilizzi le classi del generatore di risposte, assicurati di chiamare build() per generare gli oggetti di risposta. In caso contrario verrà visualizzato 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 UniversalActionResponse.

Oggetti evento azione

Quando il componente aggiuntivo attiva un elemento 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 attuale dell'utente, come 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 che contengono. La stessa struttura viene utilizzata quando un attivatore della home page si attiva per creare una home page oppure quando si attiva un attivatore contestuale per aggiornare la visualizzazione del componente aggiuntivo.

Consulta la sezione 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 garantire la compatibilità con le versioni precedenti, tutti i campi degli oggetti evento relativi ai componenti aggiuntivi di Gmail originali sono ancora contenuti nella nuova struttura degli oggetti evento (vedi struttura degli oggetti evento). Tuttavia, le stesse informazioni vengono riprodotte nelle sottostrutture degli oggetti evento comune ed evento Gmail. Se stai eseguendo l'upgrade di un componente aggiuntivo di Gmail a un componente aggiuntivo di Google Workspace, devi modificare il codice in modo che utilizzi i campi degli oggetti evento aggiornati: alla fine i campi degli oggetti evento di Gmail originali verranno rimossi.