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 carte, puoi usare widget interattivi come pulsanti, voci di menu della barra degli strumenti o caselle di controllo per chiedere all'utente i dati che il tuo componente aggiuntivo o fornire altri controlli di interazione.

Aggiungere azioni ai widget

Per la maggior parte, si rendono interattivi i widget collegandoli a azioni specifiche e implementazione del comportamento richiesto in un callback personalizzata. Per informazioni dettagliate, vedi le azioni dei componenti aggiuntivi.

Nella maggior parte dei casi, puoi seguire questa procedura generale per configurare un widget eseguire un'azione specifica quando viene selezionata o aggiornata:

1. Crea un oggetto Action, che specifica la funzione di callback da eseguire, insieme a parametri obbligatori.
2. Collega il widget a Action chiamando il metodo funzione di gestore widget.
3. Implementare la funzione di callback. per mettere in atto il comportamento richiesto.

Esempio

L'esempio seguente imposta un pulsante che visualizza 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. Restituzione di un modello ActionResponse determina 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:

• Di solito, i widget interattivi richiedono almeno un metodo di gestore per definirne comportamento degli utenti.

• Utilizzare il widget setOpenLink() quando hai un URL e vuoi aprirlo in una scheda. In questo modo non è necessario definire Oggetto Action e callback personalizzata. Se devi prima creare l'URL o eseguire altre passaggi prima di aprire l'URL, definisci Action e utilizza setOnClickOpenLinkAction() .

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

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

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

• Se uno stato dei dati su un backend di terze parti cambia a seguito di un interazione con l'interfaccia utente del componente aggiuntivo, è consigliabile impostare uno "stato modificato" bit in true, in modo che l'eventuale cache lato client esistente cancellato. Consulta le ActionResponseBuilder.setStateChanged() per ulteriori dettagli.