使用 Compose 进行导航

Navigation 组件支持 Jetpack Compose 应用。您可以在可组合项之间导航 同时利用导航组件的基础架构和 功能。

设置

如需支持 Compose，请在应用模块的 build.gradle 文件：

Groovy

dependencies {
    def nav_version = "2.8.0"

    implementation "androidx.navigation:navigation-compose:$nav_version"
}

Kotlin

dependencies {
    val nav_version = "2.8.0"

    implementation("androidx.navigation:navigation-compose:$nav_version")
}

开始使用

在应用中实现导航时，请实现导航宿主， 图和控制器。如需了解详情，请参阅导航概览。

如需了解如何在 Compose 中创建 NavController，请参阅 Compose 创建导航控制器部分。

创建 NavHost

如需了解如何在 Compose 中创建 NavHost，请参阅 Compose 部分 设计导航图部分。

如需了解如何前往可组合项，请参阅前往 架构中的目的地 文档。

Navigation Compose 还支持在可组合项目的地之间传递参数。为此，您需要向路线中添加参数占位符，就像在使用基础导航库时向深层链接中添加参数一样。

NavHost(startDestination = "profile/{userId}") {
    ...
    composable("profile/{userId}") {...}
}

默认情况下，所有参数都会被解析为字符串。arguments 参数的 composable() 接受 NamedNavArgument 对象的列表。您可以 使用 navArgument() 方法快速创建 NamedNavArgument，并 然后指定其确切 type：

NavHost(startDestination = "profile/{userId}") {
    ...
    composable(
        "profile/{userId}",
        arguments = listOf(navArgument("userId") { type = NavType.StringType })
    ) {...}
}

您应该从 composable() 函数的 lambda 中提供的 NavBackStackEntry 中提取这些参数。

composable("profile/{userId}") { backStackEntry ->
    Profile(navController, backStackEntry.arguments?.getString("userId"))
}

若要将相应参数传递到目的地，您需要在执行 navigate 调用时将该参数添加到路线：

navController.navigate("profile/user1234")

如需查看支持的类型的列表，请参阅在目的地之间传递数据。

在导航时检索复杂数据

强烈建议在导航时不要传递复杂的数据对象，而是在执行导航操作时将最少的必要信息（例如唯一标识符或其他形式的 ID）作为参数传递：

// Pass only the user ID when navigating to a new destination as argument
navController.navigate("profile/user1234")

复杂对象应以数据的形式存储在单一可信来源中，例如 数据层在导航后到达目的地后，您可以使用所传递的 ID 从单一可信来源加载所需信息。检索 ViewModel 中负责 访问数据层时，请使用 ViewModel 的 SavedStateHandle：

class UserViewModel(
    savedStateHandle: SavedStateHandle,
    private val userInfoRepository: UserInfoRepository
) : ViewModel() {

    private val userId: String = checkNotNull(savedStateHandle["userId"])

    // Fetch the relevant user information from the data layer,
    // ie. userInfoRepository, based on the passed userId argument
    private val userInfo: Flow<UserInfo> = userInfoRepository.getUserInfo(userId)

// …

}

这种方法有助于防止配置更改期间发生数据丢失，以及在更新或更改相关对象时造成任何不一致。

如需深入了解为何应避免将复杂数据作为参数传递，以及支持的参数类型列表，请参阅在目的地之间传递数据。

添加可选参数

Navigation Compose 还支持可选的导航参数。可选参数与必需参数有以下两点不同：

  • 可选参数必须使用查询参数语法 ("?argName={argName}") 来添加
  • 可选参数必须具有 defaultValue 集或 nullable = true（将默认值隐式设置为 null）

这意味着，所有可选参数都必须以列表的形式显式添加到 composable() 函数：

composable(
    "profile?userId={userId}",
    arguments = listOf(navArgument("userId") { defaultValue = "user1234" })
) { backStackEntry ->
    Profile(navController, backStackEntry.arguments?.getString("userId"))
}

现在，即使没有向目的地传递任何参数，系统也会使用 defaultValue“user1234”。

通过路线处理参数的结构意味着可组合项将完全独立于 Navigation，并且更易于测试。

Navigation Compose 支持隐式深层链接，此类链接也可定义为 composable() 函数的一部分。其 deepLinks 参数接受一个 NavDeepLink 对象，您可以使用 navDeepLink() 方法：

val uri = "https://www.example.com"

composable(
    "profile?id={id}",
    deepLinks = listOf(navDeepLink { uriPattern = "$uri/{id}" })
) { backStackEntry ->
    Profile(navController, backStackEntry.arguments?.getString("id"))
}

通过这些深层链接，您可以将特定网址、操作或 MIME 类型 可组合项。默认情况下，这些深层链接不会向外部应用公开。接收者 因此您必须添加相应的 将 <intent-filter> 元素添加到应用的 manifest.xml 文件中。为了实现深度分析 链接，则应将以下内容添加到 <activity> 元素：

