Nawigacja na kartach

Większość dodatków opartych na kartach powstaje za pomocą karty reprezentujące różne „strony” z interfejsu dodatku. Aby zadbać o wygodę użytkowników, używaj prostej i naturalnej nawigacji między kartami w dodatku.

Początkowo w dodatkach do Gmaila przejścia między różnymi kartami w interfejsie były poprzez przesuwanie i wyskakiwanie kart do i z jednego stosu kart. górnej karty stosu wyświetlanej w Gmailu.

Dodatki do Google Workspace stron głównych, kart niezwiązanych z kontekstem. Aby uwzględnić karty kontekstowe i niekontekstowe, Dodatki do Google Workspace mają wewnętrzny stos kart dla każdej z nich. Po otwarciu dodatku na hoście, odpowiedni tag homepageTrigger uruchamia się, aby utworzyć pierwszą karta strony głównej (ciemnoniebieska karta „strona główna” na schemacie poniżej). Jeśli homepageTrigger nie jest zdefiniowany, tworzona jest karta domyślna, wyświetlana a następnie skierowaliśmy je na stos treści niekontekstowych. Pierwsza karta jest kartą root.

Dodatek może tworzyć dodatkowe karty niezwiązane z kontekstem i przekazywać je na (niebieskie „przesuwane karty” w schemacie) podczas przechodzenia użytkownika przez użytkownika. Twój dodatek. Interfejs dodatku wyświetla górną kartę na stosie, dlatego układ stosów kart zmienia sposób wyświetlania, a karty pojawiają się poza stosem. i wyświetlaj poprzednie karty.

Jeśli dodatek ma zdefiniowany regułę opartą na kontekście, gdy użytkownik wpisze ten kontekst, uruchamia się reguła. Funkcja aktywatora tworzy kartę kontekstową, ale wygląd interfejsu jest aktualizowany na podstawie DisplayStyle nowej karty:

• Jeśli DisplayStyle to REPLACE (domyślna), karta kontekstowa (ciemnopomarańczowa) „kontekstowy” na diagramie) zastępuje bieżący wyświetlanej karty. Spowoduje to rozpoczęcie tworzenia nowego stosu kart kontekstowych. w stosie kart innych niż kontekstowe, ta karta kontekstowa stanowi poziom główny stosu kontekstu.
• Jeśli DisplayStyle to PEEK, interfejs tworzy wysunięty nagłówek wyświetlany w na dole paska bocznego dodatku, nakładając na bieżącą kartę. Wgląd w nagłówek pokazuje tytuł nowej karty i zawiera przyciski użytkownika umożliwiające decydują, czy wyświetlić nową kartę. Po kliknięciu przycisku Widok spowoduje, że karta zastąpi bieżącą kartę (zgodnie z powyższym opisem REPLACE).

Możesz też tworzyć dodatkowe karty kontekstowe wepchnij je na stosy (żółte „wypchnięte karty” na schemacie). Aktualizuję stos kart zmienia interfejs dodatku tak, aby wyświetlić kartę, która znajduje się u góry. Jeśli użytkownik pozwala wyświetlić kontekst, karty kontekstowe ze stosu zostają usunięte, aktualizacje karty lub strony głównej umieszczonej najwyżej na stronie głównej.

Jeśli użytkownik wprowadzi kontekst, w którym dodatek nie definiuje tagu algorytm kontekstowy w przypadku, gdy nie jest tworzona nowa karta, a i wyświetlona.

Działania Navigation opisane poniżej działają tylko na kartach z tego samego kontekstu. np. popToRoot() z karty kontekstowej powoduje wyświetlenie tylko pozostałych kart kontekstowych, nie wpływa na karty na stronie głównej.

W przeciwieństwie do tego przycisk jest aby użytkownik mógł zawsze przejść z kart kontekstowych do kart niezwiązanych z kontekstem.

Metody nawigacji

Możesz tworzyć przejścia między kartami, dodając lub usuwając karty w stosy kart. Navigation klasa zawiera funkcje do wypychania i wysuwania kart ze stosu. Tworzenie skutecznej nawigacji po kartach, skonfigurujesz widżety – do korzystania z nawigacji. działania. Możesz push lub pop wiele kart jednocześnie, ale nie możesz usunąć pierwszej karty ze strony głównej która jest najpierw przekazywana na stos podczas uruchamiania dodatku.

Aby przejść na nową kartę w odpowiedzi na interakcję użytkownika z widżetem: wykonaj te czynności:

1. Tworzenie obiektu Action i powiąż go z tagiem funkcja wywołania zwrotnego zdefiniowanych przez reklamodawcę.
2. Wywołaj odpowiednie funkcja obsługi widżetów aby ustawić Action w tym widżecie.
3. Zaimplementuj funkcję wywołania zwrotnego, która przeprowadza nawigację. Ta funkcja otrzymuje obiekt zdarzenia akcji, jako argument i musi wykonać te czynności:
   1. Tworzenie Navigation aby zdefiniować zmianę karty. Pojedynczy obiekt Navigation może obejmują wiele etapów nawigacji, które są rozłożone w kolejności, gdy zostaną dodane do obiektu.
   2. Tworzenie ActionResponse za pomocą funkcji ActionResponseBuilder i Navigation obiektu.
   3. Zwróć utworzone ActionResponse

