应用栏

应用栏是容器,可让用户访问关键功能和导航项。应用栏分为两种类型:顶部应用栏和底部应用栏。它们各自的外观和用途如下:

类型

外观

用途

顶部应用栏

屏幕顶部。

提供对关键任务和信息的访问权限。通常包含标题、核心待办项和某些导航项。

底部应用栏

横跨屏幕底部。

通常包含核心导航项。还可提供对其他关键操作的访问权限,例如通过包含的悬浮操作按钮。

顶部和底部应用栏示例。
图 1. 顶部应用栏(左)和底部应用栏(右)。

如需实现顶部应用栏和底部应用栏,请分别使用 TopAppBar 和 BottomAppBar 可组合项。借助这些组件,您可以创建封装了导航和操作控件且符合 Material Design 原则的一致界面。

顶部应用栏

下表概述了四种类型的顶部应用栏:

类型

示例

小:适用于不需要太多导航或操作的屏幕。

小型顶部应用栏

居中对齐:适用于具有单个主要操作的界面。

居中对齐的顶部应用栏

中等:适用于需要适量导航和操作的屏幕。

中等顶部应用栏

大:适用于需要大量导航和操作的屏幕。

大型顶部应用栏

API Surface

可用于实现四种不同顶部应用栏的各种可组合项非常相似。它们有几个共同的关键参数:

  • title:显示在应用栏中的文本。
  • navigationIcon:用于导航的主要图标。显示在应用栏的左侧。
  • actions:可让用户执行关键操作的图标。它们显示在应用栏的右侧。
  • scrollBehavior:确定顶部应用栏如何响应 Scaffold 内部内容的滚动。
  • colors:确定应用栏的显示方式。

滚动行为

您可以控制当用户滚动给定 Scaffold 的内部内容时应用栏如何响应。为此,请创建一个 TopAppBarScrollBehavior 实例,并将其作为 scrollBehavior 参数传递给顶部应用栏。

TopAppBarScrollBehavior 有三种类型。这些机会如下:

  • enterAlwaysScrollBehavior:当用户向上拉动 Scaffold 的内部内容时,顶部应用栏会收起。当用户开始下拉内部内容时,应用栏会展开。
  • exitUntilCollapsedScrollBehavior:与 enterAlwaysScrollBehavior 类似,但仅当用户将内容一直向下拉时,应用栏才会展开。
  • pinnedScrollBehavior:应用栏保持在原位,不会对滚动做出反应。

以下示例实现了其中几个选项。

示例

以下部分提供了四种不同类型的顶部应用栏的实现,包括如何控制滚动行为的不同示例。

小

如需创建小型顶部应用栏,请使用 TopAppBar 可组合项。以下示例实现了一个仅包含标题的基本顶部应用栏。

以下示例未向 TopAppBar 传递 scrollBehavior 的值,因此它不会对内部内容的滚动做出响应。

@Composable
fun SmallTopAppBarExample() {
    Scaffold(
        topBar = {
            TopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text("Small Top App Bar")
                }
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}

此实现如下所示:

图 2. 小型顶部应用栏。

已居中对齐

居中对齐的顶部应用栏与小型应用栏基本相同,只是标题在组件中居中。如需实现此功能,请使用专用的 CenterAlignedTopAppBar 可组合项。

此示例使用 enterAlwaysScrollBehavior() 获取它为 scrollBehavior 传递的值。因此,当用户滚动 Scaffold 的内部内容时,该栏会收起。

@Composable
fun CenterAlignedTopAppBarExample() {
    val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior(rememberTopAppBarState())

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),

        topBar = {
            CenterAlignedTopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text(
                        "Centered Top App Bar",
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis
                    )
                },
                navigationIcon = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Menu),
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}

此实现如下所示:

图 3. 居中对齐的顶部应用栏。

中

中等顶部应用栏会将标题置于任何其他图标下方。如需创建,请使用 MediumTopAppBar 可组合项。

与前面的代码段一样,此示例使用 enterAlwaysScrollBehavior() 获取它为 scrollBehavior 传递的值。

@Composable
fun MediumTopAppBarExample() {
    val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior(rememberTopAppBarState())

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            MediumTopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text(
                        "Medium Top App Bar",
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis
                    )
                },
                navigationIcon = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Menu),
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}