<activity …>
  <intent-filter>
    ...
    <data android:scheme="https" android:host="www.example.com" />
  </intent-filter>
</activity>

当其他应用触发该深层链接时，Navigation 会自动深层链接到相应的可组合项。

这些深层链接还可用于构建包含可组合项中的相关深层链接的 PendingIntent：

val id = "exampleId"
val context = LocalContext.current
val deepLinkIntent = Intent(
    Intent.ACTION_VIEW,
    "https://www.example.com/$id".toUri(),
    context,
    MyActivity::class.java
)

val deepLinkPendingIntent: PendingIntent? = TaskStackBuilder.create(context).run {
    addNextIntentWithParentStack(deepLinkIntent)
    getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT)
}

然后，您可以像使用任何其他 PendingIntent 一样，使用此 deepLinkPendingIntent 在相应深层链接目的地打开您的应用。

嵌套导航结构

如需了解如何创建嵌套导航图，请参阅 嵌套图。

与底部导航栏集成

通过在可组合项层次结构中的更高层级定义 NavController，您可以将 Navigation 与其他组件（例如底部导航组件）相关联。这样，您就可以选择底部的图标来进行导航 栏。

如需使用 BottomNavigation 和 BottomNavigationItem 组件，请将 androidx.compose.material 依赖项添加到您的 Android 应用中。

Groovy

