Azioni componenti aggiuntivi

Le azioni dei componenti aggiuntivi forniscono un comportamento interattivo 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 Action forniti dal servizio di carte di Apps Script. Ogni Action è associato a una funzione di callback quando la crei. Implementi la funzione di callback per eseguire i passaggi desiderati quando l'utente interagisce con il widget. Devi inoltre collega Action al widget utilizzando una funzione di gestore widget appropriata che definisce il tipo di interazione che attiva Chiamata di Action.

Configurare un widget con una Action utilizzando questa procedura generale:

1. Crea l'oggetto Action, che specifichi la funzione di callback insieme ai parametri di cui ha bisogno.
2. Chiamare la funzione di gestore widget appropriata. sul widget utilizzando Action .
3. Implementa la funzione di callback per applicare il comportamento richiesto.

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

Funzioni gestore widget

Per collegare un widget a una Action specifica o in un altro comportamento, usi un widget di Google Cloud. La funzione gestore determina il tipo di interazione (ad esempio, facendo clic sul widget o modificando un campo di testo) attiva la comportamento dell'azione. La funzione gestore definisce anche i passaggi eseguiti dall'interfaccia utente, se presente, al termine dell'azione.

Nella tabella seguente sono elencati i diversi tipi di gestori dei widget e i 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 come quando l'utente inserisce testo in un input e preme Invio. La trasmette automaticamente oggetto evento alla funzione che chiama. In questo oggetto evento puoi inserire ulteriori informazioni sui parametri se lo desideri.
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. La trasmette automaticamente 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 la presenta all'utente in un Finestra di composizione nell'interfaccia utente di Gmail. Puoi creare la bozza come nuovo messaggio o rispondi al messaggio aperto in Gmail. Quando il gestore chiama funzione di callback di creazione di bozze, passa oggetto evento alla funzione di callback. Consulta Scrivere bozze di messaggi per ulteriori dettagli.
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 l'URL, altrimenti le altre azioni devono essere eseguite prima del collegamento si apre; altrimenti è di solito più semplice usare setOpenLink(). Puoi aprire l'URL solo in una nuova finestra. Quando è chiuso, puoi causare UI per 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. Usa questa 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 chiuso, può causare il ricaricamento del componente aggiuntivo nell'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 una widget per l'inserimento di testo. Il gestore trasmette automaticamente oggetto evento alla funzione che chiama. Consulta Suggerimenti di completamento automatico per gli input di testo per ulteriori dettagli.

Funzioni di callback

Le funzioni di callback vengono eseguite quando una Action trigger. Poiché le funzioni di callback sono funzioni Apps Script, puoi utilizzarle consente di fare quasi tutto ciò che può fare qualsiasi altra funzione di script.

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

.

Una funzione di callback a volte restituisce un oggetto di risposta specifico. Questi i tipi di risposta indicano operazioni aggiuntive che devono essere eseguite dopo termina l'esecuzione del callback, ad esempio mostrando una nuova scheda o presentando suggerimenti di completamento automatico. Quando la funzione di callback deve restituire uno specifico , utilizzi una classe builder nel servizio Card per creare quell'oggetto.

La tabella seguente mostra quando le funzioni di callback devono restituire un specifico per azioni specifiche. Queste azioni sono tutte Indipendentemente 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 azioni che possono essere eseguite solo nell'host. Per maggiori dettagli, consulta le seguenti risorse: 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() a produrre gli oggetti di risposta. Se non lo fai, verrà visualizzato un errore.

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

Oggetti di eventi di azione

Quando il componente aggiuntivo attiva una Action, la UI genera automaticamente un oggetto evento JSON e lo passa come al callback Action personalizzata. Questo oggetto evento contiene informazioni sulla configurazione attuale contesto lato client, come i valori correnti di tutte le widget nella scheda visualizzata.

Gli oggetti di eventi azione hanno una struttura JSON specifica che organizza le informazioni che contengono. La stessa struttura viene utilizzata quando attivatore home page viene attivata per creare una home page oppure quando attivatore contestuale per aggiornare il display del componente aggiuntivo.

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

Nota: i componenti aggiuntivi di Gmail utilizzavano una versione semplificata di questa struttura di oggetti evento. che ora è deprecato. Per la compatibilità con le versioni precedenti, I campi degli oggetti dell'evento dei componenti aggiuntivi di Gmail sono ancora contenuti nel nuovo evento (vedi struttura dell'oggetto evento). Tuttavia, le stesse informazioni vengono riprodotte evento comune e un evento di Gmail le sottostrutture degli oggetti. Se esegui l'upgrade di un componente aggiuntivo di Gmail in un Google Workspace, devi modificare il codice per utilizzare i campi degli oggetti evento aggiornati, alla fine la versione originale i campi degli oggetti evento verranno rimossi.