Migrar a navegação do Jetpack para o Navigation Compose

A API Navigation Compose permite navegar entre elementos combináveis em um app do Compose, aproveitando o componente, a infraestrutura e os recursos da navegação do Jetpack.

Esta página descreve como migrar de uma navegação do Jetpack baseada em fragmentos para a navegação do Compose como parte da migração maior da interface baseada em visualizações para o Jetpack Compose.

Pré-requisitos de migração

Você pode migrar para a navegação do Compose quando conseguir substituir todos os fragmentos por elementos combináveis de tela correspondentes. Os elementos combináveis de tela podem conter uma combinação de conteúdo do Compose e de visualização, mas todos os destinos de navegação precisam ser combináveis para ativar a migração da navegação do Compose. Até então, continue usando o componente de navegação baseado em fragmentos no código de visualização e do Compose. Consulte a documentação de interoperabilidade de navegação para mais informações.

Etapas da migração

Se você estiver seguindo nossa estratégia de migração recomendada ou adotando outra abordagem, chegará a um ponto em que todos os destinos de navegação serão elementos combináveis de tela, com fragmentos atuando apenas como contêineres combináveis. Nessa fase, você pode migrar para a navegação do Compose.

Se o app já estiver seguindo um padrão de design UDF e nosso guia de arquitetura, a migração para o Jetpack Compose e a navegação do Compose não exigirá grandes refatorações de outras camadas do app, além da camada de interface.

Para migrar para a navegação do Compose, siga estas etapas:

Adicione a dependência de navegação do Compose ao app.

Crie um elemento combinável App-level e adicione-o à Activity como ponto de entrada do Compose, substituindo a configuração do layout de visualização:

class SampleActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // setContentView<ActivitySampleBinding>(this, R.layout.activity_sample)
        setContent {
            SampleApp(/* ... */)
        }
    }
}MigrationCommonScenariosSnippets.kt

Crie tipos para cada destino de navegação. Use um data object para destinos que não exigem dados e data class ou class para destinos que exigem dados.

@Serializable data object First
@Serializable data class Second(val id: String)
@Serializable data object Third
MigrationCommonScenariosSnippets.kt

Configure o NavController em um local em que todos os elementos combináveis que precisam referenciá-lo tenham acesso a ele. Geralmente, isso ocorre dentro do elemento combinável App . Essa abordagem segue os princípios da elevação de estado e permite que você use o NavController como a fonte da verdade para navegar entre as telas combináveis e manter a backstack:
```
@Composable
fun SampleApp() {
    val navController = rememberNavController()
    // ...
}MigrationCommonScenariosSnippets.kt
```

Crie o NavHost do app dentro do elemento combinável App e transmita o navController:

@Composable
fun SampleApp() {
    val navController = rememberNavController()

    SampleNavHost(navController = navController)
}

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        // ...
    }
}MigrationCommonScenariosSnippets.kt

Adicione os destinos composable para criar o gráfico de navegação. Se cada tela tiver sido migrada anteriormente para o Compose, essa etapa consistirá apenas em extrair esses elementos combináveis de tela dos fragmentos para os destinos composable:

class FirstFragment : Fragment() {

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        return ComposeView(requireContext()).apply {
            setContent {
                // FirstScreen(...) EXTRACT FROM HERE
            }
        }
    }
}

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        composable<First> {
            FirstScreen(/* ... */) // EXTRACT TO HERE
        }
        composable<Second> {
            SecondScreen(/* ... */)
        }
        // ...
    }
}MigrationCommonScenariosSnippets.kt

Se você seguiu as orientações sobre como arquitetar a interface do Compose, especificamente como os ViewModels e os eventos de navegação precisam ser transmitidos para elementos combináveis, a próxima etapa é mudar a forma como você fornece o ViewModel para cada elemento combinável de tela. Muitas vezes, é possível usar a injeção do Hilt e o ponto de integração com o Compose e a navegação usando hiltViewModel:
```
@Composable
fun FirstScreen(
    // viewModel: FirstViewModel = viewModel(),
    viewModel: FirstViewModel = hiltViewModel(),
    onButtonClick: () -> Unit = {},
) {
    // ...
}MigrationCommonScenariosSnippets.kt
```

