Adicionar uma etapa guiada

Criar da melhor forma com o Compose
Crie interfaces incríveis com o mínimo de código usando o Jetpack Compose para o SO do Android TV.
Compose para TV →

Seu aplicativo pode ter tarefas em várias etapas para os usuários. Por exemplo, seu app pode precisar orientar usuários com a compra de conteúdo adicional, a definição de uma configuração complexa ou simplesmente confirmar uma decisão. Todas essas tarefas exigem que os usuários passem por uma ou mais tarefas etapas ou decisões.

A biblioteca androidx.pes fornece classes para implementar tarefas do usuário com várias etapas. Esta página discute como usar o Classe GuidedStepSupportFragment para orientar um usuário em uma série de decisões para realizar uma tarefa. GuidedStepSupportFragment usa as práticas recomendadas da interface da TV para facilitar a compreensão e a navegação de tarefas com várias etapas em dispositivos de TV.

Fornecer detalhes para uma etapa

Um GuidedStepSupportFragment representa uma única etapa de uma série. de passos. Visualmente, ela fornece uma orientação com uma lista de possíveis ações ou decisões para a etapa.

Figura 1. Um exemplo de uma etapa guiada.

Para cada etapa da tarefa de várias etapas, estenda GuidedStepSupportFragment e forneça informações de contexto sobre a etapa e as ações que o usuário pode realizar. Substituir onCreateGuidance() e retorna uma nova GuidanceStylist.Guidance que contém contexto informações, como título, descrição e ícone da etapa, conforme mostrado no exemplo a seguir:

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

Adicione a subclasse GuidedStepSupportFragment à que você quiser. a atividade chamando GuidedStepSupportFragment.add() no método onCreate() da sua atividade.

Se a atividade contiver apenas GuidedStepSupportFragment objetos, use GuidedStepSupportFragment.addAsRoot() em vez de add() para adicionar a primeira GuidedStepSupportFragment. Usando addAsRoot() ajuda a garantir que, se o usuário pressionar o botão "Voltar" no controle remoto da TV ao visualizar os primeiros GuidedStepSupportFragment, os O GuidedStepSupportFragment e a atividade mãe são fechados.

Observação:adicionar GuidedStepSupportFragment objetos de maneira programática, não nos arquivos XML de layout.

Criar e processar ações do usuário

Adicionar ações do usuário substituindo onCreateActions(): Na substituição, adicione um novo GuidedAction para cada item de ação e forneça a string de ação, a descrição e o ID. Usar GuidedAction.Builder para adicionar novas ações.

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

As ações não estão limitadas a seleções de linha única. Aqui estão outros tipos de ações que você pode criar:

  • Adicione uma ação de marcador de informações para fornecer mais informações sobre as opções do usuário configurando infoOnly(true): Quando infoOnly for verdadeiro, os usuários não poderão selecionar a ação.
  • Adicionar uma ação de texto editável configurando editable(true): Quando editable for verdadeiro, o usuário poderá inserir texto em uma ação selecionada usando o remoto ou um teclado conectado. Substituir onGuidedActionEditedAndProceed() para receber o texto modificado que o usuário digitou. Você também pode modificar onGuidedActionEditCanceled() para saber quando o usuário cancela a entrada.
  • Adicione um conjunto de ações que se comportam como botões de opção marcáveis usando checkSetId() com um valor de ID comum para agrupar ações em um conjunto. Todas as ações na mesma lista com o mesmo do conjunto de verificação são considerados vinculados. Quando o usuário seleciona uma das ações nesse conjunto, ação será marcada e todas as outras ações serão desmarcadas.
  • Adicione uma ação do seletor de data usando GuidedDatePickerAction.Builder em vez de GuidedAction.Builder em onCreateActions(). Substituir onGuidedActionEditedAndProceed() para receber o valor da data modificada que o usuário inseriu.
  • Adicione uma ação que use subações para permitir que o usuário escolha em uma lista estendida de e fazer escolhas melhores. As subações são descritas na seção Adicionar subações.
  • Adicione uma ação de botão que apareça à direita da lista de ações e seja fácil acessíveis. As ações do botão estão descritas no artigo Adicionar botão ações.

Também é possível adicionar um indicador visual de que a seleção de uma ação leva a uma nova etapa, definindo hasNext(true):

Para ver todos os atributos diferentes que você pode definir, consulte GuidedAction:

Para responder às ações, substitua onGuidedActionClicked() e processar os dados GuidedAction. Identifique a ação selecionada por examinando GuidedAction.getId().

Adicionar subações

Algumas ações podem exigir que você dê ao usuário um conjunto adicional de opções. Um GuidedAction pode especificar uma lista de que são exibidas como um menu de ações filhas.

Figura 2. Subações de etapas guiadas.

