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 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.

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:

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 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.

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. 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 valore infoOnly è impostato su true, gli utenti non possono selezionare l'azione.
• Aggiungi un'azione di testo modificabile tramite l'impostazione editable(true). Quando il criterio editable è impostato su true, l'utente può inserire testo in un'azione selezionata utilizzando i telecomando o una tastiera connessa. Esegui override 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 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 a onCreateActions(). Esegui override onGuidedActionEditedAndProceed() 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.

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:

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'istanza di primo livello GuidedAction che mostra elenco di azioni secondarie quando 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 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 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.

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.

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