La tua applicazione potrebbe prevedere attività in più passaggi per gli utenti. Ad esempio, la tua app potrebbe dover utenti tramite l'acquisto di contenuti aggiuntivi, l'impostazione di complesse impostazioni di configurazione o semplicemente confermando una decisione. Tutte queste attività richiedono la guida degli utenti attraverso uno o più passaggi ordinati passaggi o decisioni.
La libreria androidx.leanback fornisce corsi per implementare attività utente in più passaggi. Questa pagina
illustra come utilizzare
GuidedStepSupportFragment
corso
per guidare l'utente attraverso una serie di decisioni al fine di portare a termine un'attività. GuidedStepSupportFragment
usa le best practice relative all'interfaccia utente TV per semplificare la comprensione e la navigazione delle attività in più passaggi sui dispositivi TV.
Fornire i dettagli di un passaggio
Un GuidedStepSupportFragment
rappresenta un singolo passaggio in una serie
di passaggi. Visivamente, fornisce una visualizzazione guida con un
un elenco di possibili azioni o decisioni per il passaggio.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-screen.png?authuser=1&hl=it)
Figura 1. Esempio di passaggio guidato.
Per ogni passaggio dell'attività in più passaggi, estendi
GuidedStepSupportFragment
e fornire informazioni contestuali su
il passaggio e le azioni che l'utente può eseguire. Esegui override
onCreateGuidance()
e restituirà un nuovo
GuidanceStylist.Guidance
che contiene contesto
informazioni, come titolo, descrizione e icona del passaggio, come mostrato nell'esempio seguente:
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); }
Aggiungi la sottoclasse GuidedStepSupportFragment
a ciò che preferisci
attività chiamando
GuidedStepSupportFragment.add()
nel metodo onCreate()
della tua attività.
Se la tua attività contiene solo GuidedStepSupportFragment
usa GuidedStepSupportFragment.addAsRoot()
anziché add()
per aggiungere il primo GuidedStepSupportFragment
. Utilizzo
addAsRoot()
aiuta a garantire che se l'utente preme il pulsante Indietro sul telecomando della TV durante la visione
i primi GuidedStepSupportFragment
, entrambi
GuidedStepSupportFragment
e l'attività genitore vengono chiusi.
Nota:aggiungi
GuidedStepSupportFragment
oggetti in modo programmatico,
non presenti nei file XML di layout.
Creare e gestire le azioni degli utenti
Aggiungi azioni utente tramite l'override
onCreateActions()
.
Nell'override, aggiungi un nuovo GuidedAction
per ogni
e fornire la stringa di azione, la descrizione e l'ID. Utilizza le funzionalità di
GuidedAction.Builder
per aggiungere nuove azioni.
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()); ...
Le azioni non si limitano alle selezioni su una sola riga. Di seguito sono riportati altri tipi di azioni che puoi creare:
-
Imposta un'azione per aggiungere un'etichetta di informazioni per fornire ulteriori informazioni sulle scelte dell'utente
infoOnly(true)
. Se il valoreinfoOnly
è impostato su true, gli utenti non possono selezionare l'azione. -
Aggiungi un'azione di testo modificabile tramite l'impostazione
editable(true)
. Quando il criterioeditable
è impostato su true, l'utente può inserire testo in un'azione selezionata utilizzando i telecomando o una tastiera connessa. Esegui overrideonGuidedActionEditedAndProceed()
per ottenere il testo modificato inserito dall'utente. Puoi anche eseguire l'override dionGuidedActionEditCanceled()
per sapere quando l'utente annulla l'input. -
Aggiungi un insieme di azioni che si comportano come pulsanti di opzione selezionabili utilizzando
checkSetId()
con un valore ID comune per raggruppare le azioni in un insieme. Tutte le azioni nello stesso elenco hanno lo stesso ID set di controlli sono considerati collegati. Quando l'utente seleziona una delle azioni del set, l'azione viene selezionata e tutte le altre azioni vengono deselezionate. -
Aggiungi un'azione del selettore della data utilizzando
GuidedDatePickerAction.Builder
anzichéGuidedAction.Builder
aonCreateActions()
. Esegui overrideonGuidedActionEditedAndProceed()
per ottenere il valore della data di modifica inserito dall'utente. - Aggiungi un'azione che utilizza le sottoazioni per consentire all'utente di scegliere da un elenco esteso di scelte. Le sottoazioni sono descritte nella sezione Aggiungi azioni secondarie.
- Consente di aggiungere un'azione del pulsante facilmente visibile a destra dell'elenco delle azioni accessibili. Le azioni dei pulsanti sono descritte nella sezione Pulsante Aggiungi azioni.
Puoi anche aggiungere un indicatore visivo che indichi un'azione
porta a un nuovo passaggio attraverso l'impostazione
hasNext(true)
.
Per tutti i diversi attributi che puoi impostare, consulta
GuidedAction
.
Per rispondere alle azioni, sostituisci
onGuidedActionClicked()
ed elaborerai la richiesta
GuidedAction
. Identifica l'azione selezionata per
esame di GuidedAction.getId()
.
Aggiungi azioni secondarie
Alcune azioni potrebbero richiedere di offrire all'utente ulteriori opzioni. R
GuidedAction
può specificare un elenco di
secondarie visualizzate come un menu di azioni secondarie.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-subaction.png?authuser=1&hl=it)
Figura 2. Subazioni ai passaggi guidati.
L'elenco di sottoazioni può contenere azioni regolari o azioni di pulsanti di opzione, ma non sul selettore della data né sulle azioni di testo modificabili. Inoltre, una sottoazione non può avere una propria insieme di azioni secondarie, poiché il sistema non supporta più di un livello di azioni secondarie.
Per aggiungere azioni secondarie, devi prima creare e completare un elenco di
GuidedAction
di oggetti che agiscono come azioni secondarie, come mostrato nell'esempio seguente:
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()); ...
In onCreateActions()
, crea un'istanza di primo livello
GuidedAction
che mostra
elenco di azioni secondarie quando selezionato:
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()); ... }
Infine, rispondi alle selezioni delle sottoazioni eseguendo l'override
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; }
Aggiungi azioni pulsante
Se l'elenco di azioni del passaggio guidato è lungo, gli utenti potrebbero dover scorrere l'elenco per accedere alle azioni di uso più comune. Usa le azioni dei pulsanti per separare azioni di uso comune nell'elenco delle azioni. Le azioni dei pulsanti sono visualizzate accanto a all'elenco di azioni e sono facili da navigare.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-buttonaction.png?authuser=1&hl=it)
Figura 3. Azioni dei pulsanti dei passaggi guidati.
Le azioni dei pulsanti vengono create e gestite come le azioni normali, ma tu crei
le azioni dei pulsanti in
onCreateButtonActions()
anziché onCreateActions()
. Rispondi alle azioni dei pulsanti in
onGuidedActionClicked()
.
Utilizza le azioni dei pulsanti per azioni semplici, ad esempio le azioni di navigazione tra i passaggi. Non utilizzare l'azione del selettore della data o altre azioni modificabili come azioni dei pulsanti. Inoltre, le azioni dei pulsanti non possono avere azioni secondarie.
Raggruppa i passaggi guidati in una sequenza guidata
GuidedStepSupportFragment
rappresenta un singolo passaggio. Per creare una sequenza ordinata di passaggi, raggruppa più
GuidedStepSupportFragment
di oggetti insieme utilizzando
GuidedStepSupportFragment.add()
da aggiungere
il passaggio successivo della sequenza allo stack di frammenti.
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()); } ...
Se l'utente preme il pulsante Indietro sul telecomando della TV, il dispositivo mostra la precedente
GuidedStepSupportFragment
nell'elenco di frammenti. Se
fornisci il tuo GuidedAction
che
al passaggio precedente, puoi implementare il comportamento Indietro richiamando
getFragmentManager().popBackStack()
.
Se devi riportare l'utente a un passaggio ancora precedente della sequenza, utilizza
popBackStackToGuidedStepSupportFragment()
per tornare a uno specifico GuidedStepSupportFragment
nello stack di frammenti.
Quando l'utente termina l'ultimo passaggio della sequenza, utilizza
finishGuidedStepSupportFragments()
per rimuovere tutti
GuidedStepSupportFragment
istanze
dallo stack attuale e tornare all'attività principale originale. Se
il primo GuidedStepSupportFragment
è stato aggiunto
utilizzando addAsRoot()
, chiamando
finishGuidedStepSupportFragments()
chiude anche l'attività principale.
Personalizza la presentazione dei passaggi
Il corso GuidedStepSupportFragment
può utilizzare impostazioni personalizzate
temi che controllano aspetti della presentazione, come la formattazione del testo del titolo o la transizione dei passaggi
le animazioni. I temi personalizzati devono ereditare da
Theme_Leanback_GuidedStep
e può fornire
l'override dei valori per gli attributi definiti in
GuidanceStylist
e
GuidedActionsStylist
.
Per applicare un tema personalizzato a GuidedStepSupportFragment
:
esegui una delle seguenti operazioni:
-
Applica il tema all'attività principale impostando l'attributo
android:theme
su elemento activity nel file manifest di Android. L'impostazione di questo attributo applica il tema a tutti i bambini ed è il modo più diretto per applicare un tema personalizzato se l'attività principale contiene soloGuidedStepSupportFragment
oggetti. -
Se la tua attività utilizza già un tema personalizzato e non vuoi applicarlo
GuidedStepSupportFragment
stili alle altre visualizzazioni nell'attività, aggiungiLeanbackGuidedStepTheme_guidedStepTheme
al tema di attività personalizzato esistente. Questo attributo rimanda al tema personalizzato che solo gli oggettiGuidedStepSupportFragment
in uso dell'attività. -
Se utilizzi
GuidedStepSupportFragment
oggetti in diversi che fanno parte della stessa attività in più passaggi complessiva e che desiderano utilizzare un insieme tema visivo in tutti i passaggi, overrideGuidedStepSupportFragment.onProvideTheme()
e restituisci il tema personalizzato.
Per ulteriori informazioni su come aggiungere stili e temi, vedi Stili e temi.
Il corso GuidedStepSupportFragment
utilizza l'offerta speciale
classi di stilisti per accedere agli attributi tema e applicarli.
Il corso GuidanceStylist
utilizza le informazioni sul tema
per controllare la presentazione della visualizzazione della guida a sinistra, mentre
Il corso GuidedActionsStylist
utilizza le informazioni sul tema
per controllare la presentazione
della visualizzazione delle azioni giusta.
Per personalizzare lo stile visivo dei passaggi oltre a ciò che offre la personalizzazione del tema, la sottoclasse
GuidanceStylist
o
GuidedActionsStylist
e restituisci la sottoclasse in
GuidedStepSupportFragment.onCreateGuidanceStylist()
o
GuidedStepSupportFragment.onCreateActionsStylist()
.
Per maggiori dettagli su cosa puoi personalizzare in queste sottoclassi, consulta la documentazione su
GuidanceStylist
e
GuidedActionsStylist
.