A lista de subações pode conter ações regulares ou ações do botão de opção, mas não seletor de data nem ações de texto editáveis. Além disso, uma subação não pode ter conjunto de subações, porque o sistema não oferece suporte a mais de um nível de subações.

Para adicionar subações, crie e preencha uma lista de Objetos GuidedAction que atuam como subações, conforme mostrado no exemplo a seguir:

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

No onCreateActions(), crie uma GuidedAction, que exibe o lista de subações quando selecionado:

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

Por fim, responda às seleções de subação substituindo 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;
}

Ações do botão "Adicionar"

Se a etapa guiada tiver uma lista grande de ações, talvez os usuários precisem rolar pela lista para acessar as ações mais usadas. Use os botões de ação para separar as ações mais usadas da lista. As ações do botão aparecem ao lado da lista de ações e sejam fáceis de navegar.

Figura 3. Ações de botão das etapas guiadas.

As ações do botão são criadas e processadas como as ações normais, mas você cria do botão de ações onCreateButtonActions() em vez de onCreateActions(). Responder às ações do botão em onGuidedActionClicked():

Use ações de botão para ações simples, como navegação entre etapas. Não use a ação do seletor de data ou outras ações editáveis como ações do botão. Além disso, as ações do botão não podem ter subações.

Agrupar etapas guiadas em uma sequência guiada

Um GuidedStepSupportFragment representa uma única etapa. Para criar uma sequência ordenada de etapas, agrupe vários GuidedStepSupportFragment objetos juntos usando GuidedStepSupportFragment.add() para adicionar a próxima etapa na sequência para a pilha de fragmentos.

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 o usuário pressionar o botão "Voltar" no controle remoto da TV, o dispositivo mostrará o botão anterior GuidedStepSupportFragment na pilha de fragmentos. Se você forneça seu próprio GuidedAction retornar à etapa anterior, é possível implementar o comportamento de retorno chamando getFragmentManager().popBackStack(). Se você precisar levar o usuário a uma etapa ainda mais antiga na sequência, use popBackStackToGuidedStepSupportFragment() para retornar a um GuidedStepSupportFragment específico na pilha de fragmentos.

Quando o usuário terminar a última etapa da sequência, use finishGuidedStepSupportFragments() para remover todos GuidedStepSupportFragment instâncias da pilha atual e retorna à atividade pai original. Se o o primeiro GuidedStepSupportFragment foi adicionado usando addAsRoot(), chamando O finishGuidedStepSupportFragments() também fecha a atividade mãe.

Personalizar a apresentação da etapa

A classe GuidedStepSupportFragment pode usar imagens temas que controlam aspectos da apresentação, como formatação do texto do título ou transição de etapas animações. Os temas personalizados precisam herdar de Theme_Leanback_GuidedStep e podem fornecer valores para atributos definidos GuidanceStylist e GuidedActionsStylist

Para aplicar um tema personalizado ao GuidedStepSupportFragment, faça o seguinte: siga um destes procedimentos:

  • Aplique o tema à atividade pai definindo o atributo android:theme como o no manifesto do Android. Definir este atributo aplica o tema a todos os filhos e é a maneira mais direta de aplicar um tema personalizado caso a atividade pai contenha apenas GuidedStepSupportFragment.
  • Se a atividade já usa um tema personalizado e você não quer aplicar GuidedStepSupportFragment para outras visualizações na atividade, adicione o LeanbackGuidedStepTheme_guidedStepTheme ao seu tema de atividade personalizado já existente. Esse atributo aponta para o tema personalizado que somente os objetos GuidedStepSupportFragment na sua uso em atividades.
  • Se você usar objetos GuidedStepSupportFragment em diferentes atividades que fazem parte da mesma tarefa geral de várias etapas e desejam usar uma abordagem o tema visual em todas as etapas, substituir GuidedStepSupportFragment.onProvideTheme() e retorna o tema personalizado.

Para mais informações sobre como adicionar estilos e temas, consulte Estilos e temas.

A classe GuidedStepSupportFragment usa recursos classes de estilo para acessar e aplicar atributos de tema. A classe GuidanceStylist usa informações de tema. para controlar a apresentação da orientação esquerda, enquanto A classe GuidedActionsStylist usa informações de tema para controlar a apresentação da visualização das ações corretas.

Para personalizar o estilo visual dos seus passos além do que a personalização de temas oferece, faça uma subclasse GuidanceStylist ou GuidedActionsStylist e retornar a subclasse em GuidedStepSupportFragment.onCreateGuidanceStylist() ou GuidedStepSupportFragment.onCreateActionsStylist(). Para mais detalhes sobre o que é possível personalizar nessas subclasses, consulte a documentação GuidanceStylist e GuidedActionsStylist.

Anterior
Apresentar novos usuários ao seu app
Próxima
Modo de som ambiente