Interaktiven Schritt hinzufügen

Bessere Apps mit Compose entwickeln

Mit Jetpack Compose für Android TV OS schöne Benutzeroberflächen mit minimalem Code erstellen

Compose for TV →

Ihre Anwendung kann mehrstufige Aufgaben für Nutzer enthalten. Beispielsweise muss Ihre App Nutzer möglicherweise durch den Kauf zusätzlicher Inhalte führen, eine komplexe Konfiguration einrichten oder eine Entscheidung bestätigen. Für all diese Aufgaben müssen Nutzer durch einen oder mehrere geordnete Schritte oder Entscheidungen geführt werden.

Die eingestellte androidx.leanback-Bibliothek bietet Klassen zum Implementieren mehrstufiger Nutzeraufgaben. Auf dieser Seite wird beschrieben, wie Sie die GuidedStepSupportFragment Klasse verwenden, um Nutzer mithilfe von GuidedStepSupportFragment durch eine Reihe von Entscheidungen zu führen, damit sie eine Aufgabe erledigen können.

Details für einen Schritt angeben

Ein GuidedStepSupportFragment stellt einen einzelnen Schritt in einer Reihe von Schritten dar. Visuell bietet es eine Anleitung 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 in Ihrer 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 ein neues GuidanceStylist.Guidance zurück, das Kontextinformationen wie den Titel, die Beschreibung und das Symbol des Schritts enthält, wie im folgenden Beispiel gezeigt:

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 Ihre GuidedStepSupportFragment-Unterklasse Ihrer 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 hinzuzufügen. Mit addAsRoot() wird sichergestellt, dass sowohl das GuidedStepSupportFragment als auch die übergeordnete Aktivität geschlossen werden, wenn der Nutzer beim Aufrufen des ersten GuidedStepSupportFragment auf der TV-Fernbedienung den Button „Zurück“ drückt.

Hinweis:Fügen Sie GuidedStepSupportFragment-Objekte programmatisch und nicht in Ihren Layout-XML-Dateien hinzu.

Nutzeraktionen erstellen und verarbeiten

Fügen Sie Nutzeraktionen hinzu, indem Sie onCreateActions() überschreiben. Fügen Sie in Ihrer Überschreibung für jede Aufgabe ein neues GuidedAction hinzu und geben Sie die Aktionsstring, die 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());
...

Aktionen sind nicht auf einzeilige Auswahlen beschränkt. Hier sind weitere Arten von Aktionen, die Sie erstellen können:

• Fügen Sie eine Informationslabel-Aktion hinzu, um zusätzliche Informationen zu Nutzerauswahlen bereitzustellen, indem Sie infoOnly(true) festlegen. Wenn infoOnly auf „true“ gesetzt ist, können Nutzer die Aktion nicht auswählen.
• Fügen Sie eine bearbeitbare Textaktion hinzu, indem Sie editable(true) festlegen. Wenn editable auf „true“ gesetzt ist, kann der Nutzer über die Fernbedienung oder eine angeschlossene Tastatur Text in eine ausgewählte Aktion eingeben. Überschreiben Sie onGuidedActionEditedAndProceed(), um den geänderten Text zu erhalten, den der Nutzer eingegeben hat. Sie können auch onGuidedActionEditCanceled() überschreiben, um zu erfahren, wann der Nutzer die Eingabe abbricht.
• Fügen Sie eine Reihe von Aktionen hinzu, die sich wie auswählbare Optionsfelder verhalten, indem Sie checkSetId() mit einem gemeinsamen ID-Wert verwenden, um Aktionen zu einer Gruppe zusammenzufassen. Alle Aktionen in derselben Liste mit derselben Checkset-ID gelten als verknüpft. Wenn der Nutzer eine der Aktionen in dieser Gruppe auswählt, wird diese Aktion ausgewählt und alle anderen Aktionen werden deaktiviert.
• Fügen Sie eine Datumsauswahl-Aktion hinzu, indem Sie in onCreateActions() GuidedDatePickerAction.Builder anstelle von GuidedAction.Builder verwenden. Überschreiben Sie onGuidedActionEditedAndProceed(), um den geänderten Datumswert zu erhalten, den der Nutzer eingegeben hat.
• Fügen Sie eine Aktion hinzu, die Unteraktionen verwendet, damit der Nutzer aus einer erweiterten Liste von Optionen auswählen kann. Unteraktionen werden im Abschnitt Unteraktionen hinzufügen beschrieben.
• Fügen Sie eine Schaltflächenaktion hinzu, die rechts neben der Aktionsliste angezeigt wird und leicht zugänglich ist. Schaltflächenaktionen werden im Abschnitt Schaltflächenaktionen hinzufügen beschrieben.

Sie können auch einen visuellen Hinweis hinzufügen, dass die Auswahl einer Aktion zu einem neuen Schritt führt, indem Sie hasNext(true) festlegen.

Alle Attribute, die Sie festlegen können, finden Sie unter GuidedAction.

Um auf Aktionen zu reagieren, überschreiben Sie onGuidedActionClicked() und verarbeiten Sie das übergebene GuidedAction. Ermitteln Sie die ausgewählte Aktion anhand von GuidedAction.getId().

