Jetpack系列之Compose TopBar

（一）概述

在 Jetpack Compose（Material / Material3）中，TopBar 通常指 Top App Bar，用于：显示页面标题，放置返回按钮，提供页面级操作（搜索、更多菜单等），在 Material Design 3 中，它是 Scaffold 的核心组成部分之一。

（二）TopBar 属性说明

title：用于定义 TopBar 中代表当前页面的标题。

modifier：用于为 TopBar 本身添加布局约束、语义标记、测试标识或与父级滚动系统的行为衔接。

navigationIcon：定义 TopBar 左侧的导航入口，用于表达页面在导航层级中的位置或提供返回、关闭等导航能力。

actions：定义 TopBar 右侧的页面级操作区域，用于放置与当前页面内容直接相关的快捷行为。

colors：用于配置 TopBar 在静止与滚动等不同状态下的背景及内容颜色，以维持主题一致性和层级感。

scrollBehavior：用于描述 TopBar 随内容滚动时的折叠、吸顶或显隐策略，并决定标题与背景的滚动反馈方式。

（三）TopBar 封装

package com.leo.wechat.ui.component.topbar

import androidx.compose.ui.graphics.painter.Painter

data class AppTopBarIcon(
    val enabled: Boolean,
    val painter: Painter,
    val onClick: () -> Unit,
)

AppTopBarIcon.kt 说明：定义一个TopBar上的Icon模型

package com.leo.wechat.ui.component.topbar

import androidx.compose.runtime.Composable
import androidx.compose.ui.res.painterResource
import com.leo.wechat.R

object AppTopBarIcons {

    @Composable
    fun back(
        enabled: Boolean = true,
        onClick: () -> Unit,
    ) = AppTopBarIcon(
        enabled = enabled,
        painter = painterResource(R.drawable.ic_back),
        onClick = onClick
    )

    @Composable
    fun more(
        enabled: Boolean = true,
        onClick: () -> Unit,
    ) = AppTopBarIcon(
        enabled = enabled,
        painter = painterResource(R.drawable.ic_more),
        onClick = onClick
    )
}

AppTopBarIcons.kt 说明：封装一些默认的Icon应用模型

package com.leo.wechat.ui.component.topbar

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import com.leo.wechat.ui.component.button.AlphaIconButton
import com.leo.wechat.ui.component.text.AppText

@Composable
fun AppTopBar(
    title: String,
    modifier: Modifier = Modifier,
    height: Dp = 48.dp,
    backgroundColor: Color = MaterialTheme.colorScheme.background,
    contentColor: Color = MaterialTheme.colorScheme.onBackground,
    style: TextStyle = MaterialTheme.typography.titleMedium,
    startIcon: AppTopBarIcon? = null,
    endIcon: AppTopBarIcon? = null,
    iconSize: Dp = 20.dp,
    iconPadding: Dp = 4.dp,
    iconMinClickAreaSize: Dp = 48.dp,
) {
    Box(
        modifier = modifier
            .fillMaxWidth()
            .height(height)
            .background(backgroundColor),
    ) {

        // Icon on the left (Back/Menu)
        startIcon?.let { it ->
            AlphaIconButton(
                painter = it.painter,
                onClick = it.onClick,
                modifier = Modifier
                    .align(Alignment.CenterStart)
                    .padding(start = iconPadding),
                enabled = it.enabled,
                contentColor = contentColor,
                iconSize = iconSize,
                iconMinClickAreaSize = iconMinClickAreaSize
            )
        }

        // Icon on the right (More/Edit)
        endIcon?.let { it ->
            AlphaIconButton(
                painter = it.painter,
                onClick = it.onClick,
                modifier = Modifier
                    .align(Alignment.CenterEnd)
                    .padding(end = iconPadding),
                enabled = it.enabled,
                contentColor = contentColor,
                iconSize = iconSize,
                iconMinClickAreaSize = iconMinClickAreaSize
            )
        }

        AppText(
            text = title,
            modifier = Modifier.align(Alignment.Center),
            color = contentColor,
            overflow = TextOverflow.Ellipsis,
            maxLines = 1,
            style = style
        )
    }
}

AppTopBar.kt 说明：自定义一个支持左右图标的 TopBar