Creazione di schede interattive

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 come pulsanti, voci di menu della barra degli strumenti o caselle di controllo per chiedere all'utente i dati di cui il componente aggiuntivo ha bisogno o fornire altri controlli di interazione.

Aggiunta di azioni ai widget

Per la maggior parte, puoi rendere interattivi i widget collegandoli a azioni specifiche e implementando il comportamento richiesto in una funzione di callback. Per maggiori dettagli, consulta le 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:

1. Crea un oggetto Action, specificando la funzione di callback da eseguire, nonché eventuali parametri obbligatori.
2. Collega il widget a Action chiamando la funzione di gestore del widget appropriata.
3. Implementa la funzione di callback per applicare il comportamento richiesto.

Esempio

Il seguente esempio imposta un pulsante che mostra una notifica all'utente dopo che è stato fatto clic. Il clic attiva la funzione di callback notifyUser() con un argomento che specifica il testo della notifica. Il ritorno di un valore ActionResponse compilato 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 schede interattive, tieni presente quanto segue:

• I widget interattivi in genere richiedono almeno un metodo di gestore per definire il loro comportamento.

• Utilizza la funzione di gestore del widget setOpenLink() quando hai un URL e vuoi semplicemente aprirlo in una scheda. In questo modo non è necessario definire un oggetto Action e una funzione di callback. Se devi prima creare l'URL o eseguire altri passaggi aggiuntivi prima di aprirlo, definisci un Action e utilizza setOnClickOpenLinkAction().

• Quando utilizzi le funzioni di gestore dei widget setOpenLink() o setOnClickOpenLinkAction(), devi fornire un oggetto OpenLink per definire l'URL da aprire. Puoi anche utilizzare questo oggetto per specificare il comportamento di apertura e chiusura utilizzando gli enum OpenAs e OnClose.

• È possibile che più widget utilizzino lo stesso oggetto Action. Tuttavia, devi definire oggetti Action diversi se vuoi fornire alla funzione di callback parametri diversi.

• Mantieni semplici le funzioni di callback. Per mantenere i componenti aggiuntivi reattivi, il servizio Scheda 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 aggiornare correttamente la visualizzazione della scheda in risposta al Action .

• Se lo stato dei dati in un backend di terze parti cambia a seguito dell'interazione di un utente con l'interfaccia utente del componente aggiuntivo, è consigliabile che il componente aggiuntivo imposti un bit "stato modificato" su true in modo che qualsiasi cache lato client esistente venga cancellata. Per ulteriori dettagli, consulta la descrizione del metodo ActionResponseBuilder.setStateChanged().