Ajouter une étape guidée

Créez mieux avec Compose

Créez des interfaces utilisateur attrayantes avec un minimum de code à l'aide de Jetpack Compose pour l'OS Android TV.

Compose pour la télévision →

Votre application peut comporter des tâches en plusieurs étapes pour les utilisateurs. Par exemple, votre application peut avoir besoin de guider les utilisateurs pour acheter du contenu supplémentaire, définir un paramètre de configuration complexe ou simplement confirmer une décision. Toutes ces tâches nécessitent de guider les utilisateurs à travers une ou plusieurs étapes ou décisions ordonnées.

La bibliothèque androidx.leanback fournit des classes permettant d'implémenter des tâches utilisateur en plusieurs étapes. Cette page explique comment utiliser la classe GuidedStepSupportFragment pour guider un utilisateur dans le cadre d'une série de décisions visant à accomplir une tâche. GuidedStepSupportFragment utilise les bonnes pratiques concernant l'UI TV pour faciliter la compréhension et la navigation des tâches en plusieurs étapes sur les téléviseurs.

Fournir les détails d'une étape

Un GuidedStepSupportFragment représente une seule étape d'une série d'étapes. Visuellement, elle fournit une vue de guidage avec une liste d'actions ou de décisions possibles pour l'étape.

Figure 1 : Exemple d'étape guidée.

Pour chaque étape de votre tâche en plusieurs étapes, étendez GuidedStepSupportFragment et fournissez des informations contextuelles sur l'étape et les actions que l'utilisateur peut effectuer. Remplacez onCreateGuidance() et renvoyez un nouveau GuidanceStylist.Guidance contenant des informations contextuelles, telles que le titre, la description et l'icône de l'étape, comme illustré dans l'exemple suivant:

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

Ajoutez votre sous-classe GuidedStepSupportFragment à l'activité souhaitée en appelant GuidedStepSupportFragment.add() dans la méthode onCreate() de votre activité.

Si votre activité ne contient que des objets GuidedStepSupportFragment, utilisez GuidedStepSupportFragment.addAsRoot() au lieu de add() pour ajouter le premier GuidedStepSupportFragment. L'utilisation de addAsRoot() permet de s'assurer que si l'utilisateur appuie sur le bouton "Retour" de la télécommande du téléviseur lors de l'affichage du premier GuidedStepSupportFragment, l'activité GuidedStepSupportFragment et l'activité parent se ferment.

Remarque:Ajoutez des objets GuidedStepSupportFragment par programmation, et non dans vos fichiers XML de mise en page.

Créer et gérer des actions utilisateur

Ajoutez des actions utilisateur en remplaçant onCreateActions(). Dans le forçage, ajoutez un nouvel élément GuidedAction pour chaque tâche, et indiquez la chaîne d'action, la description et l'ID. Utilisez GuidedAction.Builder pour ajouter des actions.

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

Les actions ne se limitent pas aux sélections d'une seule ligne. Voici d'autres types d'actions que vous pouvez créer:

• Ajoutez une action de libellé d'informations pour fournir des informations supplémentaires sur les choix des utilisateurs en définissant infoOnly(true). Lorsque infoOnly est défini sur "true", les utilisateurs ne peuvent pas sélectionner l'action.
• Ajoutez une action de texte modifiable en définissant editable(true). Lorsque editable est défini sur "true", l'utilisateur peut saisir du texte dans une action sélectionnée à l'aide de la télécommande ou d'un clavier connecté. Ignorez onGuidedActionEditedAndProceed() pour obtenir le texte modifié saisi par l'utilisateur. Vous pouvez également ignorer onGuidedActionEditCanceled() pour savoir quand l'utilisateur annule l'entrée.
• Ajoutez un ensemble d'actions qui se comportent comme des cases d'option cochables en utilisant checkSetId() avec une valeur d'ID commune pour regrouper les actions dans un ensemble. Toutes les actions d'une même liste ayant le même ID de check-set sont considérées comme liées. Lorsque l'utilisateur sélectionne l'une des actions de cet ensemble, cette action est cochée et toutes les autres sont décochées.
• Ajoutez une action de calendrier en utilisant GuidedDatePickerAction.Builder au lieu de GuidedAction.Builder dans onCreateActions(). Ignorez onGuidedActionEditedAndProceed() pour obtenir la valeur de date modifiée par l'utilisateur.
• Ajoutez une action qui utilise des sous-actions pour permettre à l'utilisateur de choisir parmi une liste de choix étendue. Les sous-actions sont décrites dans la section Ajouter des sous-actions.
• Ajoutez une action de bouton qui s'affiche à droite de la liste d'actions et est facilement accessible. Les actions associées aux boutons sont décrites dans la section Ajouter des actions de bouton.

Vous pouvez également ajouter un indicateur visuel indiquant que la sélection d'une action mène à une nouvelle étape en définissant hasNext(true).

Pour connaître les différents attributs que vous pouvez définir, consultez GuidedAction.

Pour répondre aux actions, ignorez onGuidedActionClicked() et traitez le GuidedAction transmis. Identifiez l'action sélectionnée en examinant GuidedAction.getId().

Ajouter des sous-actions

Certaines actions peuvent vous obliger à proposer un ensemble d'options supplémentaire à l'utilisateur. Un GuidedAction peut spécifier une liste de sous-actions qui s'affichent sous la forme d'un menu d'actions enfants.

Figure 2. Sous-actions de l'étape guidée.

