导航栏

导航栏提供对在大型屏幕设备上运行的应用中目标的访问。您应该将导航栏用于

  • 应用中任何位置都可访问的顶级目标
  • 三到七个主要目标
  • 平板电脑或桌面布局
A vertical navigation rail on the left side of a screen with four destinations (All Files, Recent, Photos, and Library), each with an associated icon, and a floating action button.
图 1. 包含四个目标和一个浮动操作按钮的导航栏。

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

API 界面

使用 NavigationRail 可组合项与 NavigationRailItem 在您的应用中实现导航栏。NavigationRailItem 代表导航栏列中的单个导航栏项。

NavigationRailItem 包含以下关键参数

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

示例：基于导航栏的导航

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

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

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

要点

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

结果

下图显示了前一个代码段的结果

A vertical navigation rail with 3 destinations with associated icons: Songs, Album, and Playlist. Icons visually indicate the purpose of each navigation button in the rail. Each destination has a relevant icon paired with it (e.g., a music note for
图 2. 包含 3 个目标及其关联图标的导航栏：歌曲、专辑和播放列表。

其他资源