對話方塊目的地

在 Android 導覽中，「對話方塊目的地」一詞是指應用程式導覽圖中的目的地，這些目的地會呈現對話方塊視窗，疊加應用程式 UI 元素和內容。

由於對話方塊目的地會顯示在填入導覽主機的「代管目的地」上，因此對話方塊目的地與 NavController 返回堆疊的互動方式有一些重要注意事項。

對話方塊可組合項

如要在 Compose 中建立對話方塊目的地，請使用 dialog() 函式，在 NavHost 中新增目的地。該函式的行為與 composable() 大致相同，只會建立對話方塊目的地，而非代管目的地。

請參考以下範例：

@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. 起始目的地是 Home 可組合項。它使用 composable()，因此為代管目的地。
  2. 另一個目的地是 SettingsDialog 可組合項。由於 dialog() 函式會將該函式新增至圖表，因此這是對話方塊目的地。當使用者從 Home 導覽至 SettingsDialog 時，後者會顯示在 Home 上。
  3. 雖然 SettingsDialog 本身並未包含 Dialog 可組合項，但因為這是對話方塊目的地，NavHost 會在 Dialog 中顯示該可組合項。

對話方塊目的地會顯示在 NavHost 中的上一個目的地上。當對話方塊代表應用程式中的另一個畫面時，這些畫面需要專屬的生命週期和已儲存狀態，與導覽圖中的任何其他目的地無關。如果您希望對話方塊顯示較不複雜的提示 (例如確認)，建議您使用 AlertDialog 或相關的可組合項。

Kotlin DSL

如果您是使用片段，且使用 Kotlin DSL 建立圖表，新增對話方塊目的地與使用 Compose 時非常類似。

請考慮下列程式碼片段中如何同時使用 dialog() 函式，新增使用片段的對話方塊目的地：

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

如果您有現有的 DialogFragment，請使用 <dialog> 元素將對話方塊新增至導覽圖表，如以下範例所示：

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