對話方塊目的地

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