Unteraktionen hinzufügen

Für einige Aktionen müssen Sie dem Nutzer möglicherweise eine zusätzliche Auswahlmöglichkeit bieten. Ein GuidedAction kann eine Liste von Unteraktionen angeben, die als Menü mit untergeordneten Aktionen angezeigt werden.

Abbildung 2 : Unteraktionen für geführte Schritte.

Die Liste der Unteraktionen kann reguläre Aktionen oder Optionsfeldaktionen enthalten, aber keine Datumsauswahl- oder bearbeitbaren Textaktionen. Außerdem kann eine Unteraktion keine eigenen Unteraktionen haben, da das System nicht mehr als eine Ebene von Unteraktionen unterstützt.

Erstellen und füllen Sie zuerst eine Liste von GuidedAction-Objekten, die als Unteraktionen dienen, 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() ein GuidedAction der obersten Ebene, das die Liste der Unteraktionen anzeigt, wenn es ausgewählt wird:

    ...
    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 von 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 lange 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 werden neben der Aktionsliste angezeigt und sind leicht zu finden.

Abbildung 3 : Schaltflächenaktionen für geführte Schritte.

Schaltflächenaktionen werden genauso erstellt und verarbeitet wie reguläre Aktionen. Sie erstellen Schaltflächenaktionen jedoch in onCreateButtonActions() anstelle von onCreateActions(). Reagieren Sie in onGuidedActionClicked() auf Schaltflächenaktionen.

Verwenden Sie Schaltflächenaktionen für einfache Aktionen wie Navigationsaktionen zwischen Schritten. Verwenden Sie die Datumsauswahl-Aktion oder andere bearbeitbare Aktionen nicht als Schaltflächenaktionen. Außerdem können Schaltflächenaktionen keine Unteraktionen haben.

Geführte Schritte zu einer geführten Sequenz zusammenfassen

Ein GuidedStepSupportFragment stellt einen einzelnen Schritt dar. Wenn Sie eine geordnete Sequenz von Schritten erstellen möchten, gruppieren Sie mehrere GuidedStepSupportFragment Objekte mit GuidedStepSupportFragment.add(), um den nächsten Schritt in der Sequenz dem Fragment-Stack 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 TV-Fernbedienung den Button „Zurück“ drückt, wird das vorherige GuidedStepSupportFragment im Fragment-Stack angezeigt. Wenn Sie ein eigenes GuidedAction bereitstellen, das zum vorherigen Schritt zurückkehrt, können Sie das Verhalten der Zurück-Taste implementieren, indem Sie getFragmentManager().popBackStack() aufrufen. Wenn Sie den Nutzer zu einem noch früheren Schritt in der Sequenz zurückbringen müssen, verwenden Sie popBackStackToGuidedStepSupportFragment() , um zu einem bestimmten GuidedStepSupportFragment im Fragment-Stack zurückzukehren.

Wenn der Nutzer den letzten Schritt in der Sequenz abgeschlossen hat, entfernen Sie mit finishGuidedStepSupportFragments() alle GuidedStepSupportFragment Instanzen aus dem aktuellen Stack und kehren Sie zur ursprünglichen übergeordneten Aktivität zurück. Wenn das erste GuidedStepSupportFragment mit addAsRoot() hinzugefügt wird, wird durch den Aufruf von finishGuidedStepSupportFragments() auch die übergeordnete Aktivität geschlossen.

Darstellung von Schritten anpassen

Die Klasse GuidedStepSupportFragment kann benutzerdefinierte Designs verwenden, mit denen Präsentationsaspekte wie die Formatierung des Titels oder Animationen für den Übergang zwischen Schritten gesteuert werden. Benutzerdefinierte Designs müssen von Theme_Leanback_GuidedStep abgeleitet werden und können überschreibende Werte für Attribute bereitstellen, die in GuidanceStylist und GuidedActionsStylist definiert sind.

Führen Sie einen der folgenden Schritte aus, um ein benutzerdefiniertes Design auf Ihr GuidedStepSupportFragment anzuwenden:

• Wenden Sie das Design auf die übergeordnete Aktivität an, indem Sie das Attribut android:theme für das Aktivitätselement im Android-Manifest festlegen. 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 Ihre Aktivität bereits ein benutzerdefiniertes Design verwendet und Sie keine GuidedStepSupportFragment-Stile auf andere Ansichten in der Aktivität anwenden möchten, fügen Sie Ihrem vorhandenen benutzerdefinierten Aktivitätsdesign 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 Sie 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 Stylist-Klassen , um auf Designattribute zuzugreifen und sie anzuwenden. Die Klasse GuidanceStylist verwendet Designinformationen, um die Darstellung der linken Anleitung zu steuern, während die Klasse GuidedActionsStylist 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 eine Unterklasse von GuidanceStylist oder GuidedActionsStylist und geben Sie Ihre Unterklasse in GuidedStepSupportFragment.onCreateGuidanceStylist() oder GuidedStepSupportFragment.onCreateActionsStylist() zurück. Details dazu, was Sie in diesen Unterklassen anpassen können, finden Sie in der Dokumentation zu GuidanceStylist und GuidedActionsStylist.