La tua applicazione potrebbe prevedere attività in più passaggi per gli utenti. Ad esempio, la tua app potrebbe dover guidare gli utenti nell'acquisto di contenuti aggiuntivi, impostando un'impostazione di configurazione complessa o semplicemente confermando una decisione. Tutte queste attività richiedono la guida degli utenti attraverso uno o più passaggi o decisioni ordinate.
La libreria androidx.leanback fornisce corsi per implementare attività utente in più passaggi. Questa pagina illustra come utilizzare il corso GuidedStepSupportFragment
per guidare un utente attraverso una serie di decisioni al fine di portare a termine un'attività. GuidedStepSupportFragment
utilizza le best practice relative all'UI 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. A livello visivo, fornisce una visualizzazione
con un elenco di possibili azioni o decisioni per il passaggio.
Per ogni passaggio dell'attività in più passaggi, estendi GuidedStepSupportFragment
e fornisci informazioni contestuali sul passaggio e sulle azioni che l'utente può eseguire. Esegui l'override di
onCreateGuidance()
e restituisci un nuovo
GuidanceStylist.Guidance
contenente informazioni sul contesto,
come il titolo, la descrizione e l'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
all'attività desiderata chiamando
GuidedStepSupportFragment.add()
nel metodo onCreate()
dell'attività.
Se l'attività contiene solo oggetti GuidedStepSupportFragment
, utilizza GuidedStepSupportFragment.addAsRoot()
anziché add()
per aggiungere il primo GuidedStepSupportFragment
. L'utilizzo dell'addAsRoot()
aiuta a garantire che se l'utente preme il pulsante Indietro sul telecomando della TV durante la visualizzazione del primo GuidedStepSupportFragment
, venga chiusa l'attività di GuidedStepSupportFragment
e quella del genitore.
Nota: aggiungi GuidedStepSupportFragment
oggetti in modo programmatico, non nei file XML di layout.
Creare e gestire le azioni degli utenti
Aggiungi azioni utente eseguendo l'override di onCreateActions()
.
Nell'override, aggiungi un nuovo GuidedAction
per ogni attività e fornisci la stringa di azione, la descrizione e l'ID. Utilizza 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. Ecco altri tipi di azioni che puoi creare:
-
Aggiungi un'azione di etichetta delle informazioni per fornire ulteriori informazioni sulle scelte dell'utente impostando
infoOnly(true)
. Se il valoreinfoOnly
è impostato su true, gli utenti non possono selezionare l'azione. -
Aggiungi un'azione di testo modificabile impostando
editable(true)
. Se il criterioeditable
è impostato su true, l'utente può inserire testo in un'azione selezionata utilizzando il telecomando o una tastiera collegata. SostituiscionGuidedActionEditedAndProceed()
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 con lo stesso ID set di controllo sono considerate collegate. Quando l'utente seleziona una delle azioni all'interno dell'insieme, questa azione viene selezionata e tutte le altre vengono deselezionate. -
Aggiungi un'azione del selettore della data utilizzando
GuidedDatePickerAction.Builder
anzichéGuidedAction.Builder
inonCreateActions()
. Esegui l'override dionGuidedActionEditedAndProceed()
per ottenere il valore della data di modifica inserito dall'utente. - Aggiungi un'azione che utilizzi le sottoazioni per consentire all'utente di scegliere da un elenco esteso di opzioni. Le sottoazioni sono descritte nella sezione Aggiungi azioni secondarie.
- Aggiungi un'azione del pulsante, visualizzata a destra dell'elenco delle azioni e facilmente accessibile. Le azioni dei pulsanti sono descritte nella sezione Aggiungi azioni pulsante.
Puoi anche aggiungere un indicatore visivo che indichi che la selezione di un'azione
porta a un nuovo passaggio impostando
hasNext(true)
.
Per tutti i diversi attributi che puoi impostare, consulta
GuidedAction
.
Per rispondere alle azioni, esegui l'override di onGuidedActionClicked()
ed elabora il GuidedAction
trasmesso. Identifica l'azione selezionata
esaminando GuidedAction.getId()
.
Aggiungi azioni secondarie
Alcune azioni potrebbero richiedere di offrire all'utente ulteriori opzioni. Un
GuidedAction
può specificare un elenco di
sottoazioni che vengono visualizzate come un menu di azioni secondarie.
L'elenco di sottoazioni può contenere azioni regolari o azioni dei pulsanti di opzione, ma non il selettore della data o le azioni di testo modificabili. Inoltre, una sottoazione non può avere un proprio insieme di sottoazioni, poiché il sistema non supporta più di un livello di sottoazioni.
Per aggiungere azioni secondarie, devi prima creare e completare un elenco di
oggetti GuidedAction
che fungono da 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 GuidedAction
di primo livello che mostri
l'elenco delle sottoazioni, se 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 di
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 il passaggio guidato include un lungo elenco di azioni, gli utenti potrebbero dover scorrere l'elenco per accedere a quelle di uso più comune. Usa le azioni dei pulsanti per separare le azioni di uso comune dall'elenco delle azioni. Le azioni dei pulsanti vengono visualizzate accanto all'elenco delle azioni e sono facili da raggiungere.
Le azioni dei pulsanti vengono create e gestite come le azioni normali, ma puoi crearle in onCreateButtonActions()
anziché in onCreateActions()
. Rispondere 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
L'elemento GuidedStepSupportFragment
rappresenta un singolo passaggio. Per creare una sequenza ordinata di passaggi, raggruppa più oggetti GuidedStepSupportFragment
utilizzando GuidedStepSupportFragment.add()
per aggiungere il passaggio successivo della sequenza all'elenco 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 il
GuidedStepSupportFragment
precedente nell'elenco di frammenti. Se fornisci il tuo GuidedAction
per tornare 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 un elemento GuidedStepSupportFragment
specifico nell'elenco di frammenti.
Quando l'utente completa l'ultimo passaggio della sequenza, usa finishGuidedStepSupportFragments()
per rimuovere tutte le GuidedStepSupportFragment
istanze dallo stack attuale e tornare all'attività principale originale. Se il primo GuidedStepSupportFragment
viene aggiunto utilizzando addAsRoot()
, la chiamata a finishGuidedStepSupportFragments()
comporta anche la chiusura dell'attività principale.
Personalizza la presentazione dei passaggi
La classe GuidedStepSupportFragment
può utilizzare temi personalizzati che controllano gli aspetti della presentazione, come la formattazione del testo del titolo o le animazioni delle transizioni dei passaggi. I temi personalizzati devono ereditare da
Theme_Leanback_GuidedStep
e possono fornire
valori di override per gli attributi definiti in
GuidanceStylist
e
GuidedActionsStylist
.
Per applicare un tema personalizzato a GuidedStepSupportFragment
,
procedi in uno dei seguenti modi:
-
Applica il tema all'attività principale impostando l'attributo
android:theme
sull'elemento attività nel file manifest di Android. La configurazione di questo attributo consente di applicare il tema a tutte le viste secondarie 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 applicare gli stili
GuidedStepSupportFragment
ad altre visualizzazioni dell'attività, aggiungi l'attributoLeanbackGuidedStepTheme_guidedStepTheme
al tema attività personalizzato esistente. Questo attributo rimanda al tema personalizzato che utilizza solo gli oggettiGuidedStepSupportFragment
nella tua attività. -
Se utilizzi oggetti
GuidedStepSupportFragment
in diverse attività che fanno parte della stessa attività in più passaggi generale e vuoi utilizzare un tema visivo coerente in tutti i passaggi, sostituisciGuidedStepSupportFragment.onProvideTheme()
e restituisci il tema personalizzato.
Per ulteriori informazioni su come aggiungere stili e temi, consulta Stili e temi.
Il corso GuidedStepSupportFragment
utilizza classi di stilisti speciali per accedere agli attributi del tema e applicarli.
Il corso GuidanceStylist
usa le informazioni sul tema
per controllare la presentazione della visualizzazione della guida sinistra, mentre il
corso GuidedActionsStylist
usa le informazioni sul tema
per controllare la presentazione della visualizzazione delle azioni a destra.
Per personalizzare lo stile visivo dei passaggi oltre alla personalizzazione del tema, utilizza 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
.