📚 课程目录第1章 Material 3设计语言概述

Material 3组件库实战：TopAppBar等 - 第1节

1.1 Material 3 设计语言核心

Material 3 (M3) 是 Google 推出的下一代设计系统，以 以颜色为驱动、自适应、个性化、无障碍 为核心理念。与 Material 2 相比，M3 不再依赖固定的 primary/secondary 色板，而是通过动态配色（Dynamic Color）从用户壁纸提取主色，生成一套完整的 color scheme，涵盖 primary、tertiary、neutral、error 等色系。同时引入 形状系统（Shape System） 和 高度系统（Elevation System），让组件在视觉层级上更清晰。

M3 核心维度	说明	对比 M2 变化
动态色	自动从壁纸提取主色 + 扩展色	M2 固定色板 → 可自适应
形状	定义 corner family（圆角/直角/裁剪）	M2 无统一形状规范
高度	阴影 + 遮挡光效，替代 M2 的 z 轴图层	更真实的光影模拟
无障碍	高对比度、大触摸区域、文字可读性优先	内置色调对比度检查

  实践要点： M3 的颜色方案通过 MaterialTheme.colorScheme（Compose）或 @attr/colorPrimary（XML）访问，开发者需确保主题中正确配置 dynamic colors。

  可通过 dynamicLightColorScheme(context) 在 Android 12+ 上获得系统壁纸色。

1.2 TopAppBar 组件定位

TopAppBar 是 M3 中最重要的顶层导航组件之一，位于屏幕顶部，通常承载应用标题、导航菜单（Menu）、搜索入口、溢出菜单（Overflow）及操作图标。在 M3 中，TopAppBar 被分为四种类型：小型（Small）、中型（Medium）、大型（Large）、居中（Center Aligned），分别适用于不同信息层级。

类型	高度	标题行为	典型场景
Small TopAppBar	64dp	标题靠左，固定高度	列表页、设置页
Medium TopAppBar	112dp	标题从顶部展开，向上滚动后收缩	详情页、内容阅读
Large TopAppBar	152dp	标题大号展示，滚动后缩小到 Medium 最终到 Small	主页、仪表盘
Center Aligned TopAppBar	64dp	标题居中，无滚动行为	确认/操作页面

实现提示： 在 Jetpack Compose 中，分别使用 SmallTopAppBar、MediumTopAppBar、LargeTopAppBar、CenterAlignedTopAppBar 可组合函数。滚动行为需配合 TopAppBarDefaults.{type}ScrollBehavior 实现。

1.3 TopAppBar 与其他组件的关系

TopAppBar 并非孤立存在，它与 M3 导航体系紧密关联：

NavigationRail：在宽屏幕设备中，Rail 位于左侧，TopAppBar 上方需留出 Rail 头部空间。
BottomNavigation：经典导航组合，TopAppBar 和 BottomBar 共同定义页面结构。
NavigationDrawer：TopAppBar 的汉堡图标触发 Drawer 展开，两者通过 drawerState 联动。
Scaffold：作为顶层布局容器，将 TopAppBar、BottomBar、Drawer、FAB 组合在一起。

在 M3 中，TopAppBar 还继承了 Surface 组件的颜色与高度特性，可以通过 containerColor 和 containerElevation 重新配色，不再像 M2 那样强制使用 colorPrimary。

1.4 结构图：M3 设计语言与 TopAppBar 定位

scrollBehavior 实现。

1.5 最小实现：Jetpack Compose 中的 TopAppBar

以下代码演示如何在 Compose 中创建一个 Small TopAppBar，并绑定 NavigationDrawer 的打开动作。注意 TopAppBar 需要包裹在 Scaffold 内。

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun MyTopAppBarSample(drawerState: DrawerState) {
    Scaffold(
        topBar = {
            SmallTopAppBar(
                title = { Text("我的应用") },
                navigationIcon = {
                    IconButton(onClick = {
                        coroutineScope.launch {
                            drawerState.open()
                        }
                    }) {
                        Icon(Icons.Filled.Menu, contentDescription = "菜单")
                    }
                },
                actions = {
                    IconButton(onClick = { /* 搜索 */ }) {
                        Icon(Icons.Filled.Search, contentDescription = "搜索")
                    }
                    IconButton(onClick = { /* 更多 */ }) {
                        Icon(Icons.Filled.MoreVert, contentDescription = "更多")
                    }
                },
                colors = TopAppBarDefaults.smallTopAppBarColors(
                    containerColor = MaterialTheme.colorScheme.surface,
                    titleContentColor = MaterialTheme.colorScheme.onSurface
                ),
                scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior()
            )
        },
        drawerContent = { /* Drawer 内容 */ },
        content = { padding ->
            // 页面主体
        }
    )
}

常见错误： 未正确配置 scrollBehavior 会导致 TopAppBar 无法随滚动收缩。另外，在 Android 12+ 上使用 Dynamic Color 时，务必确保 context 已注入动态色方案，否则 TopAppBar 会沿用旧色板。

1.6 调试要点

检查主题： 在调试面板中输出 MaterialTheme.colorScheme 的 primary、surface、onSurface 值，确认配色符合预期。
滚动行为： 测试 Medium/Large TopAppBar 的折叠动画；若动画僵硬，检查 scrollState 是否正确绑定。
状态栏适配： M3 TopAppBar 默认不会侵入状态栏区域，如需全屏效果，需使用 WindowInsetsControllerCompat 设置边距。
触摸目标： 确保所有图标按钮尺寸 ≥ 48dp，满足无障碍标准。