Uwaga: podczas poruszania się między kartami nie określasz, który stos (kontekstowy lub niezwiązane z kontekstem), do których zostały dodane karty lub z których są one usuwane. To jest kontrolowane przez użytkownika podczas wpisywania i opuszczania kontekstu. Podczas tworzenia dodatku dokładnie przetestuj nawigację na karcie, w tym zmiany kontekstu, pozytywne wrażenia użytkowników.

Tworząc elementy sterujące nawigacją, używasz tych elementów: Funkcje obiektu Navigation:

Funkcja	Opis
Navigation.pushCard(Card)	Przesuwa kartę na bieżący stos. Najpierw musisz całkowicie utworzyć kartę.
Navigation.popCard()	Usuwa jedną 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 ze stosu wszystkie karty oprócz karty głównej. Zasadniczo resetuje stos kart.
Navigation.popToNamedCard(String)	Odrzuca karty ze stosu, aż dotrą do karty o podanej nazwie lub karcie głównej. Możesz przypisać nazwy do kart za pomocą funkcji CardBuilder.setName(String).
Navigation.updateCard(Card)	Wykonuje zastąpienie bieżącej karty, odświeżając jej wyświetlanie w interfejsie.

Sprawdzona metoda dotycząca nawigacji

Czy interakcja użytkownika lub zdarzenie powinno skutkować ponownym renderowaniem kart w tym samym kontekst, użyj Navigation.pushCard() Navigation.popCard(), i Navigation.updateCard() i zastępowania istniejących kart. Jeśli interakcja lub zdarzenie użytkownika powinny co może skutkować ponownym renderowaniem kart w innym kontekście, użycie ActionResponseBuilder.setStateChanged() aby wymusić ponowne uruchomienie dodatku w takich kontekstach.

Oto przykłady nawigacji:

• Jeśli interakcja lub zdarzenie zmieni stan bieżącej karty (na przykład dodając zadanie do listy zadań), użyj updateCard()
• Jeśli interakcja lub zdarzenie zawiera dodatkowe informacje lub prosi użytkownika o dalsze działania (np. kliknięcie tytułu elementu w celu wyświetlenia dodatkowych informacji lub naciskając przycisk w celu utworzenia nowego wydarzenia w Kalendarzu), użyj pushCard() do wyświetlenia nowej strony, jednocześnie umożliwiając użytkownikowi opuszczenie nowej strony za pomocą przycisk Wstecz.
• Jeśli interakcja lub zdarzenie zaktualizuje stan na poprzedniej karcie (na przykład aktualizując tytuł elementu w widoku szczegółów), użyj polecenia takiego jak popCard() popCard(), pushCard(previous), i pushCard(current) aby zaktualizować poprzednią i bieżącą kartę.

Odświeżanie kart

Dodatki do Google Workspace dają użytkownikom: odśwież kartę, ponownie uruchamiając funkcję aktywatora Apps Script zarejestrowaną w pliku manifestu. Użytkownicy wywołują to odświeżenie za pomocą pozycji menu dodatku:

To działanie jest automatycznie dodawane do kart wygenerowanych przez: homepageTrigger lub contextualTrigger funkcje aktywujące określone w pliku manifestu dodatku (elementy główne kart kontekstowych i niekontekstowych).

Zwracanie wielu kart

Strona główna lub funkcje aktywatora kontekstowego są używane do tworzenia i zwracania albo jedno Card obiekt lub tablica Card obiekty, które interfejsu aplikacji.

Jeśli istnieje tylko 1 karta, jest ona dodawana do stosu niekontekstowego lub kontekstowego. karta główna i interfejs użytkownika aplikacji hosta.

Jeśli zwrócona tablica zawiera więcej niż 1 skompilowaną Card , aplikacja hosta wyświetla zamiast tego nową kartę, która zawiera sekcji nagłówków każdej karty. Gdy użytkownik kliknie dowolny z tych nagłówków, interfejs wyświetli odpowiednią kartę.

Gdy użytkownik wybierze kartę z listy, jest ona przekazywana na i wyświetli go aplikacja hosta. Przycisk powoduje zwrócenie użytkownika listę nagłówków karty.

To płaskie układ kart może się sprawdzić, jeśli dodatek nie wymaga żadnych przejścia między kartami. W większości przypadków lepiej jest jednak bezpośrednio definiować przejścia kart oraz ustawić stronę główną i kontekstowe funkcje aktywujące zwracają pojedynczy obiekt karty.

Przykład

Ten przykład pokazuje, jak utworzyć kilka kart za pomocą nawigacji które będą przechodzić między nimi. Te karty można dodać do kontekstowy lub niekontekstowy stos po wypchnięciu karty. 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();
  }