Interaktiven Schritt hinzufügen

Ihre Anwendung verfügt möglicherweise über mehrstufige Aufgaben für Nutzer. Beispielsweise kann Ihre Anwendung Nutzer durch den Kauf zusätzlicher Inhalte, die Einrichtung einer komplexen Konfigurationseinstellung oder die einfache Bestätigung einer Entscheidung unterstützen müssen. Bei allen diesen Aufgaben müssen die Nutzer durch einen oder mehrere geordnete Schritte oder Entscheidungen geführt werden.

Die Leanback-Androidx-Bibliothek enthält Klassen zum Implementieren mehrstufiger Nutzeraufgaben. Auf dieser Seite wird erläutert, wie Nutzer mit der Klasse GuidedStepSupportFragment durch eine Reihe von Entscheidungen zum Ausführen einer Aufgabe geführt werden. GuidedStepSupportFragment Mit den Best Practices für die TV-UI sind mehrstufige Aufgaben auf Fernsehern leicht verständlich und leicht zu navigieren.

Details zu einem Schritt angeben

Ein GuidedStepSupportFragment steht für einen einzelnen Schritt in einer Reihe von Schritten. Visuell bietet sie 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 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 eine neue GuidanceStylist.Guidance zurück, die Kontextinformationen wie den Titel des Schritts, die Beschreibung und das Symbol 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 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 die erste GuidedStepSupportFragment hinzuzufügen. Mit addAsRoot() wird sichergestellt, dass sowohl die GuidedStepSupportFragment- als auch die übergeordnete Aktivität geschlossen werden, wenn der Nutzer beim Ansehen des ersten GuidedStepSupportFragment die Taste „Zurück“ auf der Fernbedienung drückt.

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

Nutzeraktionen erstellen und verarbeiten

Sie können Nutzeraktionen hinzufügen, indem Sie onCreateActions() überschreiben. Fügen Sie beim Überschreiben für jedes Aktionselement eine neue GuidedAction hinzu und geben Sie den 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 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 Auswahlmöglichkeiten der Nutzer zur Verfügung zu stellen. Legen Sie dazu infoOnly(true) fest. Wenn infoOnly „true“ 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 in einer ausgewählten Aktion Text über die Fernbedienung oder eine verbundene Tastatur 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 die Eingabe abbricht.
• Fügen Sie eine Reihe von Aktionen hinzu, die sich wie anklickbare Optionsfelder verhalten. Verwenden Sie dazu checkSetId() mit einem gemeinsamen ID-Wert, um Aktionen zu einem Satz zu gruppieren. Alle Aktionen in derselben Liste mit derselben Prüfsatz-ID werden als verknüpft betrachtet. Wenn der Nutzer eine der Aktionen in diesem Satz auswählt, wird diese Aktion aktiviert und alle anderen Aktionen deaktiviert.
• Fügen Sie eine Aktion für die Datumsauswahl hinzu. Verwenden Sie dazu GuidedDatePickerAction.Builder anstelle von GuidedAction.Builder in onCreateActions(). Überschreiben Sie onGuidedActionEditedAndProceed(), um den vom Nutzer eingegebenen Datumswert abzurufen.
• Fügen Sie eine Aktion mit Unteraktionen hinzu, 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. Aktionen für Schaltflächen werden im Abschnitt Schaltflächenaktionen hinzufügen beschrieben.

Sie können auch einen visuellen Indikator hinzufügen, dass die Auswahl einer Aktion zu einem neuen Schritt führt. Legen Sie dazu hasNext(true) fest.

Informationen zu allen verschiedenen Attributen, die Sie festlegen können, finden Sie unter GuidedAction.

Wenn Sie auf Aktionen reagieren möchten, überschreiben Sie onGuidedActionClicked() und verarbeiten den übergebenen GuidedAction-Wert. Ermitteln Sie die ausgewählte Aktion unter GuidedAction.getId().

Unteraktionen hinzufügen

Für einige Aktionen müssen Sie den Nutzenden möglicherweise zusätzliche Auswahlmöglichkeiten zur Verfügung stellen. Mit GuidedAction kann eine Liste von Unteraktionen angegeben werden, die als Menü mit untergeordneten Aktionen angezeigt werden.

Abbildung 2: Unteraktionen mit Anleitung.