dependencies {
    implementation "androidx.compose.material:material:1.7.1"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

dependencies {
    implementation("androidx.compose.material:material:1.7.1")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

如需将底部导航栏中的项与您的导航图中的路线相关联，建议您定义密封的类（例如此处所示的 Screen），其中包含相应目的地的路线和字符串资源 ID。

sealed class Screen(val route: String, @StringRes val resourceId: Int) {
    object Profile : Screen("profile", R.string.profile)
    object FriendsList : Screen("friendslist", R.string.friends_list)
}

然后，将这些项放置在 BottomNavigationItem 可以使用的列表中：

val items = listOf(
   Screen.Profile,
   Screen.FriendsList,
)

在 BottomNavigation 可组合项中，使用 currentBackStackEntryAsState() 函数获取当前的 NavBackStackEntry。此条目允许您访问当前的 NavDestination。每个 Pod 的选定状态 然后，可以通过比较项的路由来确定 BottomNavigationItem 包含当前目的地的路线及其父目的地 使用嵌套导航和 NavDestination 层次结构。

该项目的路由还用于将 onClick lambda 连接到对 navigate 的调用，以便在点按该项时会转到该项。通过使用 saveState 和 restoreState 标志，当您在底部导航项之间切换时，系统会正确保存并恢复该项的状态和返回堆栈。

val navController = rememberNavController()
Scaffold(
  bottomBar = {
    BottomNavigation {
      val navBackStackEntry by navController.currentBackStackEntryAsState()
      val currentDestination = navBackStackEntry?.destination
      items.forEach { screen ->
        BottomNavigationItem(
          icon = { Icon(Icons.Filled.Favorite, contentDescription = null) },
          label = { Text(stringResource(screen.resourceId)) },
          selected = currentDestination?.hierarchy?.any { it.route == screen.route } == true,
          onClick = {
            navController.navigate(screen.route) {
              // Pop up to the start destination of the graph to
              // avoid building up a large stack of destinations
              // on the back stack as users select items
              popUpTo(navController.graph.findStartDestination().id) {
                saveState = true
              }
              // Avoid multiple copies of the same destination when
              // reselecting the same item
              launchSingleTop = true
              // Restore state when reselecting a previously selected item
              restoreState = true
            }
          }
        )
      }
    }
  }
) { innerPadding ->
  NavHost(navController, startDestination = Screen.Profile.route, Modifier.padding(innerPadding)) {
    composable(Screen.Profile.route) { Profile(navController) }
    composable(Screen.FriendsList.route) { FriendsList(navController) }
  }
}

在这里，您可以利用 NavController.currentBackStackEntryAsState() 方法从 NavHost 函数中获取 navController 状态，并与 BottomNavigation 组件共享此状态。这意味着 BottomNavigation 会自动拥有最新状态。

Navigation Compose 中的类型安全

本页面上的代码不符合类型安全要求。您可以调用 navigate() 函数。不过，您可以 设计导航代码的结构，使其在运行时符合类型安全要求。这样做可以避免崩溃，并确保：

  • 导航到目的地或导航图时您提供的参数的类型正确，并且所需的所有参数都存在。
  • 您从 SavedStateHandle 中检索到的参数的类型正确。

如需了解详情，请参阅 Kotlin DSL 和 Navigation 中的类型安全 写邮件。

互操作性

如果您想将 Navigation 组件与 Compose 配合使用，有以下两种选择：

  • 使用基于 fragment 的 Navigation 组件定义导航图。
  • 使用 Compose 目的地在 Compose 中通过 NavHost 定义导航图。只有在导航图中的所有界面都是可组合项的情况下，才可以这么做。

因此，若要构建 Compose 和 View 混合应用，我们建议使用基于 Fragment 的 Navigation 组件。然后，fragment 将存储基于 View 的数据 界面、Compose 界面以及同时使用 View 和 Compose 的界面。每次 fragment 的内容位于 Compose 中，下一步是将所有这些界面关联起来 与 Navigation Compose 结合使用，并移除所有 fragment。

要在 Compose 代码内更改目的地，您可以公开可传递到并由层次结构中的任何可组合项触发的事件：

@Composable
fun MyScreen(onNavigate: (Int) -> Unit) {
    Button(onClick = { onNavigate(R.id.nav_profile) } { /* ... */ }
}

在您的 fragment 中，您可以通过找到 NavController 并导航到目的地，在 Compose 和基于 fragment 的 Navigation 组件之间架起桥梁：

override fun onCreateView( /* ... */ ) {
    setContent {
        MyScreen(onNavigate = { dest -> findNavController().navigate(dest) })
    }
}

或者，您可以将 NavController 传递到 Compose 层次结构下方。不过，公开简单的函数的可重用性和可测试性更高。

测试

将导航代码与可组合目的地分离开来，以便进行测试 将每个可组合项与 NavHost 可组合项分开。

也就是说，您不应将 navController 直接传入任何 可组合项，改为将导航回调作为形参传递。这样， 所有可组合项都可单独测试，因为它们不需要 测试中 navController 的实例。

composable lambda 提供的间接层可让你 将 Navigation 代码与可组合项本身分开。这在以下两个方向上可行：

  • 仅将解析后的参数传递到可组合项
  • 传递应由要导航的可组合项触发的 lambda，而不是 NavController 本身。

例如，一个 Profile 可组合项接受 userId 作为输入并允许 导航到朋友个人资料页面的用户可能会带有以下签名：

@Composable
fun Profile(
    userId: String,
    navigateToFriendProfile: (friendUserId: String) -> Unit
) {
 …
}

这样，Profile 可组合项可独立于 Navigation 运行，从而可单独进行测试。composable lambda 会封装弥合 Navigation API 与您的可组合项之间的差距所需的基本逻辑：

composable(
    "profile?userId={userId}",
    arguments = listOf(navArgument("userId") { defaultValue = "user1234" })
) { backStackEntry ->
    Profile(backStackEntry.arguments?.getString("userId")) { friendUserId ->
        navController.navigate("profile?userId=$friendUserId")
    }
}

建议通过测试 NavHost、传递给可组合项的导航操作以及各个屏幕可组合项来编写涵盖应用导航要求的测试。

测试 NavHost

如需开始测试 NavHost，请添加以下导航测试 依赖项：

dependencies {
// ...
  androidTestImplementation "androidx.navigation:navigation-testing:$navigationVersion"
  // ...
}

您可以设置 NavHost 测试对象，并将 navController 实例的实例传递给该对象。对于这种情况 测试工件提供了 TestNavHostController。用于验证应用启动目的地和 NavHost 的界面测试将如下所示：

class NavigationTest {

    @get:Rule
    val composeTestRule = createComposeRule()
    lateinit var navController: TestNavHostController

    @Before
    fun setupAppNavHost() {
        composeTestRule.setContent {
            navController = TestNavHostController(LocalContext.current)
            navController.navigatorProvider.addNavigator(ComposeNavigator())
            AppNavHost(navController = navController)
        }
    }

    // Unit test
    @Test
    fun appNavHost_verifyStartDestination() {
        composeTestRule
            .onNodeWithContentDescription("Start Screen")
            .assertIsDisplayed()
    }
}

测试导航操作

您可以通过多种方式测试导航实现，方法是对界面元素执行点击，然后验证所显示的目的地，或将预期路线与当前路线进行比较。

如果您要测试具体应用的实现，最好在界面中执行点击操作。如需了解如何单独测试各个可组合函数，请务必查看在 Jetpack Compose 中进行测试 Codelab。

您还可以使用 navController 检查您的断言，只需使用 navController 的 currentBackStackEntry 将当前 String 路线与预期路线进行比较即可：

@Test
fun appNavHost_clickAllProfiles_navigateToProfiles() {
    composeTestRule.onNodeWithContentDescription("All Profiles")
        .performScrollTo()
        .performClick()

    val route = navController.currentBackStackEntry?.destination?.route
    assertEquals(route, "profiles")
}

如需详细了解 Compose 测试基础知识，请参阅 测试 Compose 布局和在 Jetpack Compose 中进行测试 Codelab。 如需详细了解导航代码的高级测试，请参阅测试导航指南。

了解详情

如需详细了解 Jetpack Navigation，请参阅 Navigation 组件使用入门或完成 Jetpack Compose Navigation Codelab。

如需了解如何设计应用导航，使其适应不同的屏幕尺寸、屏幕方向和设备外形规格，请参阅自适应界面的导航。

如需了解更高级的 Compose 导航实现，请参阅 模块化应用，包括嵌套图表和底部导航栏等概念 集成，请查看 GitHub 上的 Now in Android 应用。

示例