Navigazione tra le schede

La maggior parte dei componenti aggiuntivi basati su schede è costituita da più schede che rappresentano differenti ##39;pagine' dell'interfaccia dei componenti aggiuntivi. Per un'esperienza utente efficace, devi utilizzare una navigazione semplice e naturale tra le schede nel componente aggiuntivo.

Originariamente nei componenti aggiuntivi di Gmail, le transizioni tra le diverse schede dell'interfaccia utente vengono gestite eseguendo il push e il popping delle schede da e verso un singolo stack di schede, con la scheda superiore dello stack visualizzata da Gmail.

Navigazione nella scheda della home page

Google Workspace I componenti aggiuntivi introducono le home page e le schede non contestuali. Per gestire le schede contestuali e non contestuali, iGoogle Workspace componente aggiuntivo hanno uno stack di schede interno per ognuna. Quando un componente aggiuntivo viene aperto in un host, il homepageTrigger corrispondente viene attivato per creare la prima scheda della home page sullo stack (la scheda blu "home page" nel diagramma seguente). Se un homepageTrigger non è definito, viene creata, visualizzata e inviata una scheda predefinita nello stack non contestuale. Questa prima scheda è una root.

Il tuo componente aggiuntivo può creare ulteriori schede non contestuali e spingerle sullo stack (le carte blu di cui è stato eseguito il push nel diagramma) mentre l'utente naviga nel componente aggiuntivo. L'interfaccia utente aggiuntiva mostra la scheda superiore nello stack, quindi il push di nuove schede allo stack cambia la visualizzazione e il pop-out delle schede sullo stack restituisce la visualizzazione alle schede precedenti.

Se il componente aggiuntivo ha un attivatore contestuale definito, quando l'utente inserisce il contesto in cui si attiva l'attivatore. La funzione trigger crea la scheda contestuale, ma la visualizzazione dell'interfaccia utente viene aggiornata in base alla DisplayStyle della nuova scheda:

  • Se DisplayStyle è REPLACE (impostazione predefinita), la scheda contestuale (la scheda arancione scuro) e la scheda attualmente mostrata nel diagramma sostituiscono la scheda attualmente visualizzata. Di fatto, viene avviato un nuovo stack di schede contestuali oltre a quello dello stack delle schede non contestuali, che è la scheda root dello stack contestuale.
  • Se la DisplayStyle è PEEK, l'interfaccia utente crea invece un'intestazione che viene visualizzata nella parte inferiore della barra laterale dei componenti aggiuntivi, sovrapponendosi alla scheda corrente. L'intestazione di anteprima mostra il titolo della nuova scheda e fornisce i controlli del pulsante utente che consentono di decidere se visualizzare o meno la nuova scheda. Se fanno clic sul pulsante Visualizza, la scheda sostituisce la scheda corrente (come descritto sopra con REPLACE).

Puoi creare altre schede contestuali e inserirle nello stack (le schede gialle in precedenza) nel diagramma. L'aggiornamento dello stack di schede cambia l'interfaccia utente aggiuntiva per visualizzare la scheda principale. Se l'utente esce da un contesto, le schede contestuali nello stack vengono rimosse e la visualizzazione viene aggiornata alla home page o alla scheda non contestuale più in alto.

Se l'utente inserisce un contesto per il quale il tuo componente aggiuntivo non definisce un attivatore contestuale, non viene creata alcuna nuova scheda e la scheda corrente rimane visualizzata.

Le azioni Navigation descritte di seguito funzionano solo per le schede dello stesso contesto; ad esempio, popToRoot() all'interno di una scheda contestuale mostra solo tutte le altre schede contestuali e non influisce sulle schede della home page.

Al contrario, il pulsante è sempre disponibile per consentire all'utente di passare dalle schede contestuali alle schede non contestuali.

Puoi creare transizioni tra le schede aggiungendo o rimuovendo schede dagli stack di schede. La classe Navigation fornisce funzioni di push e pop-up delle schede, Per creare una navigazione efficace con le schede, configura i tuoi widget per l'utilizzo di azioni di navigazione. Puoi inviare o estrarre più schede contemporaneamente, ma non puoi rimuovere la scheda iniziale della home page che viene inviata innanzitutto allo stack all'avvio del componente aggiuntivo.

