O segundo Visualização do Desenvolvedor do Android 11 já está disponível, teste e compartilhe seu feedback.

Primeiros passos com o componente de navegação

Este tópico mostra como configurar e trabalhar com o componente de navegação. Para ter uma visão geral de alto nível do componente de navegação, consulte Visão geral da navegação.

Configurar o ambiente

Para incluir o suporte de navegação no seu projeto, adicione as seguintes dependências ao arquivo build.gradle do seu app:

Para ver informações sobre como adicionar outros componentes de arquitetura ao seu projeto, consulte Como adicionar componentes ao seu projeto.

Criar um gráfico de navegação

A navegação ocorre entre os destinos do seu app, ou seja, em qualquer lugar no app em que os usuários possam navegar. Esses destinos são conectados por meio de ações.

Um gráfico de navegação é um arquivo de recursos que contém todos os seus destinos e ações. O gráfico representa todos os caminhos de navegação do seu app.

A Figura 1 mostra uma representação visual de um gráfico de navegação para um app de amostra que contém seis destinos conectados por cinco ações. Cada destino é representado por uma miniatura de visualização, e as ações de conexão são representadas por setas que mostram como os usuários podem navegar de um destino para outro.

Figura 1. Um gráfico de navegação que mostra visualizações de seis destinos diferentes conectados por meio de cinco ações.
  1. Destinos são as diferentes áreas de conteúdo do seu app.
  2. Ações são conexões lógicas entre seus destinos que representam os caminhos que os usuários podem seguir.

