导航栏

导航栏可让用户在应用中的不同目的地之间切换。您应在以下情况下使用导航栏:

  • 3 到 5 个同等重要的目的地
  • 紧凑窗口大小
  • 应用屏幕中的目标页面保持一致
包含 4 个目的地的导航栏。每个目的地都有一个名为“Label”的占位符名称,所选目的地显示为圆形图标,其余目的地显示为三角形。
图 1. 包含 4 个目的地的导航栏。

本页面介绍了如何在应用中显示导航栏,以及相关界面和基本导航。

API Surface

使用 NavigationBar 和 NavigationBarItem 可组合项实现目的地切换逻辑。每个 NavigationBarItem 代表一个目的地。

NavigationBarItem 包含以下关键参数:

  • selected:确定当前项是否在视觉上突出显示。
  • onClick():定义用户点击该项时要执行的操作。用于处理导航事件、更新所选项状态或加载相应内容的逻辑属于此处。
  • 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))
    }
}

要点

  • NavigationBar 会显示一系列项,其中每个项都对应一个 Destination。
  • val navController = rememberNavController() 会创建并记住 NavHostController 的实例,该实例用于管理 NavHost 中的导航。
  • var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) } 管理所选项的状态。
    • startDestination.ordinal 获取 Destination.SONGS 枚举条目的数字索引(位置)。
  • 点击某个项时,系统会调用 navController.navigate(route = destination.route) 以转到相应界面。
  • NavigationBarItem 的 onClick lambda 会更新 selectedDestination 状态,以直观地突出显示所点击的项。
  • 导航逻辑会调用 AppNavHost 可组合项,并传递 navController 和 startDestination,以显示所选屏幕的实际内容。

结果

下图显示了上述代码段生成的导航栏:

图 2. 包含 3 个目的地(歌曲、专辑和播放列表)及相关图标的导航栏。

M3 Expressive 更新

Material 3 Expressive 引入了 ShortNavigationBar 和 ShortNavigationBarItem,作为标准 NavigationBar 之外的其他灵活选项。

Material 3 灵活导航栏示例,高度较短,图标带有标签。
图 3. 灵活的导航栏。

如需详细了解导航栏的 M3 Expressive 更新,请参阅 Material Design 3 导航栏指南。

ShortNavigationBar 中的导航项可以垂直或水平排列。

包含垂直项的导航栏

在紧凑窗口(例如移动设备上)中使用垂直项。以下代码段演示了如何实现包含垂直项的 ShortNavigationBar:

@Composable
fun ShortNavigationBarSample() {
    var selectedItem by remember { mutableIntStateOf(0) }
    val items = listOf("Songs", "Artists", "Playlists")

    ShortNavigationBar {
        items.forEachIndexed { index, item ->
            ShortNavigationBarItem(
                icon = {
                    Icon(
                        painter = rememberVectorPainter(if (selectedItem == index) AppIcons.FavoriteFilled else AppIcons.Favorite),
                        contentDescription = null,
                    )
                },
                label = { Text(item) },
                selected = selectedItem == index,
                onClick = { selectedItem = index },
            )
        }
    }
}

包含水平项的导航栏

在中等窗口(例如平板电脑)中使用横向列表项。以下代码段演示了如何实现 ShortNavigationBar,其中水平项在栏中居中:

@Composable
fun ShortNavigationBarWithHorizontalItemsSample() {
    var selectedItem by remember { mutableIntStateOf(0) }
    val items = listOf("Songs", "Artists", "Playlists")

    Column {
        Text(
            "Note: this configuration is better displayed in medium screen sizes.",
            Modifier.padding(16.dp),
        )

        Spacer(Modifier.height(32.dp))

        ShortNavigationBar(arrangement = ShortNavigationBarArrangement.Centered) {
            items.forEachIndexed { index, item ->
                ShortNavigationBarItem(
                    iconPosition = NavigationItemIconPosition.Start,
                    icon = {
                        Icon(
                            painter = rememberVectorPainter(if (selectedItem == index) AppIcons.FavoriteFilled else AppIcons.Favorite),
                            contentDescription = null,
                        )
                    },
                    label = { Text(item) },
                    selected = selectedItem == index,
                    onClick = { selectedItem = index },
                )
            }
        }
    }
}

其他资源