La liste de sous-actions peut contenir des actions standards ou des cases d'option, mais pas de sélecteur de date ni d'actions de texte modifiables. De plus, une sous-action ne peut pas avoir son propre ensemble de sous-actions, car le système ne prend pas en charge plusieurs niveaux de sous-actions.

Pour ajouter des sous-actions, commencez par créer et remplir une liste d'objets GuidedAction qui agissent en tant que sous-actions, comme illustré dans l'exemple suivant:

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

Dans onCreateActions(), créez un GuidedAction de premier niveau qui affiche la liste des sous-actions lorsqu'il est sélectionné:

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

Enfin, répondez aux sélections de sous-action en remplaçant onSubGuidedActionClicked():

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

Ajouter des actions de bouton

Si votre étape guidée comporte une longue liste d'actions, les utilisateurs devront peut-être la faire défiler pour accéder aux actions les plus couramment utilisées. Utilisez les actions des boutons pour séparer les actions couramment utilisées de la liste d'actions. Les actions associées aux boutons apparaissent à côté de la liste d'actions et sont faciles d'accès.

Figure 3. Actions guidées du bouton "Pas"

Les actions de bouton sont créées et gérées de la même manière que les actions standards, à la différence que vous en créez dans onCreateButtonActions() au lieu de onCreateActions(). Répondez aux actions du bouton dans onGuidedActionClicked().

Utilisez les actions sur les boutons pour des actions simples, comme des actions de navigation entre les étapes. N'utilisez pas le sélecteur de date ni d'autres actions modifiables comme actions de bouton. De plus, les actions des boutons ne peuvent pas avoir de sous-actions.

Regrouper les étapes guidées dans une séquence guidée

Un GuidedStepSupportFragment représente une seule étape. Pour créer une séquence ordonnée d'étapes, regroupez plusieurs objets GuidedStepSupportFragment à l'aide de GuidedStepSupportFragment.add() afin d'ajouter l'étape suivante de la séquence à la pile de fragments.

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

Si l'utilisateur appuie sur le bouton "Retour" de la télécommande du téléviseur, l'appareil affiche l'GuidedStepSupportFragment précédent sur la pile de fragments. Si vous fournissez votre propre GuidedAction qui revient à l'étape précédente, vous pouvez implémenter le comportement "Retour" en appelant getFragmentManager().popBackStack(). Si vous devez renvoyer l'utilisateur à une étape encore antérieure de la séquence, utilisez popBackStackToGuidedStepSupportFragment() pour revenir à un GuidedStepSupportFragment spécifique dans la pile de fragments.

Lorsque l'utilisateur a terminé la dernière étape de la séquence, utilisez finishGuidedStepSupportFragments() pour supprimer toutes les instances GuidedStepSupportFragment de la pile actuelle et revenir à l'activité parent d'origine. Si le premier GuidedStepSupportFragment est ajouté à l'aide de addAsRoot(), l'appel de finishGuidedStepSupportFragments() ferme également l'activité parente.

Personnaliser la présentation des étapes

La classe GuidedStepSupportFragment peut utiliser des thèmes personnalisés qui contrôlent des aspects de la présentation, tels que la mise en forme du texte du titre ou les animations de transition d'étapes. Les thèmes personnalisés doivent hériter de Theme_Leanback_GuidedStep et peuvent fournir des valeurs de remplacement pour les attributs définis dans GuidanceStylist et GuidedActionsStylist.

Pour appliquer un thème personnalisé à votre GuidedStepSupportFragment, effectuez l'une des opérations suivantes:

• Appliquez le thème à l'activité parent en définissant l'attribut android:theme sur l'élément d'activité dans le fichier manifeste Android. La définition de cet attribut applique le thème à toutes les vues enfants et constitue le moyen le plus simple d'appliquer un thème personnalisé si l'activité parent ne contient que des objets GuidedStepSupportFragment.
• Si votre activité utilise déjà un thème personnalisé et que vous ne souhaitez pas appliquer de styles GuidedStepSupportFragment à d'autres vues de l'activité, ajoutez l'attribut LeanbackGuidedStepTheme_guidedStepTheme à votre thème d'activité personnalisé existant. Cet attribut pointe vers le thème personnalisé que seuls les objets GuidedStepSupportFragment de votre activité utilisent.
• Si vous utilisez des objets GuidedStepSupportFragment dans différentes activités qui font partie de la même tâche globale en plusieurs étapes et que vous souhaitez utiliser un thème visuel cohérent à toutes les étapes, remplacez GuidedStepSupportFragment.onProvideTheme() et renvoyez votre thème personnalisé.

Pour en savoir plus sur l'ajout de styles et de thèmes, consultez la section Styles et thèmes.

La classe GuidedStepSupportFragment utilise des classes de stylet spéciales pour accéder aux attributs de thème et les appliquer. La classe GuidanceStylist utilise les informations de thème pour contrôler la présentation de la vue de guidage de gauche, tandis que la classe GuidedActionsStylist utilise les informations de thème pour contrôler la présentation de la vue d'actions de droite.

Pour personnaliser le style visuel de vos étapes au-delà de ce que propose la personnalisation du thème, sous-classez GuidanceStylist ou GuidedActionsStylist, puis renvoyez votre sous-classe dans GuidedStepSupportFragment.onCreateGuidanceStylist() ou GuidedStepSupportFragment.onCreateActionsStylist(). Pour en savoir plus sur les éléments que vous pouvez personnaliser dans ces sous-classes, consultez la documentation sur GuidanceStylist et GuidedActionsStylist.