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.
![](https://developer.android.google.cn/static/images/training/tv/playback/guided-step-screen.png?authuser=19&hl=pt-br)
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)
: QuandoinfoOnly
for verdadeiro, os usuários não poderão selecionar a ação. -
Adicionar uma ação de texto editável configurando
editable(true)
: Quandoeditable
for verdadeiro, o usuário poderá inserir texto em uma ação selecionada usando o remoto ou um teclado conectado. SubstituironGuidedActionEditedAndProceed()
para receber o texto modificado que o usuário digitou. Você também pode modificaronGuidedActionEditCanceled()
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 deGuidedAction.Builder
emonCreateActions()
. SubstituironGuidedActionEditedAndProceed()
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.
![](https://developer.android.google.cn/static/images/training/tv/playback/guided-step-subaction.png?authuser=19&hl=pt-br)
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.
![](https://developer.android.google.cn/static/images/training/tv/playback/guided-step-buttonaction.png?authuser=19&hl=pt-br)
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 apenasGuidedStepSupportFragment
. -
Se a atividade já usa um tema personalizado e você não quer aplicar
GuidedStepSupportFragment
para outras visualizações na atividade, adicione oLeanbackGuidedStepTheme_guidedStepTheme
ao seu tema de atividade personalizado já existente. Esse atributo aponta para o tema personalizado que somente os objetosGuidedStepSupportFragment
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, substituirGuidedStepSupportFragment.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
.