TopAppBar：是什么、配置以及在Jetpack Compose中的使用

Jetpack Compose中的TopAppBar是什么？

TopAppBar是来自Material Design库的一个可组合函数，用于Jetpack Compose实现应用顶部面板（App Bar）。该组件显示当前屏幕的标题、左侧的导航按钮和右侧的附加操作。

与经典的View系统不同，Compose版本的TopAppBar完全是声明式的：面板在状态变化时重新绘制，而不是通过findViewById管理。TopAppBar使用slot API的概念，其中title、navigationIcon和actions作为可组合lambda传递。这使得无需继承即可自定义面板的任何元素。

根据Google Material Design（2025），Compose中的TopAppBar有三种类型：CenterAlignedTopAppBar（居中对齐标题）、SmallTopAppBar（标准）和MediumTopAppBar（扩展）。每种类型决定面板高度、标题字体大小和滚动行为。居中变体更常用于主屏幕，而MediumTopAppBar用于内容页面，标题在滚动时逐渐缩小。

为了TopAppBar的正确运行，需要考虑系统边距：来自WindowInsetsCompat的Insets。根据Android Developers（2025）的建议，调用Modifier.statusBarsPadding()或windowInsetsPadding(WindowInsets.systemBars)可以防止面板重叠状态栏。

TopAppBar参数：标题和修饰符的配置

TopAppBar组件接受一系列必需和可选参数。主要参数是title，它接收一个带有标题文本的可组合块。由于title是一个@Composable lambda，不仅可以插入文本，还可以插入带文本的图标、搜索栏或进度条。

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AppTopBar() {
    TopAppBar(
        title = { Text("主页") },
        navigationIcon = {
            IconButton(onClick = { /* open drawer */ }) {
                Icon(
                    Icons.Filled.Menu,
                    contentDescription = "Menu"
                )
            }
        },
        actions = {
            IconButton(onClick = { /* search */ }) {
                Icon(Icons.Filled.Search, contentDescription = "Search")
            }
        }
    )
}

Modifier参数允许设置整个面板的边距、大小和对齐。通过Modifier.heightIn可以限制最小和最大高度。colors参数接受TopAppBarColors对象用于覆盖背景、标题和图标颜色。

默认情况下，TopAppBar使用当前MaterialTheme的配色方案。如果需要自定义调色板，请使用TopAppBarDefaults.smallTopAppBarColors()。在Material3中，背景颜色会自动适应浅色和深色主题中的surfaceColor，消除了手动配置的需要。

TopAppBar中的导航按钮

NavigationIcon是TopAppBar左侧的一个可组合块，通过它实现导航。典型场景：打开导航抽屉（Menu图标）、返回上一个屏幕（ArrowBack图标）或关闭当前屏幕（Close图标）。

图标的选择取决于屏幕在导航堆栈中的位置。如果屏幕是根屏幕 — 显示Menu图标以打开抽屉。如果屏幕是嵌套的 — 显示ArrowBack图标以返回。在Compose中，此逻辑通过NavController实现：当前返回堆栈条目决定显示哪个图标。

根据Material Design（2025）的建议，导航区域的宽度为48dp——触摸交互的标准目标。图标必须可点击，具有视觉反馈（涟漪效果）。在Compose中，这通过包装在带有onClick回调的IconButton中来确保，该回调启动导航。

使用Scaffold时，导航按钮可能会复制传递给Scaffold的DrawerState，而不是直接传递给TopAppBar。在这种情况下，navigationIcon通过rememberDrawerState引用抽屉状态。

添加操作和下拉菜单

TopAppBar中的actions参数接受带有RowScope上下文的可组合块，允许在标题右侧放置多个图标或按钮。每个操作应该是一个可点击的图标元素：搜索、通知、设置、收藏。

对于溢出操作，使用通过DropdownMenu实现的下拉菜单。如果操作数量超过三个，多余的操作将放置在带有MoreVert图标的OverflowMenu中。点击时，隐藏操作的列表打开。DropdownMenu会自动相对于图标定位。

