Ihre Anwendung enthält möglicherweise mehrstufige Aufgaben für Nutzer. Möglicherweise muss deine App Nutzer durch den Kauf zusätzlicher Inhalte, die Einrichtung einer komplexen Konfigurationseinstellung oder die einfache Bestätigung einer Entscheidung anleiten. Für all diese Aufgaben müssen Nutzer einen oder mehrere Schritte oder Entscheidungen in einer bestimmten Reihenfolge durchlaufen.
Die androidx.leanback-Bibliothek enthält Klassen zur Implementierung mehrstufiger Nutzeraufgaben. Auf dieser Seite wird erläutert, wie Sie einen Nutzer mithilfe der Klasse GuidedStepSupportFragment
durch eine Reihe von Entscheidungen zum Ausführen einer Aufgabe führen. GuidedStepSupportFragment
nutzt Best Practices für die TV-Benutzeroberfläche, um mehrstufige Aufgaben auf Fernsehern leicht verständlich zu machen und zu navigieren.
Details zu einem Schritt angeben
Eine GuidedStepSupportFragment
steht für einen einzelnen Schritt in einer Reihe von Schritten. Visuell bietet es eine Anleitungsansicht mit einer Liste möglicher Aktionen oder Entscheidungen für den Schritt.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-screen.png?authuser=6&hl=de)
Abbildung 1: Ein Beispiel für einen geführten Schritt.
Erweitern Sie für jeden Schritt der mehrstufigen Aufgabe GuidedStepSupportFragment
und geben Sie Kontextinformationen zu dem Schritt und den Aktionen an, die der Nutzer ausführen kann. Überschreiben Sie onCreateGuidance()
und geben Sie eine neue GuidanceStylist.Guidance
zurück, die Kontextinformationen wie Titel, Beschreibung und Symbol des Schritts enthält. Beispiel:
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); }
Fügen Sie die abgeleitete GuidedStepSupportFragment
-Klasse der gewünschten Aktivität hinzu, indem Sie GuidedStepSupportFragment.add()
in der onCreate()
-Methode Ihrer Aktivität aufrufen.
Wenn Ihre Aktivität nur GuidedStepSupportFragment
-Objekte enthält, verwenden Sie GuidedStepSupportFragment.addAsRoot()
anstelle von add()
, um das erste GuidedStepSupportFragment
-Objekt hinzuzufügen. Wenn der Nutzer addAsRoot()
auf der Fernbedienung des Fernsehers drückt, während er sich das erste GuidedStepSupportFragment
ansieht, werden sowohl die GuidedStepSupportFragment
- als auch die übergeordnete Aktivität beendet.
Hinweis:Füge GuidedStepSupportFragment
-Objekte programmatisch hinzu, nicht in den Layout-XML-Dateien.
Nutzeraktionen erstellen und verarbeiten
Fügen Sie Nutzeraktionen hinzu, indem Sie onCreateActions()
überschreiben.
Fügen Sie bei der Überschreibung für jedes Aktionselement eine neue GuidedAction
hinzu und geben Sie den Aktionsstring, eine Beschreibung und die ID an. Verwenden Sie GuidedAction.Builder
, um neue Aktionen hinzuzufügen.
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()); ...
Die Aktionen sind nicht auf eine einzeilige Auswahl beschränkt. Hier sind weitere Arten von Aktionen, die Sie erstellen können:
-
Fügen Sie eine Informationslabelaktion hinzu, um zusätzliche Informationen zu den Nutzeroptionen bereitzustellen. Legen Sie dazu
infoOnly(true)
fest. WenninfoOnly
„true“ ist, können Nutzer die Aktion nicht auswählen. -
Wenn Sie eine bearbeitbare Textaktion hinzufügen möchten, legen Sie
editable(true)
fest. Wenneditable
auf „true“ gesetzt ist, kann der Nutzer in einer ausgewählten Aktion über die Fernbedienung oder eine verbundene Tastatur Text eingeben. Überschreiben SieonGuidedActionEditedAndProceed()
, um den geänderten Text abzurufen, den der Nutzer eingegeben hat. Sie können auchonGuidedActionEditCanceled()
überschreiben, um zu erfahren, wann der Nutzer Eingaben abbricht. -
Fügen Sie eine Reihe von Aktionen hinzu, die sich wie prüfbare Optionsfelder verhalten. Verwenden Sie dazu
checkSetId()
mit einem gemeinsamen ID-Wert, um Aktionen in einem Satz zu gruppieren. Alle Aktionen in derselben Liste mit derselben Prüfsatz-ID gelten als verknüpft. Wenn der Nutzer eine Aktion in diesem Satz auswählt, wird diese Aktion aktiviert und alle anderen Aktionen deaktiviert. -
Fügen Sie eine Aktion zur Datumsauswahl hinzu. Verwenden Sie dazu
GuidedDatePickerAction.Builder
anstelle vonGuidedAction.Builder
inonCreateActions()
. Überschreiben SieonGuidedActionEditedAndProceed()
, um den geänderten Datumswert abzurufen, den der Nutzer eingegeben hat. - Fügen Sie eine Aktion hinzu, bei der Unteraktionen verwendet werden, damit der Nutzer aus einer erweiterten Liste von Auswahlmöglichkeiten auswählen kann. Unteraktionen werden im Abschnitt Unteraktionen hinzufügen beschrieben.
- Fügen Sie eine Schaltflächenaktion hinzu, die rechts neben der Liste mit Aktionen angezeigt wird und leicht zugänglich ist. Schaltflächenaktionen werden im Abschnitt Schaltflächenaktionen hinzufügen beschrieben.
Außerdem kannst du hasNext(true)
festlegen, um einen visuellen Hinweis hinzuzufügen, dass das Auswählen einer Aktion zu einem neuen Schritt führt.
Informationen zu den verschiedenen Attributen, die Sie festlegen können, finden Sie unter GuidedAction
.
Überschreiben Sie onGuidedActionClicked()
und verarbeiten Sie das übergebene GuidedAction
, um auf Aktionen zu reagieren. Untersuchen Sie GuidedAction.getId()
, um die ausgewählte Aktion zu ermitteln.
Unteraktionen hinzufügen
Bei einigen Aktionen müssen Sie dem Nutzer möglicherweise zusätzliche Auswahlmöglichkeiten geben. Mit GuidedAction
kann eine Liste von Unteraktionen angegeben werden, die als Menü mit untergeordneten Aktionen angezeigt werden.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-subaction.png?authuser=6&hl=de)
Abbildung 2: Unteraktionen mit Schritt-für-Schritt-Anleitung.
Die Liste der Teilaktionen kann normale Aktionen oder Optionsfeldaktionen enthalten, jedoch keine Aktionen zur Datumsauswahl oder bearbeitbaren Text. Außerdem kann eine Unteraktion keine eigene Gruppe von Unteraktionen haben, da das System nicht mehr als eine Ebene von Unteraktionen unterstützt.
Wenn Sie Unteraktionen hinzufügen möchten, erstellen Sie zuerst eine Liste von GuidedAction
-Objekten, die als Unteraktionen fungieren, wie im folgenden Beispiel gezeigt:
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()); ...
Erstellen Sie in onCreateActions()
eine übergeordnete GuidedAction
, die bei Auswahl die Liste der Unteraktionen anzeigt:
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()); ... }
Reagieren Sie schließlich auf die Auswahl der Unteraktionen, indem Sie onSubGuidedActionClicked()
überschreiben:
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; }
Schaltflächenaktionen hinzufügen
Wenn Ihr geführter Schritt eine große Liste von Aktionen enthält, müssen Nutzer möglicherweise durch die Liste scrollen, um auf die am häufigsten verwendeten Aktionen zuzugreifen. Verwenden Sie Schaltflächenaktionen, um häufig verwendete Aktionen von der Aktionsliste zu trennen. Schaltflächenaktionen erscheinen neben der Aktionsliste und sind einfach zu navigieren.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-buttonaction.png?authuser=6&hl=de)
Abbildung 3: Schritt-für-Schritt-Aktionen.
Schaltflächenaktionen werden wie normale Aktionen erstellt und verarbeitet. Schaltflächenaktionen werden jedoch in onCreateButtonActions()
statt in onCreateActions()
erstellt. Auf Schaltflächenaktionen in onGuidedActionClicked()
reagieren.
Verwenden Sie Schaltflächenaktionen für einfache Aktionen wie das Navigieren zwischen Schritten. Verwenden Sie die Aktion für die Datumsauswahl oder andere bearbeitbare Aktionen nicht als Schaltflächenaktionen. Außerdem dürfen Schaltflächenaktionen keine Unteraktionen enthalten.
Geführte Schritte zu einer geführten Sequenz gruppieren
Ein GuidedStepSupportFragment
stellt einen einzelnen Schritt dar. Gruppieren Sie mehrere GuidedStepSupportFragment
-Objekte mithilfe von GuidedStepSupportFragment.add()
, um eine geordnete Abfolge von Schritten zu erstellen und dem Fragmentstapel den nächsten Schritt in der Sequenz hinzuzufügen.
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()); } ...
Wenn der Nutzer auf der Fernbedienung des Fernsehers die Taste „Zurück“ drückt, zeigt das Gerät die vorherige GuidedStepSupportFragment
auf dem Fragmentstapel an. Wenn du deine eigene GuidedAction
angibst, die zum vorherigen Schritt zurückkehrt, kannst du das „Zurück“-Verhalten implementieren, indem du getFragmentManager().popBackStack()
aufrufst.
Wenn Sie den Nutzer zu einem noch früheren Schritt in der Sequenz zurückführen müssen, verwenden Sie popBackStackToGuidedStepSupportFragment()
, um zu einem bestimmten GuidedStepSupportFragment
im Fragmentstapel zurückzukehren.
Wenn der Nutzer den letzten Schritt in der Sequenz abschließt, verwenden Sie finishGuidedStepSupportFragments()
, um alle GuidedStepSupportFragment
-Instanzen aus dem aktuellen Stack zu entfernen und zur ursprünglichen übergeordneten Aktivität zurückzukehren. Wenn die erste GuidedStepSupportFragment
mit addAsRoot()
hinzugefügt wird, wird durch den Aufruf von finishGuidedStepSupportFragments()
auch die übergeordnete Aktivität geschlossen.
Schrittpräsentation anpassen
Für die Klasse GuidedStepSupportFragment
können benutzerdefinierte Designs verwendet werden, mit denen Präsentationsaspekte gesteuert werden, z. B. die Formatierung des Titeltexts oder Animationen mit Übergängen. Benutzerdefinierte Themen müssen von Theme_Leanback_GuidedStep
übernommen werden und können Überschreibungswerte für Attribute bereitstellen, die in GuidanceStylist
und GuidedActionsStylist
definiert sind.
Führen Sie einen der folgenden Schritte aus, um ein benutzerdefiniertes Design auf GuidedStepSupportFragment
anzuwenden:
-
Wenden Sie das Design auf die übergeordnete Aktivität an. Legen Sie dazu im Android-Manifest das Attribut
android:theme
auf das Aktivitätselement fest. Wenn Sie dieses Attribut festlegen, wird das Design auf alle untergeordneten Ansichten angewendet. Dies ist die einfachste Möglichkeit, ein benutzerdefiniertes Design anzuwenden, wenn die übergeordnete Aktivität nurGuidedStepSupportFragment
-Objekte enthält. -
Wenn für Ihre Aktivität bereits ein benutzerdefiniertes Design verwendet wird und Sie
GuidedStepSupportFragment
-Stile nicht auf andere Ansichten in der Aktivität anwenden möchten, fügen Sie dem vorhandenen benutzerdefinierten Aktivitätsthema das AttributLeanbackGuidedStepTheme_guidedStepTheme
hinzu. Dieses Attribut verweist auf das benutzerdefinierte Design, das nur von denGuidedStepSupportFragment
-Objekten in Ihrer Aktivität verwendet wird. -
Wenn Sie
GuidedStepSupportFragment
-Objekte in verschiedenen Aktivitäten verwenden, die Teil derselben mehrstufigen Aufgabe sind, und ein einheitliches visuelles Design für alle Schritte verwenden möchten, überschreiben SieGuidedStepSupportFragment.onProvideTheme()
und geben Ihr benutzerdefiniertes Design zurück.
Weitere Informationen zum Hinzufügen von Stilen und Designs finden Sie unter Stile und Designs.
Die Klasse GuidedStepSupportFragment
verwendet spezielle Stylistenklassen, um auf Designattribute zuzugreifen und sie anzuwenden.
Die GuidanceStylist
-Klasse verwendet Designinformationen, um die Darstellung der linken Anleitungsansicht zu steuern, während die GuidedActionsStylist
-Klasse Designinformationen verwendet, um die Darstellung der rechten Aktionsansicht zu steuern.
Wenn Sie den visuellen Stil Ihrer Schritte über die Designanpassung hinaus anpassen möchten, erstellen Sie abgeleitete Klassen von GuidanceStylist
oder GuidedActionsStylist
und geben Sie die abgeleitete Klasse in GuidedStepSupportFragment.onCreateGuidanceStylist()
oder GuidedStepSupportFragment.onCreateActionsStylist()
zurück.
Weitere Informationen dazu, was Sie in diesen abgeleiteten Klassen anpassen können, finden Sie in der Dokumentation zu GuidanceStylist
und GuidedActionsStylist
.