Większość dodatków opartych na kartach składa się z wielu kart, które reprezentują różne „strony” interfejsu dodatku. Aby zapewnić użytkownikom komfort, korzystaj z prostej i naturalnej nawigacji między kartami w dodatku.
Początkowo w dodatkach w Gmailu przejście między różnymi kartami interfejsu użytkownika odbywa się za pomocą wypchnięcia kart do i z jednego stosu, a górna karta stosu jest wyświetlana przez Gmaila.
Dodatki do Google Workspace obejmują strony główne i karty inne niż kontekstowe. Dodatki do Google Workspace mają wewnętrzny stos kart, który zawiera karty kontekstowe i niekontekstowe. Gdy dodatek jest otwarty na hoście, uruchamia się odpowiednia wersja homepageTrigger
, która tworzy pierwszą stronę główną na stosie (ciemnoniebieska karta „strona główna” na diagramie poniżej).
Jeśli nie zdefiniowano tagu homepageTrigger
, tworzona jest, wyświetlana i przekazywana na kartę domyślną. Pierwsza to karta root.
Dodatek może tworzyć dodatkowe karty inne niż kontekstowe i przenosić je na stos (niebieskie „karty push” na diagramie), gdy użytkownik porusza się po nim. Interfejs dodatku wyświetla u góry kartę, więc przesuwanie nowych kart do stosu powoduje zmianę wyświetlacza, a zamykanie kart poza stos przywraca poprzedni ekran.
Jeśli dodatek ma zdefiniowaną regułę kontekstową, gdy użytkownik wpisze ten kontekst, uruchomi regułę. Funkcja aktywatora tworzy kartę kontekstową, ale widok interfejsu jest aktualizowany na podstawie DisplayStyle
nowej karty:
- Jeśli
DisplayStyle
ma wartośćREPLACE
(domyślną), karta kontekstowa (ciemna pomarańczowa "kontekst" na diagramie) zastępuje obecnie wyświetlaną kartę. W ten sposób na wierzchu tego kontekstu pojawia się nowy stos kart kontekstowych, a ta karta kontekstowa jest kartą główną stosu kontekstowego. - Jeśli
DisplayStyle
toPEEK
, interfejs tworzy zajawek nagłówka u dołu paska bocznego dodatku, który nakłada się na bieżącą kartę. Podgląd nagłówka zawiera tytuł nowej karty i elementy sterujące, które pozwalają użytkownikowi zdecydować, czy chce wyświetlić nową kartę. Gdy użytkownik kliknie przycisk Wyświetl, zastąpi ona bieżącą kartę (zgodnie z opisem powyżejREPLACE
).
Możesz utworzyć dodatkowe karty kontekstowe i umieścić je na stosie (żółte „karty wypchnięte” na diagramie). Zaktualizowanie stosu kart powoduje zmianę interfejsu dodatku, aby wyświetlić kartę najwyższego poziomu. Jeśli użytkownik opuści kontekst, karty kontekstowe zostaną usunięte, a ekran pojawi się na samej górze strony lub na samej górze.
Jeśli użytkownik wpisze kontekst, dla którego dodatek nie definiuje reguły kontekstowej, nowa karta nie zostanie utworzona, a bieżąca karta pozostanie.
Działania opisane poniżej Navigation
działają tylko na kartach z tego samego kontekstu. Na przykład działanie popToRoot()
z karty kontekstowej powoduje wyświetlenie tylko wszystkich innych kart kontekstowych i nie ma wpływu na karty na stronie głównej.
Z kolei przycisk
jest zawsze dostępny dla użytkowników do przejścia z kart kontekstowych na karty inne niż kontekstowe.Metody nawigacji
Przejścia między kartami możesz tworzyć, dodając lub usuwając karty w stosach kart. Klasa Navigation
udostępnia funkcje push i wyskakujące karty ze stosów. Aby skutecznie poruszać się po kartach, musisz skonfigurować swoje widżety. Możesz wypchnąć wiele kart jednocześnie lub wypychać je, ale nie możesz usunąć początkowej karty strony głównej, która jako pierwsza zostanie wkładana w stos po uruchomieniu dodatku.
Aby przejść do nowej karty w odpowiedzi na interakcję użytkownika z widżetem, wykonaj te czynności:
- Utwórz obiekt
Action
i powiąż go ze zdefiniowaną przez siebie funkcją wywołania zwrotnego. - Wywołaj odpowiednią funkcję obsługi widżetów widżetu, aby ustawić dla niego właściwość
Action
. - Zaimplementuj funkcję wywołania zwrotnego, która obsługuje nawigację. Ta funkcja otrzymuje obiekt zdarzenia działania
jako argument. Musi wykonywać te czynności:
- Utwórz obiekt
Navigation
, aby zdefiniować zmianę karty. Jeden obiektNavigation
może zawierać wiele kroków nawigacyjnych, w kolejności, w jakiej są dodawane do obiektu. - Utwórz obiekt
ActionResponse
za pomocą klasyActionResponseBuilder
i obiektuNavigation
. - Zwróć kompilację
ActionResponse
.
- Utwórz obiekt
Podczas tworzenia elementów sterujących nawigacją używasz tych funkcji obiektów Navigation
:
Funkcja | Opis |
---|---|
Navigation.pushCard(Card) |
Umieszcza kartę na bieżącym stosie. Wymaga to wcześniejszego utworzenia karty. |
Navigation.popCard() |
Usuwa 1 kartę z góry stosu. Odpowiednik kliknięcia strzałki wstecz w wierszu nagłówka dodatku. Nie spowoduje to usunięcia kart głównych. |
Navigation.popToRoot() |
Usuwa z karty wszystkie karty oprócz karty głównej. Zasadniczo resetuje stos kart. |
Navigation.popToNamedCard(String) |
Wyskakuje karty ze stosu, aż osiągnie kartę o danej nazwie lub głównej karcie. Nazwy możesz przypisywać do kart za pomocą funkcji CardBuilder.setName(String) . |
Navigation.updateCard(Card) |
Zastępuje bieżącą kartę, zastępując ją bieżącą. |
Sprawdzona metoda nawigacji
Jeśli interakcja lub zdarzenie użytkownika powinno spowodować ponowne renderowanie kart w tym samym kontekście, użyj metod Navigation.pushCard()
, Navigation.popCard()
i Navigation.updateCard()
, aby zastąpić istniejące karty. Jeśli interakcja lub zdarzenie użytkownika powinno spowodować ponowne renderowanie kart w innym kontekście, użyj narzędzia ActionResponseBuilder.setStateChanged()
, aby wymusić ponowne wykonanie dodatku w tym kontekście.
Oto przykłady nawigacji:
- Jeśli interakcja lub zdarzenie powoduje zmianę stanu bieżącej karty (np. dodanie zadania do listy zadań), użyj
updateCard()
. - Jeśli interakcja lub zdarzenie zawiera dalsze szczegóły lub prosi użytkownika o wykonanie dalszych czynności (na przykład kliknięcie tytułu elementu w celu wyświetlenia dalszych informacji lub naciśnięcie przycisku w celu utworzenia nowego wydarzenia w Kalendarzu), za pomocą przycisku
pushCard()
może wyświetlić nową stronę, jednocześnie umożliwiając użytkownikowi opuszczenie nowej strony za pomocą przycisku Wstecz. - Jeśli interakcja lub zdarzenie aktualizacji jest zakończone na poprzedniej karcie (na przykład zaktualizowanie tytułu elementu w widoku szczegółowym), użyj wartości
popCard()
,popCard()
,pushCard(previous)
ipushCard(current)
, aby zaktualizować poprzednią kartę i obecną.
Odświeżam karty
Dodatki do Google Workspace umożliwiają użytkownikom odświeżanie karty przez ponowne uruchomienie funkcji aktywatora Apps Script zarejestrowanego w pliku manifestu. Użytkownicy uruchamiają to odświeżanie za pomocą elementu menu w dodatku:
To działanie jest automatycznie dodawane do kart wygenerowanych przez funkcje aktywujące homepageTrigger
lub contextualTrigger
, jak określono w pliku manifestu dodatku („katalogi główne” kontekstowych i niezwiązanych z kontekstem stosów kart).
Zwracanie wielu kart
Strona główna lub funkcje kontekstowej służą do kompilowania i zwracania pojedynczego obiektu Card
lub tablicy obiektów Card
wyświetlanych w interfejsie aplikacji.
Jeśli masz tylko jedną kartę, jest ona dodawana do stosu niekontekstowego lub kontekstowego jako karta główna, a interfejs użytkownika jej hostuje.
Jeśli zwrócona tablica zawiera więcej niż jeden utworzony obiekt Card
, aplikacja hostująca wyświetli nową kartę, która zawiera listę nagłówków każdej karty. Gdy użytkownik kliknie dowolny z tych nagłówków, w interfejsie wyświetli się odpowiednia karta.
Gdy użytkownik wybierze kartę z listy, zostanie ona przeniesiona do bieżącego stosu, a aplikacja hostująca ją wyświetli. Przycisk
zwraca użytkownika na listę nagłówków karty.Ten „płaski” układ kart sprawdzi się, jeśli dodatek nie wymaga przejścia między utworzonymi kartami. W większości przypadków jednak zalecane jest bezpośrednie zdefiniowanie przejść z jednej karty na inną, a funkcja strony głównej i kontekstu wywołująca pojedynczy obiekt karty.
Przykład
Oto przykład, który pokazuje, jak utworzyć kilka kart z przyciskami nawigacyjnymi, które się między nimi przełączają. Karty te można dodać do stosu kontekstowego lub bez kontekstu, przesuwając kartę zwracaną przez createNavigationCard()
w określonym kontekście lub poza nim.
/**
* 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();
}