Substitua todas as chamadas de navegação findNavController() pelas navController e transmita-as como eventos de navegação para cada tela combinável, em vez de transmitir o navController inteiro. Essa abordagem segue as práticas recomendadas de exposição de eventos de funções combináveis para chamadores e mantém o navController como a única fonte da verdade.

Os dados podem ser transmitidos para um destino criando uma instância da classe de rota definida para esse destino. Eles podem ser obtidos diretamente da entrada da backstack no destino ou de um ViewModel usando SavedStateHandle.toRoute().

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        composable<First> {
            FirstScreen(
                onButtonClick = {
                    // findNavController().navigate(firstScreenToSecondScreenAction)
                    navController.navigate(Second(id = "ABC"))
                }
            )
        }
        composable<Second> { backStackEntry ->
            val secondRoute = backStackEntry.toRoute<Second>()
            SecondScreen(
                id = secondRoute.id,
                onIconClick = {
                    // findNavController().navigate(secondScreenToThirdScreenAction)
                    navController.navigate(Third)
                }
            )
        }
        // ...
    }
}MigrationCommonScenariosSnippets.kt

Remova todos os Fragmentos, layouts XML relevantes, navegação desnecessária e outros recursos, além de dependências obsoletas de Fragmentos e da navegação do Jetpack.

Você pode encontrar as mesmas etapas com mais detalhes relacionados à navegação do Compose na documentação de configuração.

Casos de uso comuns

Não importa qual componente de navegação você esteja usando, os mesmos princípios de navegação se aplicam.

Os casos de uso comuns ao migrar incluem o seguinte:

Para mais informações sobre esses casos de uso, consulte Como navegar com o Compose.

Recuperar dados complexos durante a navegação

Recomendamos não transmitir objetos de dados complexos ao navegar. Em vez disso, transmita as informações mínimas necessárias, como um identificador exclusivo ou outra forma de ID, como argumentos ao executar ações de navegação. Você precisa armazenar objetos complexos como dados em uma única fonte de verdade, como a camada de dados. Para mais informações, consulte Como recuperar dados complexos durante a navegação.

Se os fragmentos estiverem transmitindo objetos complexos como argumentos, considere refatorar o código primeiro de uma forma que permita armazenar e buscar esses objetos na camada de dados. Consulte o repositório Now in Android para exemplos.

Limitações

Esta seção descreve as limitações atuais da navegação do Compose.

Migração incremental para a navegação do Compose

No momento, não é possível usar a navegação do Compose enquanto ainda usa fragmentos como destinos no código. Para começar a usar a navegação do Compose, todos os destinos precisam ser combináveis. Você pode acompanhar essa solicitação de recurso no Issue Tracker.

Animações de transição

A partir da navegação 2.7.0-alpha01, o suporte para definir transições personalizadas, anteriormente do AnimatedNavHost, agora é oferecido diretamente no NavHost. Leia as notas da versão para mais informações.

Saiba mais

Para mais informações sobre a migração para a navegação do Compose, consulte os seguintes recursos:

Codelab de navegação do Compose: aprenda os conceitos básicos da navegação do Compose com um codelab prático.
Repositório Now in Android: um app Android totalmente funcional criado com o Kotlin e o Jetpack Compose, que segue as práticas recomendadas de design e desenvolvimento do Android e inclui a navegação do Compose.
Migração do Sunflower para o Jetpack Compose: uma postagem no blog que documenta a jornada de migração do app de exemplo Sunflower de visualizações para o Compose, que também inclui a migração para a navegação do Compose.
Jetnews para cada tela: uma postagem no blog que documenta a refatoração e a migração do exemplo do Jetnews para oferecer suporte a todas as telas com o Jetpack Compose e a navegação do Compose.