Navegação com o Compose

O componente de navegação oferece suporte a aplicativos do Jetpack Compose. É possível navegar entre elementos combináveis e, ao mesmo tempo, aproveitar a infraestrutura e os recursos do componente de navegação.

Para conferir a biblioteca de navegação Alfa mais recente criada especificamente para o Compose, consulte a documentação da Navigation 3.

Configurar

Para oferecer suporte ao Compose, use a dependência abaixo no arquivo build.gradle do módulo do app:

dependencies {
    def nav_version = "2.9.1"

    implementation "androidx.navigation:navigation-compose:$nav_version"
}

dependencies {
    val nav_version = "2.9.1"

    implementation("androidx.navigation:navigation-compose:$nav_version")
}

Primeiros passos

Ao implementar a navegação em um app, implemente um host, um gráfico e um controlador de navegação. Para mais informações, consulte a visão geral da Navegação.

Criar um NavController

Para saber como criar um NavController no Compose, consulte a seção do Compose em Criar um controlador de navegação.

Criar um NavHost

Para informações sobre como criar um NavHost no Compose, consulte a seção do Compose de Projetar o gráfico de navegação.

Navegar para um elemento combinável

Para saber como navegar até um elemento combinável, consulte Navegar até um destino na documentação de arquitetura.

Navegar com argumentos

Para informações sobre como transmitir argumentos entre destinos combináveis, consulte a seção do Compose em Projetar o gráfico de navegação.

Extrair dados complexos durante a navegação

É altamente recomendável 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:

// Pass only the user ID when navigating to a new destination as argument
navController.navigate(Profile(id = "user1234"))

Objetos complexos precisam ser armazenados na forma de dados em uma única fonte de verdade, como a camada de dados. Depois de acessar o destino após a navegação, é possível carregar as informações necessárias da única fonte de verdade usando o ID transmitido. Para recuperar os argumentos responsáveis por acessar a camada de dados no ViewModel, use o SavedStateHandle do ViewModel:

class UserViewModel(
    savedStateHandle: SavedStateHandle,
    private val userInfoRepository: UserInfoRepository
) : ViewModel() {

    private val profile = savedStateHandle.toRoute<Profile>()

    // Fetch the relevant user information from the data layer,
    // ie. userInfoRepository, based on the passed userId argument
    private val userInfo: Flow<UserInfo> = userInfoRepository.getUserInfo(profile.id)

// …

}

Essa abordagem ajuda a evitar a perda de dados durante mudanças de configuração e qualquer inconsistência quando o objeto em questão está sendo atualizado ou modificado.

Para uma explicação mais detalhada sobre por que evitar a transmissão de dados complexos como argumentos e uma lista de tipos de argumentos aceitos, consulte Transmitir dados entre destinos.

Links diretos

O Navigation Compose é compatível com links diretos que também podem ser definidos como parte da função composable(). O parâmetro deepLinks aceita uma lista de objetos NavDeepLink que podem ser criados rapidamente usando o método navDeepLink():

@Serializable data class Profile(val id: String)
val uri = "https://www.example.com"

composable<Profile>(
  deepLinks = listOf(
    navDeepLink<Profile>(basePath = "$uri/profile")
  )
) { backStackEntry ->
  ProfileScreen(id = backStackEntry.toRoute<Profile>().id)
}

Esses links diretos permitem associar um URL, uma ação ou um tipo MIME específico a um elemento combinável. Por padrão, esses links diretos não são expostos a apps externos. Para disponibilizar esses links diretos externamente, adicione os elementos <intent-filter> adequados ao arquivo manifest.xml do app. Para ativar o link direto no exemplo anterior, adicione o código abaixo ao elemento <activity> do manifesto:

<activity …>
  <intent-filter>
    ...
    <data android:scheme="https" android:host="www.example.com" />
  </intent-filter>
</activity>

A navegação automaticamente estabelece um link direto para esse elemento combinável quando o link é acionado por outro app.

Esses mesmos links diretos também podem ser usados para criar um PendingIntent com o link direto adequado de um elemento combinável:

val id = "exampleId"
val context = LocalContext.current
val deepLinkIntent = Intent(
    Intent.ACTION_VIEW,
    "https://www.example.com/profile/$id".toUri(),
    context,
    MyActivity::class.java
)

val deepLinkPendingIntent: PendingIntent? = TaskStackBuilder.create(context).run {
    addNextIntentWithParentStack(deepLinkIntent)
    getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT)
}

deepLinkPendingIntent pode ser usada da mesma forma que qualquer outra PendingIntent para abrir seu app no destino do link direto.

Navegação aninhada

Para saber como criar gráficos de navegação aninhados, consulte Gráficos aninhados.

