Navigazione schede

La maggior parte dei componenti aggiuntivi basati su schede viene creata utilizzando schede che rappresentano "pagine" diverse del l'interfaccia del componente aggiuntivo. Per un'esperienza utente efficace, devi utilizzare una navigazione semplice e naturale tra le schede del componente aggiuntivo.

Originariamente nei componenti aggiuntivi di Gmail, le transizioni tra le diverse schede dell'interfaccia utente gestite spostando e spostando le schede da e verso una singola pila, con scheda in alto nella pila visualizzata da Gmail.

Navigazione nella scheda della home page

Introduzione ai componenti aggiuntivi di Google Workspace home page e le schede non contestuali. Per inserire schede contestuali e non contestuali, I componenti aggiuntivi di Google Workspace hanno un stack di schede interno per ciascuna. All'apertura di un componente aggiuntivo in un host, viene attivato il valore homepageTrigger corrispondente per creare il primo scheda della home page sovrapposta (la scheda "home page" di colore blu scuro nello schema sotto). Se homepageTrigger non è definito, viene creata, visualizzata una scheda predefinita ed eseguire il push sullo stack non contestuale. Questa prima scheda è una scheda principale.

Il componente aggiuntivo può creare altre schede non contestuali e inviarle alla (le "schede blu" nel diagramma) mentre l'utente esplora il componente aggiuntivo. L'interfaccia utente del componente aggiuntivo mostra la prima scheda nell'elenco, quindi il push di nuove la visualizzazione delle schede nella pila cambia, mentre se le rimuovi dalla pila, la visualizzazione alle schede precedenti.

Se per il componente aggiuntivo hai definito attivatore contestuale, quando l'utente inserisce quel contesto, l'attivatore si attiva. La funzione trigger crea la scheda contestuale, ma la visualizzazione della UI viene aggiornata in base DisplayStyle della nuova carta:

  • Se DisplayStyle è REPLACE (valore predefinito), la scheda contestuale (l'arancione scuro) "contestuale" scheda nello schema) sostituisce lo stato attuale scheda visualizzata. In questo modo, viene creata una nuova pila di schede contestuali in alto dell'insieme di schede non contestuali e questa scheda contestuale è la principale scheda dello stack contestuale.
  • Se DisplayStyle è PEEK, l'interfaccia utente crea invece un'intestazione che appare in corrispondenza in fondo alla barra laterale del componente aggiuntivo, sovrapposta alla scheda corrente. L'intestazione Anteprima mostra il titolo della nuova scheda e fornisce i controlli per i pulsanti utente che consentono decidono se visualizzare o meno la nuova scheda. Se fa clic sul pulsante Visualizza la carta sostituisce quella corrente (come descritto sopra con REPLACE).

Puoi creare schede contestuali aggiuntive inseriscile nella pila (le "carte spinte" gialle nel diagramma). Aggiornamento la pila di schede cambia l'interfaccia utente del componente aggiuntivo in modo da visualizzare la scheda più in alto. Se l'utente lascia un contesto, le schede contestuali in pila vengono rimosse e la visualizzazione vengono aggiornati alla home page o alla scheda non contestuale più in alto.

Se l'utente inserisce un contesto che il tuo componente aggiuntivo non definisce dell'attivazione contestuale "non viene creata una nuova scheda" e la scheda corrente rimane visualizzata.

Le azioni Navigation descritti di seguito, agiscono solo su schede dello stesso contesto. ad esempio popToRoot() da una scheda contestuale mostra solo tutte le altre schede contestuali, questo non influirà sulle schede della home page.

Al contrario, il pulsante è sempre disponibile per consentire all'utente di navigare dalle schede contestuali al le schede non contestuali.

Puoi creare transizioni tra le schede aggiungendo o rimuovendo schede dalla insieme di schede. La Navigation fornisce funzioni per estrarre e mostrare le schede dagli stack. Per creare una navigazione delle schede efficace, widget per utilizzare la navigazione azioni. Puoi premere o saltare più schede contemporaneamente, ma non puoi rimuovere la scheda iniziale della home page inviato per la prima volta nello stack all'avvio del componente aggiuntivo.

Per passare a una nuova scheda in risposta a un'interazione dell'utente con un widget, segui questi passaggi:

  1. Creare un oggetto Action e associarla a un funzione di callback che definisci.
  2. Chiama il widget funzione gestore widget per impostare Action sul widget.
  3. Implementa la funzione di callback che conduce la navigazione. Questa funzione viene assegnato un oggetto evento azione come argomento e deve:
      .
    1. Crea una Navigation per definire la modifica della carta. Un singolo oggetto Navigation può contenere più passaggi di navigazione, condotti nell'ordine e vengono aggiunti all'oggetto.
    2. Crea una ActionResponse utilizzando ActionResponseBuilder e il Navigation .
    3. Restituire il modello ActionResponse

Quando crei i controlli di navigazione, utilizzi: Funzioni oggetto Navigation:

Funzione Descrizione
Navigation.pushCard(Card) Invia una carta alla pila attuale. Devi prima creare la scheda completamente.
Navigation.popCard() Rimuove una carta dalla parte superiore della pila. 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 dalla pila, ad eccezione della scheda root. In pratica, reimposta la pila di schede.
Navigation.popToNamedCard(String) Scopre le carte dalla pila fino a quando non raggiunge una carta con il nome specificato o la carta principale della pila. Puoi assegnare i nomi alle schede utilizzando la funzione CardBuilder.setName(String).
Navigation.updateCard(Card) Consente di sostituire la carta corrente e di aggiornarne la visualizzazione nell'interfaccia utente.

Se un'interazione o un evento dell'utente deve comportare la visualizzazione di nuovo delle schede nello stesso il contesto, utilizza Navigation.pushCard(), Navigation.popCard(), e Navigation.updateCard() metodi per sostituire le carte esistenti. Se un'interazione utente o un evento devono far sì che le schede vengano visualizzate di nuovo in un contesto diverso, usa ActionResponseBuilder.setStateChanged() per forzare la riesecuzione del componente aggiuntivo in quei contesti.

Di seguito sono riportati alcuni esempi di navigazione:

  • Se un'interazione o un evento modifica lo stato della scheda corrente (ad esempio, aggiungi un'attività a un elenco di attività), utilizza updateCard()
  • Se un'interazione o un evento fornisce ulteriori dettagli o richiede all'utente eseguire altre azioni (ad esempio, fare clic sul titolo di un elemento per visualizzare ulteriori dettagli oppure premere un pulsante per creare un nuovo evento nel calendario), usa pushCard() per mostrare la nuova pagina e consentire all'utente di uscire dalla nuova pagina utilizzando Indietro.
  • Se un'interazione o un evento si aggiorna in una scheda precedente (ad esempio, aggiornare il titolo di un elemento con la visualizzazione dei dettagli), utilizza una formula simile popCard(), popCard(), pushCard(previous), e pushCard(current) per aggiornare la carta precedente e quella corrente.