@Composable
fun TopBarWithOverflow() {
    var menuExpanded by remember { mutableStateOf(false) }
    TopAppBar(
        title = { Text("个人资料") },
        actions = {
            IconButton(onClick = { /* share */ }) {
                Icon(Icons.Filled.Share, contentDescription = "Share")
            }
            Box {
                IconButton(onClick = { menuExpanded = true }) {
                    Icon(Icons.Filled.MoreVert, contentDescription = "More")
                }
                DropdownMenu(
                    expanded = menuExpanded,
                    onDismissRequest = { menuExpanded = false }
                ) {
                    DropdownMenuItem(text = { Text("设置") }, onClick = { /* navigate */ })
                    DropdownMenuItem(text = { Text("关于") }, onClick = { /* navigate */ })
                }
            }
        }
    )
}

为每个图标设置contentDescription很重要——这是一个可访问性要求。没有描述，TalkBack将不会朗读按钮。对于纯装饰性元素，使用contentDescription = null。

Material3中的TopAppBar：动态颜色和适应

Material3（M3）是Material Design的当前版本，由Google推荐用于新项目。M3中的TopAppBar通过TopAppBar、CenterAlignedTopAppBar和MediumTopAppBar实现。与Material2的主要区别——内置支持动态颜色、自适应高度和滚动行为。

动态颜色根据设备壁纸自动选择面板颜色（Android 12+）。M3中的TopAppBar使用surfaceColor作为背景，primary作为标题。如果动态颜色不可用，则应用MaterialTheme的回调调色板。根据Google Material Design（2025），63%的Android 12+用户在应用中使用动态颜色。

MediumTopAppBar是一种扩展变体，具有大标题（32sp），在滚动时逐渐减小到20sp，转变为SmallTopAppBar。此效果通过TopAppBarDefaults.mediumTopAppBarColors()和scrollBehavior参数实现。过渡动画由跟踪标题折叠的TopAppBarState控制。

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun MediumTopBarExample() {
    val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior()
    Scaffold(
        topBar = {
            MediumTopAppBar(
                title = { Text("图书馆") },
                navigationIcon = {
                    IconButton(onClick = { }) {
                        Icon(Icons.Filled.Menu, contentDescription = "Menu")
                    }
                },
                scrollBehavior = scrollBehavior
            )
        }
    ) { padding ->
        LazyColumn(contentPadding = padding) { /* content */ }
    }
}

对于Material3 TopAppBar，必须使用@OptIn(ExperimentalMaterial3Api::class)——注释表明API在将来版本中可能更改。截至2025年，M3中的TopAppBar仍然是实验性的，但Google建议在适当验证后用于生产。

ScrollBehavior：滚动时隐藏面板

ScrollBehavior是管理内容垂直滚动时TopAppBar可见性的机制。在Jetpack Compose中，scrollBehavior允许隐藏或缩小面板以释放空间，这在具有大内容列表的屏幕上特别有用。

Material3提供三种策略：enterAlways（向上滚动时面板出现，向下滚动时隐藏）、exitUntilCollapsed（面板仅在标题完全折叠后隐藏）以及通过实现TopAppBarScrollBehavior接口的自定义策略。第一种变体适用于内容提要，第二种——适用于带有MediumTopAppBar的屏幕。

ScrollBehavior需要与LazyColumn或LazyRow通过rememberLazyListState()协调。滚动状态通过scrollBehavior参数传递给TopAppBar。组件自动订阅滚动事件并动画化面板可见性。根据Android Developers（2025），enterAlwaysScrollBehavior是最流行的策略，在75%具有可滚动TopAppBar的应用中使用。

配置自定义ScrollBehavior

要创建自定义行为，请继承TopAppBarScrollBehavior并重写onScroll和onDrag方法。当标准场景不涵盖设计要求时，自定义行为很有用——例如，面板应该仅在超过特定滚动阈值后隐藏。

默认情况下，scrollBehavior不会为内容添加边距——paddingTop需要通过Scaffold中的contentPadding或LazyColumn中的Modifier.padding手动设置。在MediumTopAppBar中，边距通过TopAppBarState.collapsedFraction自动计算。

val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()
Scaffold(
    topBar = {
        MediumTopAppBar(
            title = { Text("内容") },
            scrollBehavior = scrollBehavior
        )
    }
) { padding ->
    LazyColumn(contentPadding = padding) { /* items */ }
}

ScrollBehavior仅在Material3中可用。在Material2中，TopAppBar没有内置的滚动时隐藏支持——类似的行为需要通过NestedScrollConnection手动实现。