Integração com a barra de navegação inferior

Ao definir o NavController em um nível superior na hierarquia de composição, você pode conectar o Navigation a outros componentes, como o componente de navegação inferior. Isso permite que você navegue selecionando os ícones na barra de navegação.

Para usar os componentes BottomNavigation e BottomNavigationItem, adicione a dependência androidx.compose.material ao seu app Android.

dependencies {
    implementation "androidx.compose.material:material:1.8.3"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

dependencies {
    implementation("androidx.compose.material:material:1.8.3")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Para vincular os itens em uma barra de navegação inferior às rotas no gráfico de navegação, é recomendável definir uma classe, como a TopLevelRoute mencionada aqui, que tenha uma classe de rota e um ícone.

data class TopLevelRoute<T : Any>(val name: String, val route: T, val icon: ImageVector)

Em seguida, coloque essas rotas em uma lista que possa ser usada pelo BottomNavigationItem:

val topLevelRoutes = listOf(
   TopLevelRoute("Profile", Profile, Icons.Profile),
   TopLevelRoute("Friends", Friends, Icons.Friends)
)

No seu BottomNavigation de composição, extraia a NavBackStackEntry usando a função currentBackStackEntryAsState(). Essa entrada fornece acesso ao NavDestination atual. O estado selecionado de cada BottomNavigationItem pode ser determinado comparando a rota do item com a rota do destino atual e os destinos pai dele para processar casos em que você está usando a navegação aninhada com a hierarquia NavDestination.

A rota do item também é usada para conectar a lambda onClick a uma chamada para navigate. Assim, ao tocar no item você vai navegar até ele. Usando as sinalizações saveState e restoreState, o estado e a backstack desse item são salvos e restaurados corretamente à medida que você alterna entre os itens da navegação inferior.

val navController = rememberNavController()
Scaffold(
  bottomBar = {
    BottomNavigation {
      val navBackStackEntry by navController.currentBackStackEntryAsState()
      val currentDestination = navBackStackEntry?.destination
      topLevelRoutes.forEach { topLevelRoute ->
        BottomNavigationItem(
          icon = { Icon(topLevelRoute.icon, contentDescription = topLevelRoute.name) },
          label = { Text(topLevelRoute.name) },
          selected = currentDestination?.hierarchy?.any { it.hasRoute(topLevelRoute.route::class) } == true,
          onClick = {
            navController.navigate(topLevelRoute.route) {
              // Pop up to the start destination of the graph to
              // avoid building up a large stack of destinations
              // on the back stack as users select items
              popUpTo(navController.graph.findStartDestination().id) {
                saveState = true
              }
              // Avoid multiple copies of the same destination when
              // reselecting the same item
              launchSingleTop = true
              // Restore state when reselecting a previously selected item
              restoreState = true
            }
          }
        )
      }
    }
  }
) { innerPadding ->
  NavHost(navController, startDestination = Profile, Modifier.padding(innerPadding)) {
    composable<Profile> { ProfileScreen(...) }
    composable<Friends> { FriendsScreen(...) }
  }
}

Aqui você aproveita o método NavController.currentBackStackEntryAsState() para elevar o estado de navController para fora da função NavHost e compartilhá-lo com o componente BottomNavigation. Isso significa que BottomNavigation automaticamente tem o estado mais atualizado.

Interoperabilidade

Se quiser usar o componente de navegação com o Compose, você tem duas opções:

• Definir um gráfico de navegação com o componente de navegação para fragmentos.
• Definir um gráfico de navegação com um NavHost no Compose usando destinos do Compose. Isso só é possível se todas as telas no gráfico de navegação forem combináveis.

Portanto, a recomendação para apps mistos do Compose e de visualizações é usar o componente de navegação baseado em fragmentos. Os fragmentos contêm telas com base em visualizações, telas do Compose e telas que usam o Compose e as visualizações. Quando o conteúdo de cada fragmento está no Compose, a próxima etapa é unir todas essas telas ao Navigation Compose e remover todos os fragmentos.

Navegar do Compose usando o componente de navegação para fragmentos

Para alterar os destinos no código do Compose, você expõe eventos que podem ser transmitidos e acionados por qualquer função combinável na hierarquia:

@Composable
fun MyScreen(onNavigate: (Int) -> Unit) {
    Button(onClick = { onNavigate(R.id.nav_profile) } { /* ... */ }
}

No fragmento, você procura a NavController e navega até o destino para criar uma ponte entre o Compose e o componente de navegação baseado em fragmento:

override fun onCreateView( /* ... */ ) {
    setContent {
        MyScreen(onNavigate = { dest -> findNavController().navigate(dest) })
    }
}

Como alternativa, você pode transmitir o NavController pela hierarquia do Compose. No entanto, a exposição de funções simples é muito mais reutilizável e testável.

Teste

Desassocie o código de navegação dos destinos combináveis para permitir o teste de cada elemento combinável isoladamente, separado do elemento combinável NavHost.

Isso significa que não é recomendado transmitir navController diretamente para qualquer elemento combinável. Em vez disso, transmita callbacks de navegação como parâmetros. Isso permite que todos os elementos combináveis sejam testáveis individualmente, já que não exigem uma instância de navController em testes.

O nível de indireção fornecido pela lambda composable é o que permite separar o código de navegação do elemento combinável. Isso funciona em duas direções:

• Transmitir para a função de composição apenas argumentos analisados
• Transmitir lambdas que vão ser acionadas pelo elemento combinável para navegar, em vez da NavController em si.

Por exemplo, um elemento combinável ProfileScreen que usa um userId como entrada e permite que os usuários naveguem até a página de perfil de um amigo pode ter a seguinte assinatura:

@Composable
fun ProfileScreen(
    userId: String,
    navigateToFriendProfile: (friendUserId: String) -> Unit
) {
 …
}

Dessa forma, o elemento combinável ProfileScreen funciona de maneira independente da navegação, permitindo que ele seja testado em separado. A lambda composable encapsula a lógica mínima necessária para preencher a lacuna entre as APIs de navegação e o elemento combinável.

@Serializable data class Profile(id: String)

composable<Profile> { backStackEntry ->
    val profile = backStackEntry.toRoute<Profile>()
    ProfileScreen(userId = profile.id) { friendUserId ->
        navController.navigate(route = Profile(id = friendUserId))
    }
}

É recomendável programar testes que atendam aos requisitos de navegação do seu app testando o NavHost, as ações de navegação transmitidas para os elementos e as telas individuais de composição.

Como testar o NavHost

Para começar a testar o NavHost , adicione a seguinte dependência de teste de navegação:

dependencies {
// ...
  androidTestImplementation "androidx.navigation:navigation-testing:$navigationVersion"
  // ...
}

Una o NavHost do app a um elemento combinável que aceite um NavHostController como parâmetro.

@Composable
fun AppNavHost(navController: NavHostController){
  NavHost(navController = navController){ ... }
}

Agora é possível testar AppNavHost e toda a lógica de navegação definida em NavHost transmitindo uma instância do artefato de teste de navegação TestNavHostController. Um teste de interface que verifica o destino inicial do app e NavHost teria esta aparência:

class NavigationTest {

    @get:Rule
    val composeTestRule = createComposeRule()
    lateinit var navController: TestNavHostController

    @Before
    fun setupAppNavHost() {
        composeTestRule.setContent {
            navController = TestNavHostController(LocalContext.current)
            navController.navigatorProvider.addNavigator(ComposeNavigator())
            AppNavHost(navController = navController)
        }
    }

    // Unit test
    @Test
    fun appNavHost_verifyStartDestination() {
        composeTestRule
            .onNodeWithContentDescription("Start Screen")
            .assertIsDisplayed()
    }
}

Como testar ações de navegação

Você pode testar a implementação da navegação de várias maneiras. Para isso, clique nos elementos da interface e confira o destino mostrado ou compare a rota esperada com a rota exibida.

Como o objetivo é testar a implementação concreta do app, recomendamos clicar na IU. Para aprender a testar isso de forma isolada com funções combináveis individuais, confira o codelab Como testar no Jetpack Compose.

Também é possível usar o navController para conferir suas declarações, comparando a rota atual com a esperada, usando a currentBackStackEntry de navController:

@Test
fun appNavHost_clickAllProfiles_navigateToProfiles() {
    composeTestRule.onNodeWithContentDescription("All Profiles")
        .performScrollTo()
        .performClick()

    assertTrue(navController.currentBackStackEntry?.destination?.hasRoute<Profile>() ?: false)
}

Para mais orientações sobre os conceitos básicos de testes no Compose, consulte Como testar o layout do Compose e o codelab Como testar no Jetpack Compose. Para saber mais sobre testes avançados do código de navegação, consulte o guia Testar a navegação.

Saiba mais

Para saber mais sobre o Jetpack Navigation, consulte Como usar o componente de navegação ou faça o codelab de navegação do Jetpack Compose.

Para aprender a projetar a navegação do app para que ele se adapte a diferentes tamanhos, orientações e formatos de tela, consulte Navegação para IUs responsivas.

Para saber mais sobre a implementação mais avançada da navegação do Compose em um app modularizado, incluindo conceitos como gráficos aninhados e integração da barra de navegação inferior, consulte o app Now in Android no GitHub.

Amostras