Die Liste der Unteraktionen kann normale Aktionen oder Aktionen für Optionsfelder enthalten, aber keine Aktionen für die Datumsauswahl oder bearbeitbare Textaktionen. Außerdem darf eine Unteraktion keine eigenen Unteraktionen haben, da das System nicht mehr als eine Ebene von Unteraktionen unterstützt.

Um Unteraktionen hinzuzufügen, müssen Sie zuerst eine Liste von GuidedAction-Objekten erstellen und füllen, 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() eine GuidedAction der obersten Ebene, 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 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;
}

Aktionen für Schaltflächen 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. Mit Schaltflächenaktionen trennen Sie häufig genutzte Aktionen von der Aktionsliste. Schaltflächenaktionen werden neben der Aktionsliste angezeigt und sind leicht zu navigieren.

Abbildung 3: Interaktive Schritte für Tastenaktionen.

Schaltflächenaktionen werden wie normale Aktionen erstellt und verarbeitet, allerdings werden Schaltflächenaktionen in onCreateButtonActions() statt in onCreateActions() erstellt. Auf Schaltflächenaktionen in onGuidedActionClicked() reagieren.

Verwenden Sie Schaltflächenaktionen für einfache Aktionen, z. B. Navigationsaktionen zwischen den Schritten. Verwenden Sie 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 zusammenfassen

Ein GuidedStepSupportFragment steht für einen einzelnen Schritt. Zum Erstellen einer geordneten Abfolge von Schritten gruppieren Sie mehrere GuidedStepSupportFragment-Objekte mithilfe von GuidedStepSupportFragment.add(), um den nächsten Schritt in der Sequenz dem Fragmentstack 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 die Schaltfläche „Zurück“ auf der TV-Fernbedienung drückt, zeigt das Gerät die vorherige GuidedStepSupportFragment im Fragment-Stack an. Wenn Sie Ihre eigene GuidedAction angeben, die zum vorherigen Schritt zurückkehrt, können Sie das Verhalten „Zurück“ durch Aufrufen von getFragmentManager().popBackStack() implementieren. Wenn Sie den Nutzer zu einem noch früheren Schritt in der Sequenz zurückkehren müssen, verwenden Sie popBackStackToGuidedStepSupportFragment(), um zu einer bestimmten GuidedStepSupportFragment im Fragmentstack zurückzukehren.

Wenn der Nutzer den letzten Schritt in der Sequenz abgeschlossen hat, 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 das Aufrufen von finishGuidedStepSupportFragments() auch die übergeordnete Aktivität geschlossen.

Präsentation des Schritts anpassen

Die Klasse GuidedStepSupportFragment kann benutzerdefinierte Designs verwenden, mit denen Darstellungsaspekte wie die Formatierung des Titeltexts oder Animationen für den Schrittwechsel gesteuert werden. Benutzerdefinierte Designs müssen von Theme_Leanback_GuidedStep übernommen 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 Ihren GuidedStepSupportFragment anzuwenden:

• Wende das Design auf die übergeordnete Aktivität an, indem du das Attribut android:theme auf das Aktivitätselement im Android-Manifest festlegst. 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 die GuidedStepSupportFragment-Stile nicht auf andere Ansichten in der Aktivität anwenden möchten, fügen Sie dem vorhandenen benutzerdefinierten Aktivitätsdesign das Attribut LeanbackGuidedStepTheme_guidedStepTheme hinzu. Dieses Attribut verweist auf das benutzerdefinierte Design, das nur die GuidedStepSupportFragment-Objekte in Ihrer Aktivität verwenden.
• Wenn Sie GuidedStepSupportFragment-Objekte in verschiedenen Aktivitäten verwenden, die Teil derselben mehrstufigen Gesamtaufgabe 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 Stillistenklassen, um auf Designattribute zuzugreifen und diese anzuwenden. Die Klasse GuidanceStylist verwendet Themeninformationen, um die Darstellung der linken Navigationsansicht zu steuern, während die Klasse GuidedActionsStylist Themeninformationen verwendet, um die Darstellung der rechten Aktionsansicht zu steuern.

Wenn Sie den visuellen Stil Ihrer Schritte über die Themenanpassung hinaus anpassen möchten, erstellen Sie eine abgeleitete Klasse von GuidanceStylist oder GuidedActionsStylist und geben Sie Ihre 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.