Kartennavigation

Die meisten kartenbasierten Add-ons werden mit mehreren Karten, die verschiedene „Seiten“ darstellen der Add-on-Oberfläche. Für eine effektive User Experience sollten Sie in Ihrem Add-on eine einfache und natürliche Navigation zwischen den Karten verwenden.

Ursprünglich in Gmail-Add-ons sind Übergänge zwischen verschiedenen Karten der Benutzeroberfläche indem Karten in einen einzelnen Stapel geschoben und herausgenommen werden. oberste Karte des Stapels von Gmail.

Neu: Google Workspace-Add-ons Homepages und nicht kontextbezogene Karten. Damit kontextbezogene und nicht kontextbezogene Karten berücksichtigt werden, Google Workspace-Add-ons haben einen internen Kartenstapel für jedes Element. Wenn ein Add-on geöffnet wird in einem Host ausgelöst, wird die entsprechende homepageTrigger ausgelöst, um die erste Startseitenkarte im Stapel (die dunkelblaue Startseitenkarte im Diagramm unten). Wenn keine homepageTrigger definiert ist, wird eine Standardkarte erstellt und angezeigt. und auf den nicht kontextbezogenen Stack übertragen. Diese erste Karte ist eine Root-Karte.

Mit Ihrem Add-on können zusätzliche Karten ohne Kontext erstellt und auf dem Tab (die blauen „Push-Karten“ im Diagramm), während die Nutzenden für Ihr Add-on. In der Add-on-Benutzeroberfläche wird die oberste Karte im Stapel angezeigt. Karten zum Stapel ändern die Anzeige, und das Herausnehmen von Karten aus dem Stapel gibt zu den vorherigen Karten wechseln.

Wenn Ihr Add-on eine definierte kontextbezogener Trigger, wenn der Nutzer diesen Kontext eingibt, wird der Trigger ausgelöst. Die Triggerfunktion erstellt die Kontextkarte, aber die UI-Anzeige wird basierend auf dem DisplayStyle der neuen Karte:

