Interaktiven Schritt hinzufügen

Besser lernen mit der Funktion „Schreiben“

Mit Jetpack Compose für Android TV OS lassen sich mit nur minimalem Code ansprechende UIs erstellen.

Für TV erstellen →

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.

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:

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)
    )
}

@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.

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())
    ...

@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. Wenn infoOnly „true“ ist, können Nutzer die Aktion nicht auswählen.
• Wenn Sie eine bearbeitbare Textaktion hinzufügen möchten, legen Sie editable(true) fest. Wenn editable auf „true“ gesetzt ist, kann der Nutzer in einer ausgewählten Aktion über die Fernbedienung oder eine verbundene Tastatur Text eingeben. Überschreiben Sie onGuidedActionEditedAndProceed(), um den geänderten Text abzurufen, den der Nutzer eingegeben hat. Sie können auch onGuidedActionEditCanceled() ü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 von GuidedAction.Builder in onCreateActions(). Überschreiben Sie onGuidedActionEditedAndProceed(), 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.

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:

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

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:

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

@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:

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
}

@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.

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.

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

@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 nur GuidedStepSupportFragment-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 Attribut LeanbackGuidedStepTheme_guidedStepTheme hinzu. Dieses Attribut verweist auf das benutzerdefinierte Design, das nur von den GuidedStepSupportFragment-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 Sie GuidedStepSupportFragment.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.