Creare schede interattive

Oltre alla presentazione dei dati, la maggior parte dei componenti aggiuntivi richiede all'utente di inserire informazioni. Quando crei un componente aggiuntivo basato su schede, puoi utilizzare widget interattivi, ad esempio pulsanti, voci di menu della barra degli strumenti o caselle di controllo, per richiedere all'utente i dati necessari per il tuo componente aggiuntivo o per fornire altri controlli di interazione.

Aggiunta di azioni ai widget

Nella maggior parte dei casi, i widget sono interattivi collegandoli ad azioni specifiche e implementando il comportamento richiesto in una funzione di callback. Per informazioni dettagliate, vedi Azioni aggiuntive.

Nella maggior parte dei casi, puoi seguire questa procedura generale per configurare un widget affinché esegua un'azione specifica quando viene selezionato o aggiornato:

  1. Creare un oggetto Action, specificando la funzione di callback da eseguire, insieme a eventuali parametri obbligatori.
  2. Collega il widget alla Action chiamando la funzione gestore di widget appropriata.
  3. Implementare la funzione di callback per implementare il comportamento richiesto.

Esempio

L'esempio seguente imposta un pulsante che mostra una notifica utente dopo aver fatto clic. Il clic attiva la funzione di callback notifyUser() con un argomento che specifica il testo della notifica. La restituzione di una risorsa ActionResponse creata genera una notifica visualizzata.

  /**
   * 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)
            .setType(CardService.NotificationType.INFO))
        .build();      // Don't forget to build the response!
  }

Progetta interazioni efficaci

Quando progetti le schede interattive, tieni presente quanto segue:

  • In genere, i widget interattivi richiedono almeno un metodo per gestire il comportamento.

  • Utilizza la funzione gestore di widget setOpenLink() quando hai un URL e vuoi aprirlo in una scheda. Ciò evita la necessità di definire un oggetto Action e una funzione di callback. Se devi creare l'URL prima o eseguire altri passaggi aggiuntivi prima di aprirlo, definisci un Action e utilizza invece setOnClickOpenLinkAction().

  • Quando utilizzi le funzioni del gestore di widget setOpenLink() o setOnClickOpenLinkAction(), devi fornire un oggetto OpenLink per definire quale URL aprire. Puoi utilizzare questo oggetto anche per specificare il comportamento di apertura e chiusura tramite le enumerazioni di OpenAs e OnClose.

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

  • Le funzioni di callback devono essere semplici. Per mantenere reattivi i componenti aggiuntivi, il servizio di schede limita le funzioni di callback a un massimo di 30 secondi di tempo di esecuzione. Se l'esecuzione richiede più tempo, l'UI del componente aggiuntivo potrebbe non aggiornare correttamente la visualizzazione della scheda in risposta a Action .

  • Se uno stato dei dati su un backend di terze parti cambia in seguito a un'interazione dell'utente con la tua UI, ti consigliamo di impostare un bit "Stato modificato" su true in modo che la cache lato client esistente venga cancellata. Per ulteriori dettagli, consulta la descrizione del metodo ActionResponseBuilder.setStateChanged().