• Wenn die DisplayStyle REPLACE (Standard), ist die Kontextkarte (die dunkelorangefarbene "kontextbezogen" im Diagramm) ersetzt die aktuelle angezeigte Karte. Dadurch wird faktisch ein neuer kontextbezogener Kartenstapel oben gestartet. des nicht kontextbezogenen Kartenstapels. Diese kontextbezogene Karte ist die Stammkarte. des kontextbezogenen Stacks.
• Wenn die DisplayStyle PEEK ist, erstellt die UI stattdessen eine Kopfzeile, die im Bereich der Add-on-Seitenleiste über der aktuellen Karte. Peek-Header zeigt den Titel der neuen Karte an und enthält Steuerelemente für die Nutzerschaltfläche, ob sie die neue Karte sehen möchten oder nicht. Wenn sie auf die Schaltfläche Anzeigen ersetzt die Karte die aktuelle Karte (wie oben beschrieben durch REPLACE.

Sie können zusätzliche Kontextkarten und und schieben Sie sie auf den Stapel (die gelben „Push-Karten“ im Diagramm). Wird aktualisiert Der Kartenstapel ändert die Add-on-UI so, dass die oberste Karte angezeigt wird. Wenn der Nutzer hinterlässt einen Kontext, werden die Kontextkarten aus dem Stapel entfernt und die Aktualisierung der wichtigsten nicht kontextbezogenen Karte oder Startseite

Wenn der Nutzer einen Kontext eingibt, der durch Ihr Add-on nicht definiert wird Kontext ausgelöst wird, wird keine neue Karte erstellt und der die aktuelle Karte angezeigt wird.

Aktionen von Navigation die nachfolgend beschriebenen Aktionen nur für Infokarten aus demselben Kontext ausführen. zum Beispiel popToRoot() Von einer Kontextkarte aus werden nur alle anderen kontextbezogenen Karten geöffnet. hat keine Auswirkungen auf Infokarten auf der Startseite.

Im Gegensatz dazu ist die Schaltfläche können Nutzer jederzeit von Ihren kontextbezogenen Karten zu Ihrem nicht kontextbezogene Karten.

Navigationsmethoden

Übergänge zwischen Infokarten kannst du erstellen, indem du Kacheln hinzufügst oder entfernst. Kartenstapel. Die Navigation -Klasse stellt Funktionen bereit, mit denen Karten per Push-Funktion aus den Stapeln entnommen werden können. Zum Erstellen effektive Kartennavigation bieten, konfigurieren Sie widgets, um die Navigation zu verwenden Aktionen. Sie können drücken oder mehrere Karten gleichzeitig, aber Sie können die erste Karte auf der Startseite nicht entfernen. die beim Start des Add-ons zuerst in den Stack verschoben wird.

Um als Reaktion auf eine Nutzerinteraktion mit einem Widget zu einer neuen Karte zu navigieren, führen Sie folgende Schritte aus:

1. Action-Objekt erstellen und es mit einer Callback-Funktion die Sie definieren.
2. Rufen Sie den entsprechenden Widget-Handler-Funktion um Action für dieses Widget festzulegen.
3. Implementieren Sie die Callback-Funktion, die die Navigation durchführt. Diese Funktion erhält ein Aktionsereignisobjekt. als Argument und muss Folgendes tun: <ph type="x-smartling-placeholder">
   </ph>
   1. Navigation erstellen -Objekt, um die Kartenänderung zu definieren. Ein einzelnes Navigation-Objekt kann enthalten mehrere Navigationsschritte, die der Reihe nach durchgeführt werden. werden sie dem Objekt hinzugefügt.
   2. ActionResponse erstellen mithilfe der Methode ActionResponseBuilder Klasse und der Navigation -Objekt enthält.
   3. Build zurückgeben ActionResponse

Hinweis: Beim Navigieren zwischen Karten wird nicht angegeben, welcher Stapel (kontextbezogene oder nicht kontextbezogen), zu denen die Infokarten hinzugefügt bzw. aus denen sie entfernt werden. Dies wird kontrolliert wenn Nutzer den Kontext betreten oder verlassen. Achten Sie beim Erstellen des Add-ons darauf, sollten Sie Ihre Kartennavigation, einschließlich Kontextänderungen, eine positive User Experience zu gewährleisten.

Beim Erstellen von Navigationssteuerelementen werden folgende Elemente verwendet: Navigation-Objektfunktionen:

Funktion	Beschreibung
Navigation.pushCard(Card)	Verschiebt eine Karte in den aktuellen Stapel. Dazu muss die Karte zuerst vollständig erstellt werden.
Navigation.popCard()	Entfernt eine Karte oben aus dem Stapel. Entspricht dem Klicken auf den Zurück-Pfeil in der Add-on-Kopfzeile. Dadurch werden keine Root-Karten entfernt.
Navigation.popToRoot()	Entfernt alle Karten mit Ausnahme der Root-Karte aus dem Stapel. Setzt diesen Kartenstapel im Wesentlichen zurück.
Navigation.popToNamedCard(String)	Karten werden so lange aus dem Stapel entfernt, bis eine Karte mit dem angegebenen Namen oder der Root-Karte des Stapels angezeigt wird. Mit der Funktion CardBuilder.setName(String) können Sie Karten Namen zuweisen.
Navigation.updateCard(Card)	Die aktuelle Karte wird direkt ersetzt und die Anzeige in der Benutzeroberfläche wird aktualisiert.

Best Practices für Navigation

Wenn eine Nutzerinteraktion oder ein Ereignis dazu führen soll, dass die Karten in derselben Kontext, verwenden Navigation.pushCard(), Navigation.popCard() und Navigation.updateCard() um die vorhandenen Karten zu ersetzen. Wenn eine Nutzerinteraktion oder ein Ereignis Karten in einem anderen Kontext erneut rendern, ActionResponseBuilder.setStateChanged() um die erneute Ausführung des Add-ons in diesen Kontexten zu erzwingen.

Im Folgenden finden Sie Beispiele für die Navigation:

• Wenn sich der Status der aktuellen Karte (z. B. einer Aufgabenliste eine Aufgabe hinzufügen), nutzen Sie updateCard()
• Wenn eine Interaktion oder ein Ereignis weitere Details liefert oder den Nutzer dazu auffordert, weitere Aktionen ausführen (z. B. auf den Titel eines Elements klicken, um weitere Details zu sehen, oder indem Sie auf eine Schaltfläche drücken, um einen neuen Kalendertermin zu erstellen, verwenden Sie pushCard() um die neue Seite anzuzeigen und es dem Nutzer zu ermöglichen, die neue Seite über die Schaltfläche „Zurück“.
• Wenn eine Interaktion oder ein Ereignis in einer vorherigen Karte aktualisiert wird (z. B. Aktualisieren des Titels eines Elements aus der Detailansicht) popCard(), popCard(), pushCard(previous), und pushCard(current) um die vorherige und die aktuelle Karte zu aktualisieren.

Karten werden aktualisiert

Mit Google Workspace-Add-ons können Nutzer Aktualisieren Sie Ihre Karte, indem Sie die Apps Script-Triggerfunktion, die in registriert ist, in deinem Manifest. Nutzer lösen diese Aktualisierung über einen Add-on-Menüpunkt aus:

Diese Aktion wird automatisch Karten hinzugefügt, die von homepageTrigger oder contextualTrigger-Triggerfunktionen, wie im Manifest Ihres Add-ons angegeben (die „Roots“ der kontextbezogenen und nicht kontextbezogenen Kartenstapel).

Rückgabe mehrerer Karten

Startseiten- oder kontextbezogene Triggerfunktionen werden verwendet, um entweder eine einzelne Card-Objekt oder ein Array von Card-Objekte, die vom wird die Benutzeroberfläche der Anwendung angezeigt.

Wenn nur eine Karte vorhanden ist, wird sie dem nicht kontextbezogenen oder kontextbezogenen Stack hinzugefügt als Root-Karte und wird von der Benutzeroberfläche der Host-Anwendung angezeigt.

Wenn das zurückgegebene Array mehr als ein erstelltes Card -Objekt enthält, zeigt die Host-Anwendung stattdessen eine neue Karte an, die ein eine Liste mit den Überschriften der einzelnen Karten. Wenn der Nutzer auf einen dieser Überschriften klickt, zeigt die entsprechende Karte an.

Wenn der Nutzer eine Karte aus der Liste auswählt, wird diese Karte auf das und die Host-Anwendung zeigt sie an. Die Über die Schaltfläche gelangt der Nutzer zurück zur Liste mit den Überschriften der Karte.

Dieser „Flach“-Ansatz Kartenanordnung kann gut funktionieren, wenn Ihr Add-on keine die Übergänge zwischen den erstellten Karten. In den meisten Fällen ist es jedoch besser, Kartenübergänge direkt definieren und Ihre Startseite und kontextabhängige Triggerfunktionen geben ein einzelnes Kartenobjekt zurück.

Beispiel

Hier ist ein Beispiel, das zeigt, wie mehrere Karten mit Navigation erstellt werden. Schaltflächen, über die Sie zwischen ihnen wechseln können. Diese Karten können entweder kontextbezogenen oder nicht kontextbezogenen Stacks durch Drücken der zurückgegebenen Karte von createNavigationCard() innerhalb oder außerhalb eines bestimmten Kontexts.

  /**
   *  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();
  }