此页面由 Cloud Translation API 翻译。

设计导航图
使用集合让一切井井有条根据您的偏好保存内容并对其进行分类。

Navigation 组件使用导航图管理应用导航。导航图是一种数据结构，包含应用内的每个目的地以及这些目的地之间的连接。

目的地类型

有三种常规类型的目的地：托管、对话框和 activity。下表概述了这三种目的地类型及其用途。

类型	说明	用例
托管	填充整个导航宿主。也就是说，托管目的地的大小与导航宿主的大小相同，之前的目的地不会显示。	主界面和详情界面。
对话框	显示叠加界面组件。此界面与导航宿主的位置或大小无关。之前的目的地会显示在该目的地下方。	提醒、选择、表单。
activity	表示应用中的独特界面或功能。	充当导航图的退出点，启动与 Navigation 组件分开管理的新 Android activity。在 Modern Android Development 中，应用由 1 个 activity 组成。因此，当与第三方 activity 互动或作为迁移过程的一部分时，最适合使用 activity 目的地。

类型

说明

用例

托管

填充整个导航宿主。也就是说，托管目的地的大小与导航宿主的大小相同，之前的目的地不会显示。

主界面和详情界面。

对话框

显示叠加界面组件。此界面与导航宿主的位置或大小无关。之前的目的地会显示在该目的地下方。

提醒、选择、表单。

activity

表示应用中的独特界面或功能。

充当导航图的退出点，启动与 Navigation 组件分开管理的新 Android activity。

在 Modern Android Development 中，应用由 1 个 activity 组成。因此，当与第三方 activity 互动或作为迁移过程的一部分时，最适合使用 activity 目的地。

本文档包含托管目的地的示例，这些目的地是最常用和最基本的目的地。如需了解其他目的地，请参阅以下指南：

框架

虽然相同的常规工作流适用于所有情况，但导航宿主和导航图的创建方式取决于您使用的界面框架。

Compose：使用 NavHost 可组合项。使用 Kotlin DSL 为其添加 NavGraph。您可以通过以下两种方式创建图表：
- 作为 NavHost 的一部分：在添加 NavHost 的过程中直接构建导航图。
- 以编程方式：使用 NavController.createGraph() 方法创建 NavGraph 并将其直接传递给 NavHost。
fragment：将 fragment 与视图界面框架搭配使用时，请使用 NavHostFragment 作为宿主。您可以通过多种方式创建导航图：
- 以编程方式：使用 Kotlin DSL 创建 NavGraph 并将其直接应用于 NavHostFragment。
  - 与 Kotlin DSL 搭配用于 fragment 和 Compose 的 createGraph() 函数是相同的。
- XML：直接使用 XML 编写导航宿主和图表。
- Android Studio 编辑器：使用 Android Studio 中的 GUI 编辑器创建图表并将其调整为 XML 资源文件。

Compose

在 Compose 中，使用可序列化对象或类定义路线。路线用于描述如何前往目的地，并包含目的地所需的所有信息。

使用 @Serializable 注解可自动为路线类型创建必要的序列化和反序列化方法。此注解由 Kotlin 序列化插件提供。按照这些说明添加此插件。

定义路线后，使用 NavHost 可组合项创建导航图。请参考以下示例：

@Serializable
object Profile
@Serializable
object FriendsList

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile) {
    composable<Profile> { ProfileScreen( /* ... */ ) }
    composable<FriendsList> { FriendsListScreen( /* ... */ ) }
    // Add more destinations similarly.
}

可序列化对象代表这两条路线（Profile 和 FriendsList）。
调用 NavHost 可组合项会传递 NavController 和起始目的地的路线。
传递给 NavHost 的 lambda 最终会调用 NavController.createGraph() 并返回 NavGraph。
每条路线都作为类型实参提供给 NavGraphBuilder.composable<T>()，后者会将目的地添加到生成的 NavGraph 中。
传递给 composable 的 lambda 是 NavHost 为该目的地显示的内容。

了解 lambda

为便于更好地了解用来创建 NavGraph 的 lambda，不妨这样假想一下：若要创建上面代码段中的相同图表，您可以另行使用 NavController.createGraph() 创建 NavGraph 并将其直接传递给 NavHost：

val navGraph by remember(navController) {
  navController.createGraph(startDestination = Profile)) {
    composable<Profile> { ProfileScreen( /* ... */ ) }
    composable<FriendsList> { FriendsListScreen( /* ... */ ) }
  }
}
NavHost(navController, navGraph)

传递参数

如果您需要将数据传递给目的地，请使用具有参数的类定义路线。例如，Profile 路线是具有 name 参数的数据类。

@Serializable
data class Profile(val name: String)

每当您需要将参数传递给该目的地时，都需要创建路线类的实例，并将参数传递给类构造函数。

对于可选参数，请创建具有默认值的可为 null 的字段。

@Serializable
data class Profile(val nickname: String? = null)

获取路线实例

您可以使用 NavBackStackEntry.toRoute() 或 SavedStateHandle.toRoute() 获取路线实例。使用 composable() 创建目的地时，NavBackStackEntry 可用作参数。

@Serializable
data class Profile(val name: String)

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile(name="John Smith")) {
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(name = profile.name) }
}

请注意该代码段中的以下内容：

Profile 路线指定导航图中的起始目的地，其中 "John Smith" 是 name 的参数。
目的地本身就是 composable<Profile>{} 块。
ProfileScreen 可组合项会为自己的 name 实参采用 profile.name 的值。
因此，值 "John Smith" 会传递给 ProfileScreen。