Para adicionar um gráfico de navegação ao projeto, faça o seguinte:

  1. Na janela "Project", clique com o botão direito do mouse no diretório res e selecione New > Android Resource File. A caixa de diálogo New Resource File é exibida.
  2. Digite um nome no campo File name, por exemplo, "nav_graph".
  3. Selecione Navigation na lista suspensa Resource type e clique em OK.
  4. Quando você adiciona seu primeiro gráfico de navegação, o Android Studio cria um diretório de recursos navigation dentro do diretório res. Esse diretório contém seu arquivo de recurso de gráfico de navegação (nav_graph.xml, por exemplo).

    Depois de adicionar um gráfico, o Android Studio abre o gráfico no Navigation Editor. No Navigation Editor, você pode editar visualmente os gráficos de navegação ou editar diretamente o XML subjacente.

    Figura 2. O Navigation Editor
    1. Painel Destinations: lista seu host de navegação e todos os destinos atualmente no Graph Editor.
    2. Graph Editor: contém uma representação visual do seu gráfico de navegação. Você pode alternar entre a visualização Design e a representação XML subjacente na visualização Text.
    3. Attributes: mostra atributos para o item selecionado no momento no gráfico de navegação.
    4. Clique na guia Text para ver o XML correspondente, que precisa ser semelhante ao seguinte snippet:

      <?xml version="1.0" encoding="utf-8"?>
          <navigation xmlns:android="http://schemas.android.com/apk/res/android"
                      xmlns:app="http://schemas.android.com/apk/res-auto"
                      android:id="@+id/nav_graph">
      
          </navigation>
          

      <navigation> é o elemento raiz de um gráfico de navegação. Conforme você adiciona destinos e conecta ações ao gráfico, é possível ver os elementos <destination> e <action> correspondentes aqui como elementos filhos. Se você tiver gráficos aninhados, eles aparecerão como elementos<navigation> filhos.

      Adicionar um NavHost a uma atividade

      Uma das partes principais do componente de navegação é o host de navegação. O host de navegação é um contêiner vazio em que os destinos são trocados por um usuário enquanto ele navega pelo aplicativo.

      Um host de navegação precisa derivar de NavHost. A implementação NavHost padrão do componente de navegação, NavHostFragment, gerencia a troca de destinos de fragmento.

      Adicionar um NavHostFragment via XML

      O XML de exemplo abaixo mostra um NavHostFragment como parte da atividade principal de um app.

          <?xml version="1.0" encoding="utf-8"?>
          <android.support.constraint.ConstraintLayout
              xmlns:android="http://schemas.android.com/apk/res/android"
              xmlns:app="http://schemas.android.com/apk/res-auto"
              xmlns:tools="http://schemas.android.com/tools"
              android:layout_width="match_parent"
              android:layout_height="match_parent"
              tools:context=".MainActivity">
      
              <androidx.appcompat.widget.Toolbar
                  .../>
      
              <fragment
                  android:id="@+id/nav_host_fragment"
                  android:name="androidx.navigation.fragment.NavHostFragment"
                  android:layout_width="0dp"
                  android:layout_height="0dp"
                  app:layout_constraintLeft_toLeftOf="parent"
                  app:layout_constraintRight_toRightOf="parent"
                  app:layout_constraintTop_toTopOf="parent"
                  app:layout_constraintBottom_toBottomOf="parent"
      
                  app:defaultNavHost="true"
                  app:navGraph="@navigation/nav_graph" />
      
              <com.google.android.material.bottomnavigation.BottomNavigationView
                  .../>
      
          </android.support.constraint.ConstraintLayout>
          

      Observe o seguinte:

    5. O atributo android:name contém o nome da classe da implementação de NavHost.
    6. O atributo app:navGraph associa o NavHostFragment a um gráfico de navegação. O gráfico de navegação especifica todos os destinos nesse NavHostFragment para onde os usuários podem navegar.
    7. O atributo app:defaultNavHost="true" garante que seu NavHostFragment intercepte o botão "Voltar" do sistema. Observe que apenas um NavHost pode ser o padrão. Se você tiver vários hosts no mesmo layout (layouts de dois painéis, por exemplo), especifique apenas um NavHost padrão.
    8. Você também pode usar o Layout Editor para adicionar um NavHostFragment a uma atividade fazendo o seguinte:

      1. Na lista de arquivos de projeto, clique duas vezes no arquivo XML de layout da sua atividade para abri-lo no Layout Editor.
      2. No painel Palette, escolha a categoria Containers ou, como alternativa, procure "NavHostFragment".
      3. Arraste a visualização NavHostFragment até sua atividade.
      4. Em seguida, na caixa de diálogo Navigation Graphs exibida, escolha o gráfico de navegação correspondente a ser associado a NavHostFragment e clique em OK.
      5. Adicionar destinos ao gráfico de navegação

        Você pode criar um destino a partir de um fragmento ou uma atividade existente. Você também pode usar o Navigation Editor para criar um novo destino ou criar um marcador para substituir posteriormente por um fragmento ou uma atividade.

        Neste exemplo, vamos criar um novo destino. Para adicionar um novo destino usando o Navigation Editor, faça o seguinte:

        1. No Navigation Editor, clique no ícone New Destination e, em seguida, clique em Create new destination.
        2. Na caixa de diálogo New Android Component exibida, crie seu fragmento. Para saber mais sobre fragmentos, consulte a documentação do fragmento.
        3. De volta ao Navigation Editor, observe que o Android Studio adicionou esse destino ao gráfico.

          A Figura 3 mostra um exemplo de destino e um destino de marcador.

          Figura 3. Um destino e um marcador

          Para ver outras formas de adicionar destinos ao seu gráfico de navegação, consulte Criar destinos.

          Anatomia de um destino

          Clique em um destino para selecioná-lo e observe os seguintes atributos no painel Attributes:

        4. O campo Type indica se o destino é implementado como um fragmento, uma atividade ou outra classe personalizada no código-fonte.
        5. O campo Label contém o nome do arquivo de layout XML do destino.
        6. O campo ID contém o código do destino que é usado para fazer referência ao destino no código.
        7. O menu suspenso Class mostra o nome da classe associada ao destino. Você pode clicar nessa lista suspensa para alterar a classe associada para outro tipo de destino.
        8. Clique na guia Text para exibir a visualização XML do seu gráfico de navegação. O XML contém os mesmos atributos id, name, label e layout do destino, conforme mostrado abaixo.

              <?xml version="1.0" encoding="utf-8"?>
              <navigation xmlns:app="http://schemas.android.com/apk/res-auto"
                  xmlns:tools="http://schemas.android.com/tools"
                  xmlns:android="http://schemas.android.com/apk/res/android"
                  app:startDestination="@id/blankFragment">
                  <fragment
                      android:id="@+id/blankFragment"
                      android:name="com.example.cashdog.cashdog.BlankFragment"
                      android:label="Blank"
                      tools:layout="@layout/fragment_blank" />
              </navigation>
              

          Designar uma tela como destino inicial

          O destino inicial é a primeira tela que os usuários veem ao abrir seu app, e é a última tela que os usuários veem quando saem do app. O Navigation Editor usa um ícone de casa para indicar o destino inicial.

          Depois de definir todos os seus destinos, você pode escolher um destino inicial fazendo o seguinte:

          1. Na guia Design, clique no destino para destacá-lo.

          2. Clique no botão Assign start destination . Como alternativa, você pode clicar com o botão direito no destino e clicar em Set as Start Destination.

          Conectar destinos

          Uma ação é uma conexão lógica entre destinos. As ações são representadas como setas no gráfico de navegação. As ações geralmente conectam um destino ao outro, embora você também possa criar ações globais que levam a um destino específico a partir de qualquer lugar no seu app.

          Com as ações, você representa os diferentes caminhos que os usuários podem seguir no seu app. Para navegar até os destinos, você ainda precisa criar o código para executar a navegação. Isso é abordado na seção Navegar até um destino posteriormente neste tópico.

          Você pode usar o Navigation Editor para conectar dois destinos fazendo o seguinte:

          1. Na guia Design, passe o mouse sobre o lado direito do destino a partir do qual você quer que os usuários naveguem. Um círculo aparece sobre o lado direito do destino, conforme mostrado na Figura 4.

            Figura 4. Um destino com um círculo de ação e conexão
          2. Clique e arraste o cursor sobre o destino para o qual você quer que os usuários naveguem e solte. A linha resultante entre os dois destinos representa uma ação, conforme mostrado na Figura 5.

            Figura 5. Como conectar destinos a uma ação
          3. Clique na seta para destacar a ação. Os seguintes atributos aparecem no painel Attributes:

          4. O campo Type contém "Action".
          5. O campo ID contém o ID da ação.
          6. O campo Destination contém o ID do fragmento ou da atividade de destino.
          7. Clique na guia Text para alternar para a visualização XML. Agora, um elemento de ação é adicionado ao destino de origem. A ação tem um IDe um atributo de destino que contém o ID do próximo destino, conforme mostrado no exemplo abaixo.

            <?xml version="1.0" encoding="utf-8"?>
                <navigation xmlns:app="http://schemas.android.com/apk/res-auto"
                    xmlns:tools="http://schemas.android.com/tools"
                    xmlns:android="http://schemas.android.com/apk/res/android"
                    app:startDestination="@id/blankFragment">
                    <fragment
                        android:id="@+id/blankFragment"
                        android:name="com.example.cashdog.cashdog.BlankFragment"
                        android:label="fragment_blank"
                        tools:layout="@layout/fragment_blank" >
                        <action
                            android:id="@+id/action_blankFragment_to_blankFragment2"
                            app:destination="@id/blankFragment2" />
                    </fragment>
                    <fragment
                        android:id="@+id/blankFragment2"
                        android:name="com.example.cashdog.cashdog.BlankFragment2"
                        android:label="fragment_blank_fragment2"
                        tools:layout="@layout/fragment_blank_fragment2" />
                </navigation>
                
          8. No gráfico de navegação, as ações são representadas por elementos <action>. No mínimo, uma ação contém o respectivo código e o código do destino ao qual um usuário deve ser levado.

            A navegação até um destino é feita usando um NavController, um objeto que gerencia a navegação do app dentro de um NavHost. Cada NavHost tem o próprio NavController correspondente. Você pode recuperar um NavController usando um dos seguintes métodos:

            Kotlin:

          9. Fragment.findNavController()
          10. View.findNavController()
          11. Activity.findNavController(viewId: Int)
          12. Java:

          13. NavHostFragment.findNavController(Fragment)
          14. Navigation.findNavController(Activity, @IdRes int viewId)
          15. Navigation.findNavController(View)
          16. Garantir a segurança de tipos usando Safe Args

            A maneira recomendada de navegar entredestinos é usar o plug-in Safe Args do Gradle. Esse plug-in gera classes de objetos e builders simples que permitem a navegação segura de tipos e a transmissão de argumentos entre destinos.

            Depois que o plug-in Safe Args é ativado, ele gera um código que contém classes e métodos para cada ação que você definiu. Para cada ação, o Safe Args também gera uma classe para cada destino de origem, que é o destino de origem da ação. O nome da classe gerada é uma combinação do nome da classe de destino de origem e da palavra "Directions". Por exemplo, se o destino tem o nome de SpecifyAmountFragment, a classe gerada será chamada SpecifyAmountFragmentDirections. A classe gerada contém um método estático para cada ação definida no destino de origem. Esse método usa qualquer parâmetro de ação definido como argumento e retorna um objeto NavDirections que você pode transmitir para navigate().

            Como exemplo, vamos supor que temos um gráfico de navegação com uma única ação que conecta o destino de origem, SpecifyAmountFragment, a um destino de recebimento, ConfirmationFragment.

            O Safe Args gera uma classe SpecifyAmountFragmentDirections com um único método, actionSpecifyAmountFragmentToConfirmationFragment(), que retorna um objeto NavDirections. Esse objeto NavDirections retornado pode ser transmitido diretamente para navigate(), conforme mostrado no exemplo a seguir.

            Kotlin

                override fun onClick(view: View) {
                    val action =
                        SpecifyAmountFragmentDirections
                            .actionSpecifyAmountFragmentToConfirmationFragment()
                    view.findNavController().navigate(action)
                }
                

            Java

                @Override
                public void onClick(View view) {
                    NavDirections action =
                        SpecifyAmountFragmentDirections
                            .actionSpecifyAmountFragmentToConfirmationFragment();
                    Navigation.findNavController(view).navigate(action);
                }
                

            Para ver mais informações sobre como transmitir dados entre destinos com o Safe Args, consulte Usar o Safe Args para transmitir dados com segurança de tipo.

            Mais informações

          17. Visão geral da navegação
          18. Criar destinos
          19. Navegar até um destino
          20. Atualizar componentes da IU com NavigationUI
          21. Transmitir dados entre destinos
          22. Ações globais
          23. Destinos condicionais
          24. Tipos de destino personalizados
          25. Android Jetpack: gerenciar a navegação da IU com o "Navigation Controller" (Google I/O '18) (em inglês)
          26. Migrar um projeto já existente para o componente da arquitetura de navegação
          27. Codelab de navegação
          28. Se você encontrar problemas com a navegação, envie um feedback por meio de um dos seguintes canais:

          29. Registrar um bug do Navigation Editor
          30. Registrar um bug da biblioteca de navegação
          31. Marcar um problema no StackOverflow
          32. Para saber como fornecer as informações mais úteis nos relatórios de bugs, consulte os seguintes links:

          33. Como informar bugs (plataforma Android)
          34. Informar um bug (Android Studio)