La maggior parte dei componenti aggiuntivi, oltre a presentare i dati, richiede all'utente di inserire informazioni. Quando crei un componente aggiuntivo basato su schede, puoi utilizzare widget interattivi, quali pulsanti, voci di menu della barra degli strumenti o caselle di controllo per chiedere all'utente i dati necessari al componente aggiuntivo o fornire altri controlli di interazione.
Aggiunta di azioni ai widget
Per la maggior parte, rendi i widget interattivi collegandoli a azioni specifiche e implementando il comportamento richiesto in una funzione di callback. Per informazioni dettagliate, vedi Azioni dei componenti aggiuntivi.
Nella maggior parte dei casi, puoi seguire questa procedura generale per configurare un widget in modo che esegua un'azione specifica quando viene selezionato o aggiornato:
- Crea un oggetto
Action
, specificando la funzione di callback che deve essere eseguita, insieme a tutti i parametri obbligatori. - Collega il widget a
Action
chiamando la funzione di gestore del widget appropriata. - Implementa la funzione di callback per mettere in atto il comportamento richiesto.
Esempio
L'esempio seguente imposta un pulsante che mostra una notifica per l'utente dopo il clic. Il clic attiva la funzione di callback notifyUser()
con un argomento che specifica il testo della notifica. La restituzione di un elemento ActionResponse
creato comporta la visualizzazione di una notifica.
/**
* Build a simple card with a button that sends a notification.
* @return {Card}
*/
function buildSimpleCard() {
var buttonAction = CardService.newAction()
.setFunctionName('notifyUser')
.setParameters({'notifyText': 'Button clicked!'});
var button = CardService.newTextButton()
.setText('Notify')
.setOnClickAction(buttonAction);
// ...continue creating widgets, then create a Card object
// to add them to. Return the built Card object.
}
/**
* Callback function for a button action. Constructs a
* notification action response and returns it.
* @param {Object} e the action event object
* @return {ActionResponse}
*/
function notifyUser(e) {
var parameters = e.parameters;
var notificationText = parameters['notifyText'];
return CardService.newActionResponseBuilder()
.setNotification(CardService.newNotification())
.setText(notificationText)
.build(); // Don't forget to build the response!
}
Progettare interazioni efficaci
Quando progetti le schede interattive, tieni presente quanto segue:
I widget interattivi di solito richiedono almeno un metodo di gestore per definire il loro comportamento.
Utilizza la funzione di gestione del widget
setOpenLink()
quando hai un URL e vuoi semplicemente aprirlo in una scheda. In questo modo non è necessario definire un oggettoAction
e una funzione di callback. Se devi prima creare l'URL o eseguire altri passaggi aggiuntivi prima di aprirlo, definisci unAction
e utilizza invecesetOnClickOpenLinkAction()
.Quando utilizzi le funzioni di gestore dei widget
setOpenLink()
osetOnClickOpenLinkAction()
, devi fornire un oggettoOpenLink
per definire l'URL da aprire. Puoi utilizzare questo oggetto anche per specificare il comportamento di apertura e chiusura utilizzando le enumerazioniOpenAs
eOnClose
.È possibile che più widget utilizzino lo stesso oggetto
Action
. Tuttavia, devi definire oggettiAction
diversi se vuoi fornire parametri diversi alla funzione di callback.Mantieni semplici le funzioni di callback. Per garantire la reattività dei componenti aggiuntivi, il servizio schede 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 al
Action
.Se lo stato dei dati in un backend di terze parti cambia a seguito di un'interazione dell'utente con la UI del componente aggiuntivo, è consigliabile che il componente aggiuntivo imposti il bit "Stato modificato" su
true
, in modo che l'eventuale cache lato client esistente venga cancellata. Per ulteriori dettagli, consulta la descrizione del metodoActionResponseBuilder.setStateChanged()
.