O Jetpack Navigation 3 está estável

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

O Navigation 3 é uma nova biblioteca de navegação criada do zero para adotar o estado do Jetpack Compose. Ele oferece controle total sobre a backstack, ajuda a manter o estado de navegação e permite criar layouts adaptáveis com facilidade (como lista-detalhe). Há até uma versão multiplataforma da JetBrains (link em inglês).

Por que uma nova biblioteca?

A biblioteca original Jetpack Navigation (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 do Nav3 que mostra suas telas) apenas observa uma lista de chaves (cada uma representando uma tela) apoiada pelo 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, já que ela tem um estado interno próprio. Com a Nav3, você fornece seu próprio estado, o que dá controle total.

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

Com essa abordagem, você pode: 

• Personalize as animações da 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
• Substitua facilmente os componentes do 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. 

Migração da Navigation 2

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

1. Adicione as dependências do Navigation 3.
2. Atualize suas rotas de navegação para implementar o NavKey. Suas rotas não precisam implementar essa interface para usar o Nav3, mas, se o fizerem, você poderá aproveitar a função rememberNavBackStack do Nav3 para criar uma pilha de retorno persistente.
3. Crie classes para armazenar e modificar seu estado de navegação. É aqui que as pilhas de retorno são mantidas.
4. Substitua NavController por estas classes.
5. Mova seus destinos do NavGraph do NavHost para um entryProvider.
6. Substitua NavHost por NavDisplay.

Testar a migração de agentes de IA

Você pode usar um agente de IA para ler o guia de migração e executar as etapas no seu projeto. Para testar isso com o Modo Agente do Gemini no Android Studio:

• Salve esta versão em Markdown do guia no seu projeto.
• Cole este comando no agente (mas não pressione "Enter"): "Migre este projeto para o Navigation 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. 

Queremos saber como você ou seu agente se saíram. Envie seu feedback aqui.

Receitas de navegação saborosas para situações comuns

Para casos de uso comuns, mas sutis, temos um repositório de receitas. Isso mostra como combinar as APIs 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 sutis dela para a biblioteca principal do Nav3 ou bibliotecas complementares. 

No momento, há 19 receitas, incluindo: 

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

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

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

Resumo

Para começar a usar a Nav3, confira a documentação e as receitas. Além disso, fique de olho em 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 livres 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 você encontrar algum problema, informe aqui.