Destinos de caixa de diálogo

Na navegação do Android, o termo destino da 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, sobrepostas a elementos e conteúdo da IU do app.

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

Combinável da 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:

@Composable
fun SettingsDialog(){
    Text("Settings")
    // ...
}

@Composable
fun MyApp() {
    val navController = rememberNavController()
    NavHost(navController, startDestination = "home") {
        composable("home") { Home(onNavigateToHome = { navController.navigate("home") }) }
        dialog("settings") { SettingsDialog(onNavigateToSettingsDialog = { navController.navigate("settings") }) }
    }
}
  1. O destino inicial é o elemento combinável Home. Como ele usa composable(), é um destino hospedado.
  2. O outro destino é o elemento combinável SettingsDialog. Como a função dialog() o adiciona ao gráfico, ele é um destino de caixa de diálogo. Quando o usuário navega de Home para SettingsDialog, o último aparece sobre Home.
  3. Embora o SettingsDialog não inclua um elemento combinável Dialog, por ele ser um destino de caixa de diálogo, o NavHost o exibe em um Dialog.

Os destinos de caixa de diálogo aparecem sobre o destino anterior no NavHost. Use-as quando a caixa de diálogo representar uma tela separada no app que precisa do próprio ciclo de vida e estado salvo, independente 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 uma AlertDialog ou um elemento combinável relacionado.

DSL do Kotlin

Se você estiver trabalhando com fragmentos e usando a DSL de Kotlin para criar seu gráfico, a adição de um destino de caixa de diálogo é 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:

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

    // Define the "settings" destination as a dialog using DialogFragment.
    dialog<SettingsDialogFragment>("settings") {
        label = "Settings Dialog"
    }
}

XML

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

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