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.

<ph type="x-smartling-placeholder"></ph> 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 en achetant du contenu supplémentaire, en mettant en place une configuration complexe ou simplement pour confirmer une décision. Toutes ces tâches nécessitent de guider les utilisateurs dans une ou plusieurs les étapes ou les décisions.

La bibliothèque androidx.leanback fournit des classes permettant d'implémenter des tâches utilisateur en plusieurs étapes. Cette page explique comment utiliser Classe GuidedStepSupportFragment pour guider un utilisateur à travers une série de décisions pour accomplir une tâche. GuidedStepSupportFragment utilise les bonnes pratiques d'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

Une GuidedStepSupportFragment représente une seule étape d'une série d'étapes. Visuellement, il fournit une vue de guidage liste des actions ou 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 fournir des informations contextuelles sur l'étape et les actions que l'utilisateur peut entreprendre. Remplacement onCreateGuidance() et renvoie un nouveau GuidanceStylist.Guidance contenant le contexte 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 la sous-classe GuidedStepSupportFragment à la sous-classe de votre choix l'activité en appelant GuidedStepSupportFragment.add() dans la méthode onCreate() de votre activité.

Si votre activité contient uniquement GuidedStepSupportFragment des objets, utilisez GuidedStepSupportFragment.addAsRoot() au lieu de add() pour ajouter la première GuidedStepSupportFragment. En utilisant addAsRoot() permet de s'assurer que si l'utilisateur appuie sur le bouton "Retour" de la télécommande du téléviseur lorsqu'il visionne le contenu le premier GuidedStepSupportFragment, les deux GuidedStepSupportFragment et l'activité parent se ferment.

Remarque:Ajoutez GuidedStepSupportFragment par programmation, pas dans vos fichiers XML de mise en page.

Créer et gérer des actions utilisateur

Ajouter des actions utilisateur en remplaçant onCreateActions() Dans votre forçage, ajoutez un nouveau GuidedAction pour chaque la tâche et fournir la chaîne, la description et l'ID de l'action. Utilisez GuidedAction.Builder pour ajouter de nouvelles 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 de que vous pouvez créer:

• Ajoutez une action "Libellé d'information" 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 méthode une télécommande ou un clavier connecté. Remplacement 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 à l'aide de checkSetId() ayant une valeur d'ID commune pour regrouper les actions dans un ensemble. Toutes les actions de la même liste ayant le même check-set sont considérés comme associés. Lorsque l'utilisateur sélectionne l'une des actions de cet ensemble, 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(). Remplacement 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 étendue de les choix possibles. Les sous-actions sont décrites dans la section Ajouter des sous-actions.
• Ajoutez un bouton d'action qui s'affiche à droite de la liste d'actions et est facile à utiliser. accessibles. Les actions des boutons sont décrites dans la section Bouton "Ajouter" Actions.

Vous pouvez également ajouter un indicateur visuel permettant de sélectionner 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 à des actions, remplacez onGuidedActionClicked() et traiter les données transmises GuidedAction Identifiez l'action sélectionnée examen de GuidedAction.getId().

Ajouter des sous-actions

Certaines actions peuvent vous obliger à proposer un ensemble d'options supplémentaire à l'utilisateur. A 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 des sous-actions peut contenir des actions standards ou des cases d'option, mais et non dans le sélecteur de date ni les actions de texte modifiables. De plus, une sous-action ne peut pas avoir 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 de 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 élément GuidedAction, qui affiche Liste des sous-actions lorsque cette option est sélectionnée:

    ...
    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-actions 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 procédure guidée comporte une longue liste d'actions, les utilisateurs devront peut-être faire défiler la liste pour accéder aux actions les plus couramment utilisées. Utilisez les actions des boutons pour séparer les actions couramment utilisées dans la liste d'actions. Les actions du bouton s'affichent à côté de la liste d'actions et sont faciles d'accès.

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

Les actions associées aux boutons sont créées et gérées de la même manière que les actions standards, mais vous créez actions du bouton dans onCreateButtonActions() au lieu de onCreateActions(). Répondre aux actions des boutons 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

GuidedStepSupportFragment représente une seule étape. Pour créer une séquence ordonnée d'étapes, regroupez plusieurs GuidedStepSupportFragment objets ensemble en utilisant GuidedStepSupportFragment.add() à ajouter l'étape suivante de la séquence vers 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 les GuidedStepSupportFragment sur la pile de fragments. Si vous fournissez vos propres GuidedAction qui à 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 tout supprimer GuidedStepSupportFragment instances de la pile actuelle et revenir à l'activité parent d'origine. Si le GuidedStepSupportFragment a été ajouté avec addAsRoot(), appel finishGuidedStepSupportFragments() ferme également l'activité parent.

Personnaliser la présentation des étapes

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

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

• Appliquez le thème à l'activité parent en définissant l'attribut android:theme sur la d'activité dans le fichier manifeste Android. La définition de cet attribut applique le thème à tous les enfants et constitue le moyen le plus simple d'appliquer un thème personnalisé si l'activité parent ne contient Objets GuidedStepSupportFragment.
• Si votre activité utilise déjà un thème personnalisé et que vous ne voulez pas l'appliquer GuidedStepSupportFragment applique un style aux autres vues de l'activité, ajouter LeanbackGuidedStepTheme_guidedStepTheme à votre thème d'activité personnalisé existant. Cet attribut renvoie au thème personnalisé uniquement les objets GuidedStepSupportFragment dans votre l'utilisation de l'activité.
• Si vous utilisez des objets GuidedStepSupportFragment dans différentes les activités faisant partie d'une même tâche globale en plusieurs étapes et qui souhaitent utiliser thème visuel pour toutes les étapes, remplacer GuidedStepSupportFragment.onProvideTheme() et renvoyer votre thème personnalisé.

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

La classe GuidedStepSupportFragment utilise des classes stylist 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 du volet de navigation de gauche, tandis que La classe GuidedActionsStylist utilise les informations du thème pour contrôler la présentation des actions appropriées.

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