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.
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 zasadainfoOnly
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ślieditable
ma wartość prawda, użytkownik może wpisywać tekst w wybranym działaniu za pomocą pilota lub podłączonej klawiatury. ZastąponGuidedActionEditedAndProceed()
, aby otrzymać zmodyfikowany tekst wpisany przez użytkownika. Możesz też zastąpić parametronGuidedActionEditCanceled()
, 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
zamiastGuidedAction.Builder
wonCreateActions()
. ZastąponGuidedActionEditedAndProceed()
, 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.
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ść.
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 obiektyGuidedStepSupportFragment
. -
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 atrybutLeanbackGuidedStepTheme_guidedStepTheme
do istniejącego niestandardowego motywu aktywności. Ten atrybut wskazuje motyw niestandardowy, z którego korzystają tylko obiektyGuidedStepSupportFragment
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ąpGuidedStepSupportFragment.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
.