Aggiungere un passaggio guidato

Migliora la creazione con Compose

Crea splendide UI con un minimo codice utilizzando Jetpack Compose per il sistema operativo Android TV.

Scrivi per la TV →

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.

Figura 1. Esempio di passaggio guidato.

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:

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

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.

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

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 valore infoOnly è impostato su true, gli utenti non possono selezionare l'azione.
• Aggiungi un'azione di testo modificabile impostando editable(true). Se il criterio editable è impostato su true, l'utente può inserire testo in un'azione selezionata utilizzando il telecomando o una tastiera collegata. Sostituisci onGuidedActionEditedAndProceed() per ottenere il testo modificato inserito dall'utente. Puoi anche eseguire l'override di onGuidedActionEditCanceled() 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 in onCreateActions(). Esegui l'override di onGuidedActionEditedAndProceed() 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.

Figura 2. Subazioni ai passaggi guidati.

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:

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

In onCreateActions(), crea un GuidedAction di primo livello che mostri l'elenco delle sottoazioni, se selezionato:

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

Infine, rispondi alle selezioni delle sottoazioni eseguendo l'override di 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;
}

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.

Figura 3. Azioni dei pulsanti dei passaggi guidati.

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.

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

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 solo GuidedStepSupportFragment oggetti.
• Se la tua attività utilizza già un tema personalizzato e non vuoi applicare gli stili GuidedStepSupportFragment ad altre visualizzazioni dell'attività, aggiungi l'attributo LeanbackGuidedStepTheme_guidedStepTheme al tema attività personalizzato esistente. Questo attributo rimanda al tema personalizzato che utilizza solo gli oggetti GuidedStepSupportFragment 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, sostituisci GuidedStepSupportFragment.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.