對話方塊目的地

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

因為對話方塊目的地會顯示在填滿 導覽主機時，請考量對話方塊和對話方塊的方式 目的地會與 NavController 的返回堆疊互動。

對話方塊可組合函式

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

請參考以下範例：

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

對話方塊目的地會顯示在 NavHost 中的前一個目的地上方。使用 這些對話方塊代表應用程式中需要專屬畫面的獨立畫面 生命週期和已儲存狀態，與 導覽圖如果希望透過對話方塊提供較簡單的提示 (例如確認)，建議您使用 AlertDialog 或相關可組合函式。

Kotlin DSL

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

您也可以參考下列程式碼片段，瞭解如何使用 dialog() 函式新增使用片段的對話方塊目的地：

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

如果已有 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>