Aggiornamento delle schede in corso...

I componenti aggiuntivi di Google Workspace offrono agli utenti la possibilità di aggiorna la scheda eseguendo di nuovo la funzione trigger di Apps Script registrata in del file manifest. Gli utenti attivano questo aggiornamento tramite un componente aggiuntivo:

Barra laterale del componente aggiuntivo di Google Workspace

Questa azione viene aggiunta automaticamente alle schede generate da homepageTrigger oppure contextualTrigger funzione di attivazione, come specificato nel file manifest del componente aggiuntivo (le "radice" degli elenchi di schede contestuali e non contestuali).

Restituzione di più carte

Esempio di scheda del componente aggiuntivo

La home page o le funzioni di trigger contestuali vengono utilizzate per creare e restituire un singolo Card o un array di Card oggetti che dell'interfaccia utente.

Se è presente una sola scheda, questa viene aggiunta all'elenco non contestuale o contestuale come scheda principale e nella UI dell'applicazione host.

Se l'array restituito include più elementi creati Card l'applicazione host visualizza invece una nuova scheda contenente dell'intestazione di ciascuna scheda. Quando l'utente fa clic su una di queste intestazioni, l'interfaccia utente mostra la scheda corrispondente.

Quando l'utente seleziona una carta dall'elenco, questa viene spostata nella lo stack attuale e l'applicazione host lo visualizza. La Il pulsante riporta l'utente allo l'elenco delle intestazioni delle schede.

Questo piatto la disposizione delle carte può funzionare bene se il componente aggiuntivo non richiede transizioni tra le schede che crei. Nella maggior parte dei casi, però, è meglio definire direttamente le transizioni delle schede e fare in modo che la home page le funzioni di attivazione contestuale restituiscono un singolo oggetto scheda.

Esempio

Ecco un esempio che mostra come creare diverse schede con gli strumenti di navigazione che consentono di passare da uno all'altro. Queste carte possono essere aggiunte stack contestuale o non contestuale tramite 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();
  }