Tu aplicación puede mostrarles a los usuarios tareas de varios pasos. Por ejemplo, es posible que tu app necesite guiar a los usuarios comprando contenido adicional, estableciendo parámetros de configuración complejos tan solo confirmar una decisión. Todas estas tareas requieren explicar a los usuarios una o más tareas pasos o decisiones.
La biblioteca de androidx.Leanback brinda clases que permiten implementar tareas de varios pasos para los usuarios. Esta página
se aborda cómo usar la
Clase GuidedStepSupportFragment
para guiar a un usuario a través de una serie de decisiones para realizar una tarea. GuidedStepSupportFragment
utiliza las prácticas recomendadas de la IU de TV para que las tareas de varios pasos sean fáciles de entender y navegar en dispositivos de TV.
Cómo proporcionar detalles para un paso
Una GuidedStepSupportFragment
representa un solo paso de una serie.
de pasos. Visualmente, proporciona una vista de guía con una
de acciones o decisiones posibles para el paso.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-screen.png?authuser=19&hl=es)
Figura 1: Ejemplo de paso guiado
Para cada paso de tu tarea de varios pasos, extiende
GuidedStepSupportFragment
y proporcionar información de contexto sobre
el paso y las acciones que el usuario puede realizar. Anular
onCreateGuidance()
y mostrar una nueva
GuidanceStylist.Guidance
que contiene contexto
información, como el título, la descripción y el ícono del paso, tal como se muestra en el siguiente ejemplo:
Kotlin
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) ) }
Java
@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); }
Agrega la subclase GuidedStepSupportFragment
a los elementos que desees.
de la actividad llamando
GuidedStepSupportFragment.add()
en el método onCreate()
de tu actividad.
Si tu actividad contiene solo GuidedStepSupportFragment
usa GuidedStepSupportFragment.addAsRoot()
en lugar de add()
para agregar la primera GuidedStepSupportFragment
. Usando
addAsRoot()
ayuda a garantizar que, si el usuario presiona el botón Atrás en el control remoto de la TV mientras mira contenido
el primer GuidedStepSupportFragment
, tanto
Se cierran GuidedStepSupportFragment
y la actividad superior.
Nota: Agregar
GuidedStepSupportFragment
de forma programática,
no en tus archivos de diseño en formato XML.
Cómo crear y administrar acciones de usuarios
Anulación para agregar acciones del usuario
onCreateActions()
En la anulación, agrega un GuidedAction
nuevo para cada
elemento de acción y proporcione la cadena de acción, la descripción y el ID. Usa
GuidedAction.Builder
para agregar nuevas acciones.
Kotlin
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()) ...
Java
@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()); ...
Las acciones no se limitan a selecciones de una sola línea. Estos son otros tipos de acciones que puedes crear:
-
Agrega una acción de etiqueta de información para proporcionar información adicional sobre las opciones del usuario mediante el parámetro de configuración
infoOnly(true)
CuandoinfoOnly
es verdadero, los usuarios no pueden seleccionar la acción. -
Configuración para agregar una acción de texto editable
editable(true)
Cuandoeditable
es verdadero, el usuario puede ingresar texto en una acción seleccionada usando el o un teclado conectado. AnularonGuidedActionEditedAndProceed()
para obtener el texto modificado que ingresó el usuario. También puedes anularonGuidedActionEditCanceled()
para saber cuándo el usuario cancela la entrada. -
Agrega un conjunto de acciones que se comporten como botones de selección que se pueden marcar con
checkSetId()
con un valor de ID común para agrupar acciones en un conjunto. Todas las acciones de la misma lista tienen el mismo del conjunto de verificación se consideran vinculados. Cuando el usuario selecciona una de las acciones de ese conjunto, esa acción quedará marcada y todas las demás acciones quedarán desmarcadas. -
Agrega una acción de selector de fecha con
GuidedDatePickerAction.Builder
en vez deGuidedAction.Builder
enonCreateActions()
. AnularonGuidedActionEditedAndProceed()
para obtener el valor de fecha modificado que ingresó el usuario. - Agrega una acción que use subacciones para que el usuario pueda elegir entre una lista extendida de y tomar una decisión. Las subacciones se describen en la sección Cómo agregar subacciones.
- Agrega una acción de botón que aparezca a la derecha de la lista de acciones y que se pueda accesible. Las acciones de botones se describen en el artículo Agregar botón acciones.
También puedes agregar un indicador visual de que cuando seleccionas una acción
lleva a un nuevo paso estableciendo
hasNext(true)
Para ver todos los atributos que puedes configurar, consulta la
GuidedAction
Para responder a acciones, anular
onGuidedActionClicked()
y procesa el
GuidedAction
Identifica la acción seleccionada por
examina GuidedAction.getId()
.
Cómo agregar subacciones
Algunas acciones podrían requerir que le des al usuario un conjunto adicional de opciones. R
GuidedAction
puede especificar una lista de
subacciones que se muestran como menú de acciones secundarias.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-subaction.png?authuser=19&hl=es)
Figura 2: Subacciones de pasos guiados
La lista de subacciones puede contener acciones normales o de botones de selección, pero y no con el selector de fecha ni con acciones de texto editables. Además, una subacción no puede tener un conjunto de subacciones porque el sistema no admite más de un nivel de subacciones.
Para agregar subacciones, crea y propaga una lista de
Objetos GuidedAction
que actúan como subacciones, como se muestra en el siguiente ejemplo:
Kotlin
subActions.add(GuidedAction.Builder() .id(SUBACTION1) .title(getString(R.string.guidedstep_subaction1_title)) .description(getString(R.string.guidedstep_subaction1_desc)) .build()) ...
Java
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()); ...
En onCreateActions()
, crea un evento de nivel superior.
GuidedAction
que muestra la
Lista de subacciones cuando se seleccionan:
Kotlin
... actions.add(GuidedAction.Builder() .id(SUBACTIONS) .title(getString(R.string.guidedstep_subactions_title)) .description(getString(R.string.guidedstep_subactions_desc)) .subActions(subActions) .build()) ...
Java
@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()); ... }
Por último, responde a las selecciones de subacciones anulando
onSubGuidedActionClicked()
:
Kotlin
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 }
Java
@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; }
Cómo agregar acciones de botones
Si tu paso guiado tiene una lista larga de acciones, es posible que los usuarios deban desplazarse por ella. para acceder a las acciones más usadas. Usa acciones de botones para separar acciones de uso frecuente de la lista de acciones. Las acciones de los botones aparecen junto a en la lista de acciones y sean fáciles de navegar.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-buttonaction.png?authuser=19&hl=es)
Figura 3: Acciones de botones de pasos guiados
Las acciones de botones se crean y manejan como las acciones normales, pero
acciones de botones en
onCreateButtonActions()
en lugar de onCreateActions()
. Responde a las acciones de los botones en
onGuidedActionClicked()
Usa las acciones de botones para acciones simples, como las de navegación entre pasos. No uses acciones de selección de fechas o editables como acciones de botones. Ten en cuenta que las acciones de botones no pueden tener subacciones.
Cómo agrupar pasos guiados en una secuencia guiada
Un GuidedStepSupportFragment
representa un solo paso. Para crear una secuencia ordenada de pasos, agrupa varios
GuidedStepSupportFragment
de forma conjunta con
GuidedStepSupportFragment.add()
para agregar
el siguiente paso en la secuencia hasta la pila de fragmentos.
Kotlin
override fun onGuidedActionClicked(action: GuidedAction) { val fm = fragmentManager when(action.id) { CONTINUE -> GuidedStepSupportFragment.add(fm, SecondStepFragment()) } }
Java
@Override public void onGuidedActionClicked(GuidedAction action) { FragmentManager fm = getFragmentManager(); if (action.getId() == CONTINUE) { GuidedStepSupportFragment.add(fm, new SecondStepFragment()); } ...
Si el usuario presiona el botón Atrás en el control remoto de la TV, el dispositivo muestra el anterior
GuidedStepSupportFragment
en la pila de fragmentos Si
y proporcionar tu propio GuidedAction
regresa al paso anterior, puedes implementar el comportamiento Atrás llamando
getFragmentManager().popBackStack()
Si necesitas que el usuario regrese a un paso anterior de la secuencia, usa
popBackStackToGuidedStepSupportFragment()
para volver a un GuidedStepSupportFragment
específico en la pila de fragmentos.
Cuando el usuario finalice el último paso de la secuencia, usa
finishGuidedStepSupportFragments()
para quitar todo
GuidedStepSupportFragment
instancia
de la pila actual y volver a la actividad principal original. Si el botón
se agregó el primer GuidedStepSupportFragment
usando addAsRoot()
, llamando
finishGuidedStepSupportFragments()
también cierra la actividad superior.
Cómo personalizar una presentación de pasos
La clase GuidedStepSupportFragment
puede usar objetos
temas que controlan aspectos de la presentación, como el formato del texto del título o la transición de pasos
animaciones. Los temas personalizados se deben heredar de
Theme_Leanback_GuidedStep
y puede proporcionar
anular valores para atributos definidos en
GuidanceStylist
y
GuidedActionsStylist
Para aplicar un tema personalizado a tu GuidedStepSupportFragment
, haz lo siguiente:
realiza una de las siguientes acciones:
-
Para aplicar el tema a la actividad principal, establece el atributo
android:theme
en el de actividad en el manifiesto de Android. Cuando configuras este atributo, se aplica el tema a todos los elementos y es la forma más directa de aplicar un tema personalizado si la actividad principal solo contieneGuidedStepSupportFragment
. -
Si tu actividad ya usa un tema personalizado y no quieres aplicarlo
GuidedStepSupportFragment
estilos a otras vistas de la actividad, agregaLeanbackGuidedStepTheme_guidedStepTheme
. a tu tema de actividad personalizado existente. Este atributo apunta al tema personalizado que solo los objetosGuidedStepSupportFragment
de tu y el uso de la actividad física. -
Si usas objetos
GuidedStepSupportFragment
en diferentes que son parte de la misma tarea general de varios pasos y que desean utilizar un tema visual en todos los pasos, anularGuidedStepSupportFragment.onProvideTheme()
y muestra el tema personalizado.
Para obtener más información sobre cómo agregar estilos y temas, consulta Estilos y temas.
La clase GuidedStepSupportFragment
usa
clases de estilo para acceder a atributos de temas y aplicarlos.
La clase GuidanceStylist
usa información sobre el tema
para controlar la presentación de la vista de guía izquierda, mientras que la
La clase GuidedActionsStylist
usa información del tema
para controlar la presentación de la vista de acciones derecha.
Para personalizar el estilo visual de tus pasos más allá de lo que proporciona la personalización del tema, crea subclases
GuidanceStylist
o
GuidedActionsStylist
y muestra tu subclase en
GuidedStepSupportFragment.onCreateGuidanceStylist()
o
GuidedStepSupportFragment.onCreateActionsStylist()
Para obtener detalles sobre lo que puedes personalizar en estas subclases, consulta la documentación sobre
GuidanceStylist
y
GuidedActionsStylist