导航栏

导航栏允许用户在应用中的不同目标之间切换。您应该在以下情况下使用导航栏：

  • 三到五个同等重要的目标
  • 紧凑的窗口尺寸
  • 应用屏幕间一致的目标
A navigation bar with 4 destinations. Each destination has a placeholder name called
图 1. 包含 4 个目标的导航栏。

此页面将向您展示如何在应用中显示包含相关屏幕和基本导航的导航栏。

API surface

使用 NavigationBar 和 NavigationBarItem 可组合项来实现目标切换逻辑。每个 NavigationBarItem 表示一个单一目标。

NavigationBarItem 包含以下关键参数

  • selected：确定当前项是否在视觉上高亮显示。
  • onClick()：一个必需的 lambda 函数，用于定义用户点击该项时要执行的操作。您通常在此处处理导航事件、更新选中项状态或加载相应内容。
  • label：在项中显示文本。可选。
  • icon：在项中显示图标。可选。

示例：底部导航栏

以下代码段实现了一个带项的底部导航栏，用户可以在应用中不同屏幕之间导航

@Composable
fun NavigationBarExample(modifier: Modifier = Modifier) {
    val navController = rememberNavController()
    val startDestination = Destination.SONGS
    var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) }

    Scaffold(
        modifier = modifier,
        bottomBar = {
            NavigationBar(windowInsets = NavigationBarDefaults.windowInsets) {
                Destination.entries.forEachIndexed { index, destination ->
                    NavigationBarItem(
                        selected = selectedDestination == index,
                        onClick = {
                            navController.navigate(route = destination.route)
                            selectedDestination = index
                        },
                        icon = {
                            Icon(
                                destination.icon,
                                contentDescription = destination.contentDescription
                            )
                        },
                        label = { Text(destination.label) }
                    )
                }
            }
        }
    ) { contentPadding ->
        AppNavHost(navController, startDestination, modifier = Modifier.padding(contentPadding))
    }
}
Navigation.kt

关键点

  • NavigationBar 显示项的集合，每个项对应一个 Destination。
  • val navController = rememberNavController() 创建并记住一个 NavHostController 实例，该实例管理 NavHost 中的导航。
  • var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) } 管理当前选中项的状态。
  • var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) } 管理当前选中项的状态。
    • startDestination.ordinal 获取 Destination.SONGS 枚举条目的数字索引（位置）。
  • 当点击一个项时，会调用 navController.navigate(route = destination.route) 导航到相应的屏幕。
  • NavigationBarItem 的 onClick lambda 更新 selectedDestination 状态以在视觉上突出显示被点击的项。
  • 它调用 AppNavHost 可组合项，传入 navController 和 startDestination，以显示所选屏幕的实际内容。

结果

下图显示了上一个代码段生成的导航栏

An app screen with 3 destinations listed horizontally in a bottom navigation bar: Songs, Album, and Playlist. Each destination has a relevant icon paired with it (e.g., a music note for “Songs”).
图 2. 包含 3 个目标及其关联图标的导航栏：歌曲、专辑和播放列表。

其他资源