最小示例

下面是将 NavController 和 NavHost 结合使用的完整示例：

@Serializable
data class Profile(val name: String)

@Serializable
object FriendsList

// Define the ProfileScreen composable.
@Composable
fun ProfileScreen(
    profile: Profile
    onNavigateToFriendsList: () -> Unit,
  ) {
  Text("Profile for ${profile.name}")
  Button(onClick = { onNavigateToFriendsList() }) {
    Text("Go to Friends List")
  }
}

// Define the FriendsListScreen composable.
@Composable
fun FriendsListScreen(onNavigateToProfile: () -> Unit) {
  Text("Friends List")
  Button(onClick = { onNavigateToProfile() }) {
    Text("Go to Profile")
  }
}

// Define the MyApp composable, including the `NavController` and `NavHost`.
@Composable
fun MyApp() {
  val navController = rememberNavController()
  NavHost(navController, startDestination = Profile(name = "John Smith")) {
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(
            profile = profile,
            onNavigateToFriendsList = {
                navController.navigate(route = FriendsList)
            }
        )
    }
    composable<FriendsList> {
      FriendsListScreen(
        onNavigateToProfile = {
          navController.navigate(
            route = Profile(name = "Aisha Devi")
          )
        }
      )
    }
  }
}

如代码段所示，向 NavHost 公开事件，而不是将 NavController 传递给可组合项。也就是说，可组合项应具有一个 () -> Unit 类型的参数，NavHost 可为该参数传递一个会调用 NavController.navigate() 的 lambda。

Fragment

如前几部分所述，在使用 fragment 时，您可以选择使用 Kotlin DSL、XML 或 Android Studio 编辑器以编程方式创建导航图。

以下部分详细介绍了这些不同的方法。

以程序化方式

Kotlin DSL 提供了一种以编程方式创建包含 fragment 的导航图的方法。在许多方面，这比使用 XML 资源文件更简洁且更时尚。

请考虑以下示例，它实现了双屏导航图。

首先，您需要创建 NavHostFragment，它不得包含 app:navGraph 元素：

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</FrameLayout>

接下来，将 NavHostFragment 的 id 传递给 NavController.findNavController。这会将 NavController 与 NavHostFragment 关联。

随后，对 NavController.createGraph() 的调用会将该图关联到 NavController，继而也关联到 NavHostFragment：

@Serializable
data class Profile(val name: String)

@Serializable
object FriendsList

// Retrieve the NavController.
val navController = findNavController(R.id.nav_host_fragment)

// Add the graph to the NavController with `createGraph()`.
navController.graph = navController.createGraph(
    startDestination = Profile(name = "John Smith")
) {
    // Associate each destination with one of the route constants.
    fragment<ProfileFragment, Profile> {
        label = "Profile"
    }

    fragment<FriendsListFragment, FriendsList>() {
        label = "Friends List"
    }

    // Add other fragment destinations similarly.
}

以这种方式使用 DSL 非常类似于上文关于 Compose 的部分中介绍的工作流。例如，在那里和这里，NavController.createGraph() 函数都会生成 NavGraph。同样，那里的 NavGraphBuilder.composable() 会向图表添加可组合目的地，这里的 NavGraphBuilder.fragment() 会添加 fragment 目的地。

如需详细了解如何使用 Kotlin DSL，请参阅使用 NavGraphBuilder DSL 构建图表。

XML

您可以直接自行编写 XML。以下示例是上一部分中的双屏示例的镜像，效果同等。

首先，创建一个 NavHostFragment。它充当包含实际导航图的导航宿主。

NavHostFragment 的最小实现：

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:navGraph="@navigation/nav_graph" />

</FrameLayout>

NavHostFragment 包含 app:navGraph 属性。使用此属性可将导航图连接到导航宿主。以下示例展示了如何实现该图：

<navigation xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/nav_graph"
    app:startDestination="@id/profile">

    <fragment
        android:id="@+id/profile"
        android:name="com.example.ProfileFragment"
        android:label="Profile">

        <!-- Action to navigate from Profile to Friends List. -->
        <action
            android:id="@+id/action_profile_to_friendslist"
            app:destination="@id/friendslist" />
    </fragment>

    <fragment
        android:id="@+id/friendslist"
        android:name="com.example.FriendsListFragment"
        android:label="Friends List" />

    <!-- Add other fragment destinations similarly. -->
</navigation>

您可以使用操作来定义不同目的地之间的连接。在此示例中，profile fragment 包含一项导航到 friendslist 的操作。如需了解详情，请参阅使用导航操作和 fragment。

编辑器

您可以使用 Android Studio 中的 Navigation Editor 管理应用的导航图。这在本质上是一个可用于创建和修改 NavigationFragment XML 的 GUI，如上一部分所示。

如需了解详情，请参阅导航编辑器。

嵌套图

您还可以使用嵌套图。这涉及使用图表作为导航目的地。如需了解详情，请参阅嵌套图。

深入阅读

如需了解更多核心导航概念，请参阅以下指南：

概览：请务必阅读 Navigation 组件的一般概览。
activity 目的地：有关如何实现将用户转到 activity 的目的地的示例。
对话框目的地：有关如何创建用于将用户转到对话框的目的地的示例。
导航到目的地：有关如何从一个目的地导航到另一个目的地的详细指南。
嵌套图：有关如何将一个导航图嵌套在另一个导航图中的深度指南。