Per aprire una nuova scheda in risposta a un'interazione dell'utente con un widget, procedi nel seguente modo:

  1. Crea un oggetto Action e associalo a una funzione di callback da te definita.
  2. Chiama la funzione di gestione dei widget appropriata del widget per impostare il relativo Action.
  3. Implementare la funzione di callback che esegue la navigazione. A questa funzione viene assegnato un oggetto evento azione come argomento e deve:
    1. Crea un oggetto Navigation per definire la modifica della scheda. Un singolo oggetto Navigation può contenere più passaggi di navigazione, che vengono eseguiti nell'ordine in cui vengono aggiunti all'oggetto.
    2. Crea un oggetto ActionResponse utilizzando la classe ActionResponseBuilder e l'oggetto Navigation.
    3. Restituire la ActionResponse creata.

Quando crei controlli di navigazione, utilizzi le seguenti funzioni di oggetti Navigation:

Funzione Descrizione
Navigation.pushCard(Card) Esegue il push di una carta sullo stack corrente. Questo passaggio richiede la creazione completa della carta.
Navigation.popCard() Rimuove una scheda dalla parte superiore dello stack. Equivale a fare clic sulla freccia indietro nella riga di intestazione del componente aggiuntivo. Le schede principali non vengono rimosse.
Navigation.popToRoot() Rimuove tutte le schede dallo stack ad eccezione della scheda principale. Essenzialmente reimposta lo stack di schede.
Navigation.popToNamedCard(String) Consente di aprire le schede dallo stack fino a raggiungere una carta con il nome specificato o la root card dello stack. Puoi assegnare nomi alle schede utilizzando la funzione CardBuilder.setName(String).
Navigation.updateCard(Card) Sostituisce in loco la carta corrente, aggiornandone la visualizzazione nell'interfaccia utente.

Se un'interazione o un evento da parte dell'utente deve comportare il rendering delle schede nello stesso contesto, utilizza i metodi Navigation.pushCard(), Navigation.popCard() e Navigation.updateCard() per sostituire le schede esistenti. Se un'interazione o un evento da parte dell'utente deve comportare il rendering di schede in un contesto diverso, utilizza ActionResponseBuilder.setStateChanged() per forzare la nuova esecuzione del componente aggiuntivo in quei contesti.