此实现如下所示,并演示了 enterAlwaysScrollBehavior() 的滚动行为:

图 4. 中等顶部应用栏,在用户向上滚动时收起,在用户向下滚动时展开。

大

大型顶部应用栏与中型顶部应用栏类似,但标题和图标之间的内边距更大,并且在屏幕上占用的空间也更多。如需创建,请使用 LargeTopAppBar 可组合项。

与前面的代码段不同,此示例使用 exitUntilCollapsedScrollBehavior() 获取它为 scrollBehavior 传递的值。因此,当用户滚动 Scaffold 的内部内容时,该栏会收起,但当用户滚动到内部内容的末尾时,该栏会展开。

@Composable
fun LargeTopAppBarExample() {
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior(rememberTopAppBarState())

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            LargeTopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text(
                        "Large Top App Bar",
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis
                    )
                },
                navigationIcon = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Menu),
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}

此实现如下所示:

图 5. 大型顶部应用栏的实现示例。

M3 Expressive 更新

新的中型灵活和大型灵活应用栏进行了重大改进,例如灵活的高度、多行支持和居中文字。它们还可以包含更多种类的元素,例如图片。建议使用中等弹性应用栏和大型弹性应用栏,而不是中等应用栏和大型应用栏。 小型应用栏也进行了更新,同样提升了灵活性。

具有灵动样式的顶部应用栏。
图 6. M3 Expressive 顶部应用栏变体。

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

居中和左对齐

小 浅色主题居中对齐的顶部应用栏(带字幕)
深色主题顶部应用栏
中 浅色主题居中对齐的中型顶部应用栏(带副标题)
深色主题中型顶部应用栏
大 浅色主题居中对齐的大型顶部应用栏(带副标题)
深色主题大型顶部应用栏

小标题、中等灵活标题和大灵活标题可以靠前缘对齐或居中。

