Destinos de caixa de diálogo

Na navegação do Android, o termo destino de caixa de diálogo se refere a destinos dentro do gráfico de navegação do app, que assumem a forma de janelas de caixas de diálogo, sobrepondo o conteúdo e os elementos da interface do app.

Como os destinos das caixas de diálogo aparecem sobre destinos hospedados que preenchem o host de navegação, há algumas considerações importantes sobre como a caixa de os destinos interagem com a backstack do NavController.

Elemento combinável de caixa de diálogo

Para criar um destino de caixa de diálogo no Compose, adicione um destino ao NavHost usando a função dialog(). A função se comporta essencialmente da mesma forma que composable, mas cria um destino de caixa de diálogo em vez de um destino hospedado.

Veja o exemplo a seguir:

@Serializable
object Home
@Serializable
object Settings
@Composable
fun HomeScreen(onNavigateToSettings: () -> Unit){
    Column {
        Text("Home")
        Button(onClick = onNavigateToSettings){
            Text("Open settings")
        }
    }
}

// This screen will be displayed as a dialog
@Composable
fun SettingsScreen(){
    Text("Settings")
    // ...
}

@Composable
fun MyApp() {
    val navController = rememberNavController()
    NavHost(navController, startDestination = Home) {
        composable<Home> { HomeScreen(onNavigateToSettings = { navController.navigate(route = Settings) }) }
        dialog<Settings> { SettingsScreen() }
    }
}

1. O destino inicial usa a rota Home. Devido ao composable() o adiciona ao gráfico, é um destino hospedado.
2. O outro destino usa a rota Settings.
   • Da mesma forma, como dialog() o adiciona ao gráfico, é uma caixa de diálogo. destino.
   • Quando o usuário navega de HomeScreen para SettingsScreen, o o último aparece sobre HomeScreen.
3. Embora SettingsScreen não inclua um elemento combinável Dialog, como ele é um destino de caixa de diálogo, o NavHost o mostra em um Dialog.

Os destinos de caixa de diálogo aparecem sobre o destino anterior no NavHost. Usar quando a caixa de diálogo representa uma tela separada no app que precisa do próprio e o estado salvo, independentemente de qualquer outro destino no gráfico de navegação. Caso queira uma caixa de diálogo para um comando menos complexo, como uma confirmação, você pode usar um AlertDialog ou um elemento combinável relacionado.

DSL do Kotlin

Se você estiver trabalhando com fragmentos e estiver usando a DSL do Kotlin para criar seu gráfico, a adição de um destino de caixa de diálogo será muito semelhante ao uso do Compose.

Considere como o snippet abaixo também usa a função dialog() para adicionar um destino de caixa de diálogo que usa um fragmento:

// Define destinations with serializable classes or objects
@Serializable
object Home
@Serializable
object Settings

// Add the graph to the NavController with `createGraph()`.
navController.graph = navController.createGraph(
    startDestination = Home
) {
    // Associate the home route with the HomeFragment.
    fragment<HomeFragment, Home> {
        label = "Home"
    }

    // Define the settings destination as a dialog using DialogFragment.
    dialog<SettingsFragment, Settings> {
        label = "Settings"
    }
}

XML

Se você já tiver um DialogFragment, use o elemento <dialog> para adicionar a caixa de diálogo ao seu gráfico de navegação, conforme mostrado no exemplo a seguir:

<?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">

...

<dialog
    android:id="@+id/my_dialog_fragment"
    android:name="androidx.navigation.myapp.MyDialogFragment">
    <argument android:name="myarg" android:defaultValue="@null" />
        <action
            android:id="@+id/myaction"
            app:destination="@+id/another_destination"/>
</dialog>

...

</navigation>