Dodaj krok z przewodnikiem

Ulepszaj dzięki funkcji tworzenia wiadomości
Dzięki Jetpack Compose na system operacyjny Android TV możesz tworzyć atrakcyjne interfejsy użytkownika przy użyciu minimalnej ilości pisania.
Utwórz wiadomość na potrzeby telewizji →

Aplikacja może zawierać zadania wieloetapowe dla użytkowników. Na przykład aplikacja może wymagać kierowania użytkowników przez zakup dodatkowych treści, konfigurowanie złożonych ustawień konfiguracji czy po prostu potwierdzanie decyzji. Wszystkie te zadania wymagają przeprowadzenia użytkownika przez co najmniej 1 uporządkowaną czynność lub decyzję.

Biblioteka androidx.leanback zawiera klasy do implementowania wieloetapowych zadań użytkownika. Na tej stronie dowiesz się, jak za pomocą klasy GuidedStepSupportFragment poprowadzić użytkownika przez serię decyzji w celu wykonania zadania. GuidedStepSupportFragment korzysta ze sprawdzonych metod dotyczących interfejsu TV, aby ułatwić zrozumienie wieloetapowych zadań i nawigację na telewizorach.

Podaj szczegóły kroku

GuidedStepSupportFragment reprezentuje jeden krok w serii kroków. Graficznie przedstawia on widok wskazówek z listą możliwych działań lub decyzji dotyczących danego kroku.

Rysunek 1. Przykładowy przewodnik.

W przypadku każdego kroku zadania wieloetapowego rozszerz opis GuidedStepSupportFragment i podaj informacje kontekstowe o kroku i działaniach, które może wykonać użytkownik. ZastąponCreateGuidance() i zwróć nową wartość GuidanceStylist.Guidance zawierającą informacje kontekstowe, takie jak tytuł, opis i ikona kroku, jak w tym przykładzie:

Kotlin

override fun onCreateGuidance(savedInstanceState: Bundle?): GuidanceStylist.Guidance {
    return GuidanceStylist.Guidance(
            getString(R.string.guidedstep_first_title),
            getString(R.string.guidedstep_first_description),
            getString(R.string.guidedstep_first_breadcrumb),
            activity.getDrawable(R.drawable.guidedstep_main_icon_1)
    )
}

Java

@Override
public GuidanceStylist.Guidance onCreateGuidance(Bundle savedInstanceState) {
    String title = getString(R.string.guidedstep_first_title);
    String breadcrumb = getString(R.string.guidedstep_first_breadcrumb);
    String description = getString(R.string.guidedstep_first_description);
    Drawable icon = getActivity().getDrawable(R.drawable.guidedstep_main_icon_1);
    return new GuidanceStylist.Guidance(title, description, breadcrumb, icon);
}

Dodaj podklasę GuidedStepSupportFragment do wybranego działania, wywołując metodę GuidedStepSupportFragment.add() w metodzie onCreate() aktywności.

Jeśli Twoja aktywność zawiera tylko GuidedStepSupportFragment obiektów, użyj GuidedStepSupportFragment.addAsRoot() zamiast add(), aby dodać pierwszy obiekt GuidedStepSupportFragment. Korzystanie z addAsRoot() powoduje, że jeśli podczas wyświetlania pierwszego elementu GuidedStepSupportFragment użytkownik naciśnie przycisk Wstecz na pilocie telewizora, zarówno działanie GuidedStepSupportFragment, jak i działanie rodzica zostaną zamknięte.

Uwaga: obiekty GuidedStepSupportFragment dodawaj automatycznie, a nie w plikach XML układu.

Tworzenie i obsługa działań użytkowników

Dodaj działania użytkowników, zastępując wartość onCreateActions(). W zastąpieniu dodaj nowy GuidedAction dla każdego działania i podaj ciąg działania, opis oraz identyfikator. Aby dodać nowe działania, użyj polecenia GuidedAction.Builder.

Kotlin

override fun onCreateActions(actions: MutableList<GuidedAction>, savedInstanceState: Bundle?) {
    super.onCreateActions(actions, savedInstanceState)

    // Add "Continue" user action for this step
    actions.add(GuidedAction.Builder()
            .id(CONTINUE)
            .title(getString(R.string.guidedstep_continue))
            .description(getString(R.string.guidedstep_letsdoit))
            .hasNext(true)
            .build())
    ...

Java

@Override
public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {
    // Add "Continue" user action for this step
    actions.add(new GuidedAction.Builder()
           .id(CONTINUE)
           .title(getString(R.string.guidedstep_continue))
           .description(getString(R.string.guidedstep_letsdoit))
           .hasNext(true)
           .build());
...

Działania nie są ograniczone do pojedynczych wierszy. Oto dodatkowe typy działań, które możesz tworzyć:

  • Dodaj działanie etykiety informacyjnej, aby wyświetlać dodatkowe informacje o wyborach użytkownika za pomocą ustawienia infoOnly(true). Jeśli zasada infoOnly ma wartość Prawda, użytkownicy nie mogą wybrać działania.
  • Aby dodać działanie tekstowe z możliwością edytowania, ustaw ustawienie editable(true). Jeśli editable ma wartość prawda, użytkownik może wpisywać tekst w wybranym działaniu za pomocą pilota lub podłączonej klawiatury. Zastąp onGuidedActionEditedAndProceed(), aby otrzymać zmodyfikowany tekst wpisany przez użytkownika. Możesz też zastąpić parametr onGuidedActionEditCanceled(), aby otrzymywać informacje o tym, że użytkownik anuluje dane wejściowe.
  • Dodaj zestaw działań, które działają jak przyciski umożliwiające zaznaczenie. W tym celu użyj polecenia checkSetId() z wspólną wartością identyfikatora, aby zgrupować działania w zestaw. Wszystkie działania na tej samej liście o tym samym identyfikatorze zestawu kontrolnego są uznawane za połączone. Gdy użytkownik wybierze jedno z działań w zestawie, zostanie ono zaznaczone, a pozostałe działania zostaną odznaczone.
  • Dodaj działanie selektora daty, używając GuidedDatePickerAction.Builder zamiast GuidedAction.Builder w onCreateActions(). Zastąp onGuidedActionEditedAndProceed(), aby pobrać podaną przez użytkownika wartość daty zmodyfikowania.
  • Dodaj działanie używające poddziałań, aby umożliwić użytkownikowi wybór z rozszerzonej listy wyboru. Działania podrzędne są opisane w sekcji Dodaj działania podrzędne.
  • Dodaj łatwo dostępny przycisk widoczny po prawej stronie listy działań. Działania związane z przyciskami są opisane w sekcji Dodaj działania związane z przyciskiem.

Możesz też dodać wizualny wskaźnik, który informuje, że wybór działania prowadzi do nowego kroku poprzez ustawienie hasNext(true).

Listę wszystkich atrybutów, które możesz ustawić, znajdziesz na stronie GuidedAction.

Aby zareagować na działania, zastąp zmienną onGuidedActionClicked() i przetwórz przekazane dane GuidedAction. Wybierz działanie, sprawdzając GuidedAction.getId().

Dodaj działania podrzędne

Niektóre działania mogą wymagać udostępnienia użytkownikowi dodatkowego zestawu opcji. GuidedAction może określać listę działań podrzędnych, które będą wyświetlane jako menu z działaniami podrzędnymi.

Rysunek 2. Poddziałania z instrukcjami krok po kroku.

Lista działań podrzędnych może zawierać zwykłe działania lub opcje, ale nie selektor daty ani edytowalne działania tekstowe. Dodatkowo działanie nie może mieć własnego zestawu działań podrzędnych, ponieważ system nie obsługuje więcej niż 1 poziomu takich działań.

Aby dodać działania podrzędne, najpierw utwórz i wypełnij listę obiektów GuidedAction, które służą jako działania podrzędne, jak w tym przykładzie:

Kotlin

subActions.add(GuidedAction.Builder()
        .id(SUBACTION1)
        .title(getString(R.string.guidedstep_subaction1_title))
        .description(getString(R.string.guidedstep_subaction1_desc))
        .build())
...

Java

List<GuidedAction> subActions = new ArrayList<GuidedAction>();
subActions.add(new GuidedAction.Builder()
       .id(SUBACTION1)
       .title(getString(R.string.guidedstep_subaction1_title))
       .description(getString(R.string.guidedstep_subaction1_desc))
       .build());
...

W onCreateActions() utwórz element GuidedAction najwyższego poziomu, który po wybraniu wyświetla listę działań podrzędnych:

Kotlin

    ...
    actions.add(GuidedAction.Builder()
            .id(SUBACTIONS)
            .title(getString(R.string.guidedstep_subactions_title))
            .description(getString(R.string.guidedstep_subactions_desc))
            .subActions(subActions)
            .build())
    ...

Java

@Override
public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {
...
    actions.add(new GuidedAction.Builder()
           .id(SUBACTIONS)
           .title(getString(R.string.guidedstep_subactions_title))
           .description(getString(R.string.guidedstep_subactions_desc))
           .subActions(subActions)
           .build());
...
}

Na koniec zareaguj na wybory poddziałań, zastępując fragment onSubGuidedActionClicked():

Kotlin

override fun onSubGuidedActionClicked(action: GuidedAction): Boolean {
    // Check for which action was clicked and handle as needed
    when(action.id) {
        SUBACTION1 -> {
            // Subaction 1 selected
        }
    }
    // Return true to collapse the subactions menu or
    // false to keep the menu expanded
    return true
}

Java

@Override
public boolean onSubGuidedActionClicked(GuidedAction action) {
   // Check for which action was clicked and handle as needed
   if (action.getId() == SUBACTION1) {
       // Subaction 1 selected
   }
   // Return true to collapse the subactions menu or
   // false to keep the menu expanded
   return true;
}

Dodaj działania przycisku

Jeśli krok z przewodnikiem zawiera obszerną listę działań, użytkownicy mogą być zmuszeni do jej przewinięcia, aby uzyskać dostęp do najczęściej używanych działań. Używaj przycisków, aby oddzielić często używane działania od listy działań. Działania związane z przyciskami są widoczne obok listy i łatwo do nich przejść.

Rysunek 3. Działania przycisku z instrukcjami krok po kroku.

Działania związane z przyciskami tworzy się i obsługuje tak samo jak zwykłe działania, ale tworzy się je w onCreateButtonActions(), a nie w onCreateActions(). Reaguj na działania przycisku w onGuidedActionClicked().

Używaj przycisków do prostych działań, np. do przechodzenia między krokami. Jako działania przycisku nie używaj działania selektora daty ani innych działań, które można edytować. Pamiętaj też, że przycisk nie może zawierać działań podrzędnych.

Grupuj kroki z instrukcjami w sekwencję z instrukcjami

GuidedStepSupportFragment reprezentuje jeden krok. Aby utworzyć uporządkowane sekwencje kroków, zgrupuj kilka obiektów GuidedStepSupportFragment za pomocą polecenia GuidedStepSupportFragment.add(), by dodać kolejny krok sekwencji do stosu fragmentów.

Kotlin

override fun onGuidedActionClicked(action: GuidedAction) {
    val fm = fragmentManager
    when(action.id) {
        CONTINUE -> GuidedStepSupportFragment.add(fm, SecondStepFragment())
    }
}

Java

@Override
public void onGuidedActionClicked(GuidedAction action) {
    FragmentManager fm = getFragmentManager();
    if (action.getId() == CONTINUE) {
       GuidedStepSupportFragment.add(fm, new SecondStepFragment());
    }
...

Jeśli użytkownik naciśnie przycisk Wstecz na pilocie telewizora, urządzenie wyświetli poprzedni plik GuidedStepSupportFragment na stosie fragmentów. Jeśli podasz własny element GuidedAction, który wróci do poprzedniego kroku, możesz zaimplementować działanie Wstecz, wywołując metodę getFragmentManager().popBackStack(). Jeśli musisz przywrócić użytkownikowi jeszcze wcześniejszy krok w sekwencji, użyj popBackStackToGuidedStepSupportFragment(), aby wrócić do określonego elementu GuidedStepSupportFragment w stosie fragmentów.

Gdy użytkownik zakończy ostatni krok w sekwencji, użyj polecenia finishGuidedStepSupportFragments(), aby usunąć z bieżącego stosu wszystkie instancje GuidedStepSupportFragment i wrócić do pierwotnej aktywności nadrzędnej. Jeśli dodasz pierwszy element GuidedStepSupportFragment za pomocą addAsRoot(), wywołanie finishGuidedStepSupportFragments() zamyka też aktywność nadrzędną.

Dostosuj prezentację kroku

Klasa GuidedStepSupportFragment może używać niestandardowych motywów, które kontrolują aspekty prezentacji, takie jak formatowanie tekstu tytułu czy animacje przejścia krokowego. Motywy niestandardowe muszą dziedziczyć z elementu Theme_Leanback_GuidedStep i mogą zastąpić wartości w przypadku atrybutów zdefiniowanych w atrybutach GuidanceStylist i GuidedActionsStylist.

Aby zastosować motyw niestandardowy do urządzenia GuidedStepSupportFragment, wykonaj jedną z tych czynności:

  • Zastosuj motyw do aktywności nadrzędnej, ustawiając atrybut android:theme w elemencie aktywności w pliku manifestu Androida. Ustawienie tego atrybutu powoduje zastosowanie motywu do wszystkich widoków podrzędnych. To najprostszy sposób zastosowania motywu niestandardowego, jeśli aktywność nadrzędna zawiera tylko obiekty GuidedStepSupportFragment.
  • Jeśli Twoja aktywność korzysta już z motywu niestandardowego i nie chcesz stosować stylów GuidedStepSupportFragment do innych widoków w tej aktywności, dodaj atrybut LeanbackGuidedStepTheme_guidedStepTheme do istniejącego niestandardowego motywu aktywności. Ten atrybut wskazuje motyw niestandardowy, z którego korzystają tylko obiekty GuidedStepSupportFragment w Twojej aktywności.
  • Jeśli używasz obiektów GuidedStepSupportFragment w różnych działaniach, które są częścią tego samego ogólnego zadania wieloetapowego, i chcesz używać spójnego motywu wizualnego we wszystkich krokach, zastąp GuidedStepSupportFragment.onProvideTheme() i zwróć motyw niestandardowy.

Więcej informacji o dodawaniu stylów i motywów znajdziesz na stronie Style i motywy.

Klasa GuidedStepSupportFragment używa specjalnych klas stylów do uzyskiwania dostępu do atrybutów motywów i ich stosowania. Klasa GuidanceStylist wykorzystuje informacje o motywie do kontrolowania wyświetlania widoku wskazówek po lewej stronie, a klasa GuidedActionsStylist używa informacji o motywie do sterowania wyświetlaniem widoku działań po prawej stronie.

Aby dostosować styl wizualny kroków poza możliwością dostosowania motywu, należy utworzyć podklasę GuidanceStylist lub GuidedActionsStylist i zwrócić podklasę w obiekcie GuidedStepSupportFragment.onCreateGuidanceStylist() lub GuidedStepSupportFragment.onCreateActionsStylist(). Szczegółowe informacje o tym, co możesz dostosować w tych podklasach, znajdziesz w dokumentacji GuidanceStylist i GuidedActionsStylist.