以下代码段演示了如何实现带有副标题的居中对齐顶部应用栏:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun SimpleCenterAlignedTopAppBarWithSubtitle() {
    val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            TopAppBar(
                title = { Text("Simple TopAppBar", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                subtitle = { Text("Subtitle", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                titleHorizontalAlignment = Alignment.CenterHorizontally,
                navigationIcon = {
                    IconButton(onClick = { /* onBackClick() */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description",
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(painter = rememberVectorPainter(AppIcons.Favorite), contentDescription = "Localized description")
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
        content = { innerPadding ->
            // ...
        },
    )
}

滚动行为

始终输入

当用户向下滚动浏览内容(向上拉动内容)时,应用栏会立即收起。当用户向上滚动(向下拉动内容)时,应用栏会立即展开,无论用户位于可滚动内容列表中的哪个位置。

以下代码段演示了如何实现具有“enter-always”滚动行为的顶部应用栏:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun EnterAlwaysTopAppBar() {
    val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            TopAppBar(
                title = { Text("TopAppBar", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                subtitle = { Text("Subtitle", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                navigationIcon = {
                    IconButton(onClick = { /* onBackClick() */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description",
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(painter = rememberVectorPainter(AppIcons.Favorite), contentDescription = "Localized description")
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
        content = { innerPadding ->
            // ...
        },
    )
}

以下视频展示了上述代码段的结果:

图 7. 具有“始终进入”滚动行为的顶部应用栏,会在用户向下滚动时收起,在用户向上滚动时展开。

退出,直到收起

当用户向下滚动内容(向上拉动内容)时,中型和大型弹性应用栏会收起,直到只有收起的应用栏保持可见。当用户向上滚动(将内容向下拉)时,应用栏会保持收起状态,直到用户到达内容顶部,此时应用栏会展开回其完整高度,并以其副标题为中心。

中等柔韧度

以下代码段演示了如何实现具有“退出直到收起”滚动行为的中等灵活顶部应用栏:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun ExitUntilCollapsedCenterAlignedMediumFlexibleTopAppBar() {
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            MediumFlexibleTopAppBar(
                title = { Text("Medium TopAppBar", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                subtitle = { Text("Subtitle", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                titleHorizontalAlignment = Alignment.CenterHorizontally,
                navigationIcon = {
                    IconButton(onClick = { /* onBackClick() */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description",
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(painter = rememberVectorPainter(AppIcons.Favorite), contentDescription = "Localized description")
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
        content = { innerPadding ->
            // ...
        },
    )
}

以下视频展示了上述代码段的结果:

图 8. 一个中等大小、居中对齐的顶部应用栏,会在用户向下滚动时收起。

大型灵活

以下代码段演示了如何实现具有“退出直到收起”滚动行为的大型灵活顶部应用栏:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun ExitUntilCollapsedCenterAlignedLargeFlexibleTopAppBar() {
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            LargeFlexibleTopAppBar(
                title = { Text("Large TopAppBar", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                subtitle = { Text("Subtitle", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                titleHorizontalAlignment = Alignment.CenterHorizontally,
                navigationIcon = {
                    IconButton(onClick = { /* onBackClick() */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description",
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(painter = rememberVectorPainter(AppIcons.Favorite), contentDescription = "Localized description")
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
        content = { innerPadding ->
            // ...
        },
    )
}

以下视频展示了上述代码段的结果:

图 9. 一个大型、居中对齐的顶部应用栏,会在用户向下滚动时收起。

底部应用栏

如需创建底部应用栏,请使用 BottomAppBar 可组合项。此可组合项的使用方式与本页前面部分所述的顶部应用栏可组合项类似。您需要为以下关键参数传递可组合项:

  • actions:显示在状态栏左侧的一系列图标。这些通常是给定屏幕的关键操作或导航项。
  • floatingActionButton:显示在栏右侧的悬浮操作按钮。

@Composable
fun BottomAppBarExample() {
    Scaffold(
        bottomBar = {
            BottomAppBar(
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(painter = rememberVectorPainter(AppIcons.Check), contentDescription = "Localized description")
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Edit),
                            contentDescription = "Localized description",
                        )
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Mic),
                            contentDescription = "Localized description",
                        )
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Image),
                            contentDescription = "Localized description",
                        )
                    }
                },
                floatingActionButton = {
                    FloatingActionButton(
                        onClick = { /* do something */ },
                        containerColor = BottomAppBarDefaults.bottomAppBarFabColor,
                        elevation = FloatingActionButtonDefaults.bottomAppBarFabElevation()
                    ) {
                        Icon(painter = rememberVectorPainter(AppIcons.Add), "Localized description")
                    }
                }
            )
        },
    ) { innerPadding ->
        Text(
            modifier = Modifier.padding(innerPadding),
            text = "Example of a scaffold with a bottom app bar."
        )
    }
}

此实现如下所示:

图 10. 底部应用栏的实现示例。

M3 Expressive 更新

对于 Material 3 Expressive,请使用停靠式工具栏 (FlexibleBottomAppBar) 而非标准底部应用栏,以实现更短的高度和更灵活的水平项排列。

以下代码段实现了一个 FlexibleBottomAppBar,其中包含一个 AppBarRow,可在空间有限时将额外的操作项移至溢出菜单中:

@Composable
fun FlexibleBottomAppBarSample() {
    val icons =
        listOf(
            AppIcons.ArrowBack,
            AppIcons.ArrowForward,
            AppIcons.Add,
            AppIcons.Check,
            AppIcons.Edit,
            AppIcons.Favorite,
        )
    val items = listOf("Back", "Forward", "Add", "Check", "Edit", "Favorite")

    FlexibleBottomAppBar(
        contentPadding = PaddingValues(horizontal = 96.dp),
        horizontalArrangement = BottomAppBarDefaults.FlexibleFixedHorizontalArrangement,
    ) {
        AppBarRow(
            overflowIndicator = { menuState ->
                IconButton(
                    onClick = {
                        if (menuState.isShowing) {
                            menuState.dismiss()
                        } else {
                            menuState.show()
                        }
                    }
                ) {
                    Icon(
                        painter = rememberVectorPainter(AppIcons.MoreVert),
                        contentDescription = "Overflow",
                    )
                }
            }
        ) {
            items.forEachIndexed { index, item ->
                clickableItem(
                    onClick = { /* doSomething() */ },
                    icon = {
                        Icon(
                            painter = rememberVectorPainter(icons[index]),
                            contentDescription = item,
                        )
                    },
                    label = item,
                )
            }
        }
    }
}

其他资源