Nawigacja po kartach

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 to PEEK, 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żej REPLACE).

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:

1. Utwórz obiekt Action i powiąż go ze zdefiniowaną przez siebie funkcją wywołania zwrotnego.
2. Wywołaj odpowiednią funkcję obsługi widżetów widżetu, aby ustawić dla niego właściwość Action.
3. Zaimplementuj funkcję wywołania zwrotnego, która obsługuje nawigację. Ta funkcja otrzymuje obiekt zdarzenia działania jako argument. Musi wykonywać te czynności:
   1. Utwórz obiekt Navigation, aby zdefiniować zmianę karty. Jeden obiekt Navigation może zawierać wiele kroków nawigacyjnych, w kolejności, w jakiej są dodawane do obiektu.
   2. Utwórz obiekt ActionResponse za pomocą klasy ActionResponseBuilder i obiektu Navigation.
   3. Zwróć kompilację ActionResponse.

Uwaga: podczas poruszania się między kartami nie określasz, z którego stosu (kontekstowego lub niekontekstowego) karty zostaną dodane lub usunięte. Kontroluje to, kiedy użytkownik wchodzi w kontekst. Gdy tworzysz dodatek, dokładnie przetestuj nawigację po karcie, w tym zmiany kontekstu, aby zadbać o wygodę użytkowników.

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) i pushCard(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();
  }