Di seguito sono riportati alcuni esempi di navigazione:

  • Se un'interazione o un evento cambia lo stato della scheda corrente (ad esempio quando aggiungi un'attività a un elenco attività), utilizza updateCard().
  • Se un'interazione o un evento fornisce ulteriori dettagli o richiedono all'utente ulteriori azioni (ad esempio, il clic su un titolo di un elemento per visualizzare altri dettagli o la pressione di un pulsante per creare un nuovo evento di Calendar), utilizza pushCard() per visualizzare la nuova pagina, consentendo all'utente di uscire dalla nuova pagina utilizzando il pulsante Indietro.
  • Se un'interazione o uno stato di aggiornamento dell'evento in una scheda precedente (ad es. l'aggiornamento del titolo di un elemento dalla visualizzazione dei dettagli), utilizza qualcosa come popCard(), popCard(), pushCard(previous) e pushCard(current) per aggiornare la scheda precedente e la scheda corrente.

Aggiornamento delle schede

Google Workspace i componenti aggiuntivi permettono agli utenti di aggiornare la tua scheda eseguendo nuovamente la funzione di trigger di Apps Script registrata nel tuo manifest. Gli utenti attivano questo aggiornamento tramite una voce di menu aggiuntiva:

 l10n-placeholder39=  l10n-placeholder40=





Questa azione viene aggiunta automaticamente alle schede generate da homepageTrigger o contextualTrigger funzioni trigger, come specificato nel file manifest del componente aggiuntivo (le &root39 degli stack di schede contestuali e non contestuali).

Restituzione di più carte

Esempio di scheda aggiuntiva

Le funzioni di attivazione della home page o di contesto vengono utilizzate per creare e restituire un singolo oggetto Card o un array di oggetti Card visualizzati nella UI dell'applicazione.

Se c'è solo una scheda, questa viene aggiunta allo stack non contestuale o contestuale man mano che la scheda principale viene visualizzata dall'UI dell'applicazione host.

Se l'array restituito include più di un oggetto Card creato, l'applicazione host mostra invece una nuova scheda, che contiene un elenco di ogni intestazione della scheda. Quando l'utente fa clic su una di queste intestazioni, nell'interfaccia utente viene visualizzata la scheda corrispondente.

Quando l'utente seleziona una scheda dall'elenco, questa viene spinta sullo stack corrente e viene visualizzata dall'applicazione host. Il pulsante riporta l'utente all'elenco delle intestazioni della scheda.

Questa disposizione 'fissa' della carta può funzionare bene se il tuo componente aggiuntivo non ha bisogno di alcuna transizione tra le carte che crei. Nella maggior parte dei casi, tuttavia, è meglio definire direttamente le transizioni delle schede e fare in modo che la home page e le funzioni di trigger contestuale restituiscano un singolo oggetto scheda.

Esempio

Ecco un esempio che mostra come costruire diverse schede con i pulsanti di navigazione che passano da una scheda all'altra. È possibile aggiungere queste schede allo stack di contesto o non contestuale eseguendo il push della scheda restituita da createNavigationCard() all'interno o all'esterno di un determinato contesto.

  /**
   *  Create the top-level card, with buttons leading to each of three
   *  'children' cards, as well as buttons to backtrack and return to the
   *  root card of the stack.
   *  @return {Card}
   */
  function createNavigationCard() {
    // Create a button set with actions to navigate to 3 different
    // 'children' cards.
    var buttonSet = CardService.newButtonSet();
    for(var i = 1; i <= 3; i++) {
      buttonSet.addButton(createToCardButton(i));
    }

    // Build the card with all the buttons (two rows)
    var card = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader().setTitle('Navigation'))
        .addSection(CardService.newCardSection()
            .addWidget(buttonSet)
            .addWidget(buildPreviousAndRootButtonSet()));
    return card.build();
  }

  /**
   *  Create a button that navigates to the specified child card.
   *  @return {TextButton}
   */
  function createToCardButton(id) {
    var action = CardService.newAction()
        .setFunctionName('gotoChildCard')
        .setParameters({'id': id.toString()});
    var button = CardService.newTextButton()
        .setText('Card ' + id)
        .setOnClickAction(action);
    return button;
  }

  /**
   *  Create a ButtonSet with two buttons: one that backtracks to the
   *  last card and another that returns to the original (root) card.
   *  @return {ButtonSet}
   */
  function buildPreviousAndRootButtonSet() {
    var previousButton = CardService.newTextButton()
        .setText('Back')
        .setOnClickAction(CardService.newAction()
            .setFunctionName('gotoPreviousCard'));
    var toRootButton = CardService.newTextButton()
        .setText('To Root')
        .setOnClickAction(CardService.newAction()
            .setFunctionName('gotoRootCard'));

    // Return a new ButtonSet containing these two buttons.
    return CardService.newButtonSet()
        .addButton(previousButton)
        .addButton(toRootButton);
  }

  /**
   *  Create a child card, with buttons leading to each of the other
   *  child cards, and then navigate to it.
   *  @param {Object} e object containing the id of the card to build.
   *  @return {ActionResponse}
   */
  function gotoChildCard(e) {
    var id = parseInt(e.parameters.id);  // Current card ID
    var id2 = (id==3) ? 1 : id + 1;      // 2nd card ID
    var id3 = (id==1) ? 3 : id - 1;      // 3rd card ID
    var title = 'CARD ' + id;

    // Create buttons that go to the other two child cards.
    var buttonSet = CardService.newButtonSet()
      .addButton(createToCardButton(id2))
      .addButton(createToCardButton(id3));

    // Build the child card.
    var card = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader().setTitle(title))
        .addSection(CardService.newCardSection()
            .addWidget(buttonSet)
            .addWidget(buildPreviousAndRootButtonSet()))
        .build();

    // Create a Navigation object to push the card onto the stack.
    // Return a built ActionResponse that uses the navigation object.
    var nav = CardService.newNavigation().pushCard(card);
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }

  /**
   *  Pop a card from the stack.
   *  @return {ActionResponse}
   */
  function gotoPreviousCard() {
    var nav = CardService.newNavigation().popCard();
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }

  /**
   *  Return to the initial add-on card.
   *  @return {ActionResponse}
   */
  function gotoRootCard() {
    var nav = CardService.newNavigation().popToRoot();
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }