Aggiungere un passaggio guidato

Creare app migliori con Compose

Crea UI accattivanti con un codice minimo utilizzando Jetpack Compose per Android TV OS.

Compose per TV →

La tua applicazione potrebbe avere attività in più passaggi per gli utenti. Ad esempio, la tua app potrebbe dover guidare gli utenti nell'acquisto di contenuti aggiuntivi, nella configurazione di un'impostazione complessa o nella conferma di una decisione. Tutte queste attività richiedono di guidare gli utenti attraverso uno o più passaggi o decisioni in ordine.

La libreria androidx.leanback ritirata fornisce classi per implementare attività utente in più passaggi. Questa pagina spiega come utilizzare la GuidedStepSupportFragment classe per guidare un utente attraverso una serie di decisioni per completare un'attività utilizzando GuidedStepSupportFragment.

Fornire dettagli per un passaggio

Un GuidedStepSupportFragment rappresenta un singolo passaggio in una serie di passaggi. Visivamente, fornisce una visualizzazione di guida con un elenco di possibili azioni o decisioni per il passaggio.

Figura 1. Un esempio di passaggio guidato.

Per ogni passaggio dell'attività in più passaggi, estendi GuidedStepSupportFragment e fornisci informazioni di contesto su il passaggio e sulle azioni che l'utente può intraprendere. Esegui l'override onCreateGuidance() e restituisci un nuovo GuidanceStylist.Guidance che contenga informazioni di 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 GuidedStepSupportFragment oggetti, utilizza GuidedStepSupportFragment.addAsRoot() anziché add() per aggiungere il primo GuidedStepSupportFragment. L'utilizzo di addAsRoot() consente di garantire che, se l'utente preme il pulsante Indietro sul telecomando della TV quando visualizza il primo GuidedStepSupportFragment, vengano chiusi sia GuidedStepSupportFragment sia l'attività principale.

Nota: aggiungi gli oggetti GuidedStepSupportFragment a livello di programmazione, non nei file XML di layout.

Creare e gestire le azioni utente

Aggiungi le azioni utente eseguendo l'override di onCreateActions(). Nell'override, aggiungi un nuovo GuidedAction per ogni attività e fornisci la stringa, la descrizione e l'ID dell'azione. 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 sono limitate a selezioni su una sola riga. Ecco altri tipi di azioni che puoi creare:

• Aggiungi un'azione di etichetta informativa per fornire ulteriori informazioni sulle scelte dell'utente impostando infoOnly(true). Quando infoOnly è true, gli utenti non possono selezionare l'azione.
• Aggiungi un'azione di testo modificabile impostando editable(true). Quando editable è true, l'utente può inserire testo in un'azione selezionata utilizzando il telecomando o una tastiera collegata. Esegui l'override di 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 di insieme di controllo sono considerate collegate. Quando l'utente seleziona una delle azioni all'interno dell'insieme, questa viene selezionata e tutte le altre azioni vengono deselezionate.
• Aggiungi un'azione di selezione della data utilizzando GuidedDatePickerAction.Builder anziché GuidedAction.Builder in onCreateActions(). Esegui l'override di onGuidedActionEditedAndProceed() per ottenere il valore della data modificato inserito dall'utente.
• Aggiungi un'azione che utilizza le sottoazioni per consentire all'utente di scegliere da un elenco esteso di opzioni. Le sottoazioni sono descritte nella sezione Aggiungere sottoazioni.
• Aggiungi un'azione del pulsante che viene visualizzata a destra dell'elenco delle azioni ed è facilmente accessibile. Le azioni dei pulsanti sono descritte nella sezione Aggiungere azioni dei pulsanti.

Puoi anche aggiungere un indicatore visivo che indica che la selezione di un'azione porta a un nuovo passaggio impostando hasNext(true).

Per tutti i diversi attributi che puoi impostare, vedi GuidedAction.

Per rispondere alle azioni, esegui l'override di onGuidedActionClicked() ed elabora GuidedAction passato. Identifica l'azione selezionata esaminando GuidedAction.getId().

Aggiungere sottoazioni

Alcune azioni potrebbero richiedere di fornire all'utente un insieme aggiuntivo di scelte. Un GuidedAction può specificare un elenco di sottoazioni che vengono visualizzate come menu di azioni secondarie.

Figura 2. Sottoazioni del passaggio guidato.

L'elenco delle sottoazioni può contenere azioni normali o azioni dei pulsanti di opzione, ma non azioni di selezione della data o di testo modificabile. Inoltre, una sottoazione non può avere il proprio insieme di sottoazioni, perché il sistema non supporta più di un livello di sottoazioni.

Per aggiungere sottoazioni, crea e compila innanzitutto un elenco di oggetti GuidedAction che fungano da sottoazioni, 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 visualizzi l'elenco delle sottoazioni quando viene 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;
}

Aggiungere azioni dei pulsanti

Se il passaggio guidato ha un lungo elenco di azioni, gli utenti potrebbero dover scorrere l'elenco per accedere alle azioni di uso comune. Utilizza 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 del passaggio guidato.

Le azioni dei pulsanti vengono create e gestite come le azioni normali, ma vengono create azioni dei pulsanti in onCreateButtonActions() anziché in onCreateActions(). Rispondi alle azioni dei pulsanti in onGuidedActionClicked().

Utilizza le azioni dei pulsanti per azioni semplici, come le azioni di navigazione tra i passaggi. Non utilizzare l'azione di selezione della data o altre azioni modificabili come azioni dei pulsanti. Inoltre, le azioni dei pulsanti non possono avere sottoazioni.

Raggruppare i passaggi guidati in una sequenza guidata

Un GuidedStepSupportFragment rappresenta un singolo passaggio. Per creare una sequenza ordinata di passaggi, raggruppa più GuidedStepSupportFragment oggetti insieme utilizzando GuidedStepSupportFragment.add() per aggiungere il passaggio successivo nella sequenza allo stack 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 nello stack di frammenti. Se fornisci il tuo GuidedAction che torna al passaggio precedente, puoi implementare il comportamento Indietro chiamando getFragmentManager().popBackStack(). Se devi riportare l'utente a un passaggio precedente della sequenza, utilizza popBackStackToGuidedStepSupportFragment() per tornare a un GuidedStepSupportFragment specifico nello stack di frammenti.

Quando l'utente completa l'ultimo passaggio della sequenza, utilizza finishGuidedStepSupportFragments() per rimuovere tutte le istanze GuidedStepSupportFragment dallo stack corrente e tornare all'attività principale originale. Se il primo GuidedStepSupportFragment viene aggiunto utilizzando addAsRoot(), la chiamata a finishGuidedStepSupportFragments() chiude anche l'attività principale.

Personalizzare la presentazione dei passaggi

La classe GuidedStepSupportFragment può utilizzare temi personalizzati che controllano aspetti di presentazione come la formattazione del testo del titolo o le animazioni di transizione 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 dell'attività nel file manifest di Android. L'impostazione di questo attributo applica il tema a tutte le visualizzazioni secondarie ed è il modo più semplice per applicare un tema personalizzato se l'attività principale contiene solo oggetti GuidedStepSupportFragment.
• Se l'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 dell'attività personalizzata esistente. Questo attributo rimanda al tema personalizzato utilizzato solo dagli oggetti GuidedStepSupportFragment nell'attività.
• Se utilizzi oggetti GuidedStepSupportFragment in attività diverse che fanno parte della stessa attività complessiva in più passaggi e vuoi utilizzare un tema visivo coerente in tutti i passaggi, esegui l'override di GuidedStepSupportFragment.onProvideTheme() e restituisci il tema personalizzato.

Per ulteriori informazioni su come aggiungere stili e temi, vedi Stili e temi.

La classe GuidedStepSupportFragment utilizza speciali classi di stile per accedere agli attributi del tema e applicarli. La classe GuidanceStylist utilizza le informazioni del tema per controllare la presentazione della visualizzazione di guida a sinistra, mentre la classe GuidedActionsStylist utilizza le informazioni del tema per controllare la presentazione della visualizzazione delle azioni a destra.

Per personalizzare lo stile visivo dei passaggi oltre a quanto fornito dalla personalizzazione del tema, crea una sottoclasse di GuidanceStylist o GuidedActionsStylist e restituisci la sottoclasse in GuidedStepSupportFragment.onCreateGuidanceStylist() o GuidedStepSupportFragment.onCreateActionsStylist(). Per informazioni dettagliate su ciò che puoi personalizzare in queste sottoclassi, consulta la documentazione relativa a GuidanceStylist e GuidedActionsStylist.