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 Action oggetti forniti dal servizio di schede di Google Apps Script. Ogni Action è associata a una funzione di callback quando la crei. Implementa la funzione di callback per eseguire i passaggi selezionati quando l'utente interagisce con il widget. Devi anche collegare il Action al widget utilizzando una funzione di gestione dei widget appropriata che definisce il tipo di interazione che attiva il Action callback.

Per configurare un widget con un Action:

  1. Crea l'Action oggetto, specificando la funzione di callback che deve 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.

Non confondere gli Action oggetti con gli CardAction oggetti. CardAction gli oggetti sono voci di menu dell'intestazione della scheda, mentre Action gli oggetti definiscono le risposte alle interazioni dell'utente con l'interfaccia utente.

Funzioni di gestione dei widget

Per collegare un widget a un Action 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 eseguiti dall'interfaccia utente, se presenti, 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 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 testo in un input e preme Invio. Il gestore passa automaticamente un oggetto di eventi alla funzione che chiama. Se selezionato, puoi inserire ulteriori informazioni sui parametri in questo oggetto di eventi.
setOnClickAction L'utente fa clic sul widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Imposta un'azione Action che esegue una funzione Apps Script quando l'utente fa clic sul widget. Il gestore passa automaticamente un oggetto di eventi alla funzione che chiama. Puoi inserire informazioni sui parametri facoltative in questo oggetto di eventi.
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 per la creazione della bozza, passa un oggetto di eventi alla funzione di callback. Per maggiori dettagli, vedi Creare bozze di messaggi.
setOnClickOpenLinkAction L'utente fa clic sul widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Imposta un'azione 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. Una volta chiusa, 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; in caso contrario, utilizza setOnClickOpenLinkAction. Puoi aprire l'URL in una nuova finestra o in una sovrapposizione. Una volta chiusa, puoi fare in modo che l'interfaccia utente ricarichi il componente aggiuntivo.
setSuggestionsAction L'utente inserisce 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 di eventi alla funzione che chiama. Per maggiori dettagli, vedi Suggerimenti per il completamento automatico per gli input di testo.

Funzioni di callback

Le funzioni di callback vengono eseguite quando viene attivata un Action. Poiché le funzioni di callback sono funzioni Apps Script, puoi farle eseguire quasi tutte le operazioni che può eseguire 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 callback, ad esempio la visualizzazione di una nuova scheda o la presentazione di suggerimenti per il completamento automatico. Quando la funzione di callback deve restituire un oggetto di risposta specifico, utilizza una classe di creazione nel servizio di 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 indipendenti dall'applicazione host specifica che il componente aggiuntivo sta estendendo:

Azione tentata La funzione di callback deve restituire
Navigare ActionResponse
Visualizzare una Notification ActionResponse
Aprire un link utilizzando setOnClickOpenLinkAction ActionResponse
Visualizzare i suggerimenti per il 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 nell'host. Per maggiori dettagli, consulta le guide seguenti:

Quando utilizzi le classi di creazione delle risposte, chiama il metodo build per produrre gli oggetti di risposta. In caso contrario, si verifica un errore.

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

Oggetti di eventi di azioni

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

Gli oggetti di eventi di azioni hanno una struttura JSON specifica che organizza le informazioni che contengono. La stessa struttura viene utilizzata quando viene attivato un trigger della home page per creare una home page o quando viene attivato un trigger contestuale per aggiornare la visualizzazione del componente aggiuntivo.

Per una spiegazione completa della struttura dell'oggetto di eventi, vedi Oggetti di eventi per una completa spiegazione.

I componenti aggiuntivi di Gmail utilizzavano una versione semplificata di questa struttura di oggetti di eventi, che ora è obsoleta. Per la compatibilità con le versioni precedenti, tutti i campi dell'oggetto di eventi dei componenti aggiuntivi di Gmail originali sono ancora contenuti nella nuova struttura dell'oggetto di eventi (vedi Struttura dell'oggetto di eventi). Tuttavia, le stesse informazioni vengono riprodotte nelle sottostrutture dell'oggetto di eventi commonEventObject e Gmail. Se stai eseguendo l'upgrade di un componente aggiuntivo di Gmail a un componente aggiuntivo di Google Workspace, modifica il codice in modo da utilizzare i campi dell'oggetto di eventi aggiornati. Alla fine, i campi dell'oggetto di eventi di Gmail originali verranno rimossi.