A navegação do Jetpack 3 está estável

A versão 1.0 da navegação do Jetpack 3 está estável 🎉. Use-a nos seus apps de produção hoje mesmo. A JetBrains já está usando no app KotlinConf.

A navegação 3 é uma nova biblioteca de navegação criada do zero para adotar o estado do Jetpack Compose state. Ela oferece controle total sobre a backstack, ajuda a manter o estado de navegação e permite criar layouts adaptáveis com facilidade (como detalhes e listas). Há até uma versão multiplataforma da JetBrains.

Por que uma nova biblioteca?

A biblioteca original de navegação do Jetpack (agora Nav2) foi projetada há sete anos e, embora atenda bem aos objetivos originais e tenha sido aprimorada de forma iterativa, a maneira como os apps são criados mudou fundamentalmente. 

A programação reativa com uma interface declarativa agora é a norma. A Nav3 adota essa abordagem. Por exemplo, o NavDisplay (o componente de interface da Nav3 que mostra as telas) simplesmente observa uma lista de chaves (cada uma representando uma tela) com o estado do Compose e atualiza a interface quando essa lista muda.

A Nav2 também pode dificultar a criação de uma única fonte de verdade para o estado de navegação, porque tem o próprio estado interno. Com a Nav3, você fornece seu próprio estado, o que oferece controle total.

Por fim, você pediu mais flexibilidade e personalização. Em vez de ter uma única API monolítica, a Nav3 oferece APIs menores e desacopladas (ou "blocos de construção") que podem ser combinadas para criar funcionalidades complexas. A própria Nav3 usa esses blocos de construção para fornecer padrões sensíveis para casos de uso de navegação bem definidos. 

Essa abordagem permite: 

• Personalizar animações de tela em um nível global e individual
• Mostrar vários painéis ao mesmo tempo e criar layouts flexíveis usando a API Scenes
• Substituir facilmente os componentes da Nav3 pelas suas próprias implementações se quiser um comportamento personalizado

Leia mais sobre o design e os recursos no blog de lançamento. 

Como migrar da navegação 2

Se você já estiver usando a Nav2, especificamente a navegação do Compose, considere migrar para a Nav3. Para ajudar, há um guia de migração. As principais etapas são: 

1. Adicione as dependências da navegação 3.
2. Atualize as rotas de navegação para implementar a NavKey. As rotas não precisam implementar essa interface para usar a Nav3, mas, se fizerem isso, você poderá aproveitar a função rememberNavBackStack da Nav3 para criar uma backstack persistente.
3. Crie classes para manter e modificar o estado de navegação. É aqui que as backstacks são mantidas.
4. Substitua o NavController por essas classes.
5. Mova os destinos do NavGraph do NavHost para um entryProvider.
6. Substitua o NavHost pelo NavDisplay.

Como fazer testes com a migração de agentes de IA

Talvez você queira testar o uso de um agente de IA para ler o guia de migração e executar as etapas no seu projeto. Para testar isso com o Gemini no modo de agente do Android Studio:

• Salve essa versão em Markdown do guia no seu projeto.
• Cole esse comando no agente (mas não pressione Enter): "Migre este projeto para a navegação 3 usando ".
• Digite @migration-guide.md. Isso vai fornecer o guia como contexto para o agente.

Como sempre, revise com atenção as mudanças feitas pelo agente de IA. Ele pode cometer erros.

Gostaríamos de saber como você ou seu agente se saiu. Por favor, envie seu feedback aqui.

Receitas de navegação úteis para cenários comuns

Para casos de uso comuns, mas diferenciados, temos um repositório de receitas. Ele mostra como combinar as APIs da Nav3 de uma maneira específica, permitindo que você escolha ou modifique a receita de acordo com suas necessidades. Se uma receita se tornar popular, vamos considerar "promover" as partes não diferenciadas dela para a biblioteca principal da Nav3 ou bibliotecas de complementos. 

Atualmente, há 19 receitas, incluindo para: 

• Várias backstacks
• Modularização e injeção de dependência
• Como transmitir argumentos de navegação para ViewModels (incluindo o uso do Koin)
• Como retornar resultados de telas por eventos e por estado compartilhado

No momento, estamos trabalhando em uma receita de links diretos, além de uma integração do Koin, e temos muitas outras planejadas. Um engenheiro da JetBrains também publicou uma versão multiplataforma do Compose das receitas.

Se você tiver um caso de uso comum para o qual gostaria de ver uma receita, por favor, registre uma solicitação de receita. 

Resumo

Para começar a usar a Nav3, consulte os documentos e as receitas. Além disso, fique atento a uma semana inteira de conteúdo técnico, incluindo: 

• Um vídeo detalhado sobre a API que aborda modularização, animações e layouts adaptáveis.
• Uma sessão de perguntas e respostas ao vivo com os engenheiros que criaram a Nav3.

A semana de destaque da Nav3 começa em 1º de dezembro de 2025. 

Como sempre, se encontrar algum problema, registre-o aqui.