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 durch Drücken und Zerlegen von Karten in einen einzelnen Kartenstapel und mit dem 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
(Standardeinstellung), 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 durchREPLACE
.
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 zum Übertragen und Herausnehmen von Karten aus den Stacks bereit. 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:
Action
-Objekt erstellen und es mit einer Callback-Funktion die Sie definieren.- Rufen Sie den entsprechenden
Widget-Handler-Funktion
um
Action
für dieses Widget festzulegen. - 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>
Navigation
erstellen zum Definieren der Kartenänderung. Ein einzelnesNavigation
-Objekt kann enthalten mehrere Navigationsschritte, die der Reihe nach durchgeführt werden. werden sie dem Objekt hinzugefügt.ActionResponse
erstellen mithilfe der MethodeActionResponseBuilder
Klasse und derNavigation
-Objekt enthält.- Build zurückgeben
ActionResponse
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)
, undpushCard(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 kontext- oder kontextbezogenen Stapel 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();
}