Android 平台设计指南 — Material Design 3
1. Material You 与主题化 [关键]
1.1 动态颜色
启用从用户壁纸派生的动态颜色。动态颜色是 Android 12+ 的默认设置,应作为主要的主题化策略。
// Compose:动态颜色主题
@Composable
fun AppTheme(
darkTheme: Boolean = isSystemInDarkTheme(),
dynamicColor: Boolean = true,
content: @Composable () -> Unit
) {
val colorScheme = when {
dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
val context = LocalContext.current
if (darkTheme) dynamicDarkColorScheme(context)
else dynamicLightColorScheme(context)
}
darkTheme -> darkColorScheme()
else -> lightColorScheme()
}
MaterialTheme(
colorScheme = colorScheme,
typography = AppTypography,
content = content
)
}
<!-- XML:themes.xml 中的动态颜色 -->
<style name="Theme.App" parent="Theme.Material3.DayNight.NoActionBar">
<item name="dynamicColorThemeOverlay">@style/ThemeOverlay.Material3.DynamicColors.DayNight</item>
</style>
规则:
- R1.1:始终为低于 Android 12 的设备提供静态颜色方案的降级方案。
- R1.2:切勿在组件中硬编码颜色十六进制值。始终从主题中引用颜色角色。
- R1.3:用至少 3 种不同的壁纸进行测试,以验证动态颜色的和谐性。
1.2 色彩角色
Material 3 定义了一组结构化的色彩角色。根据语义使用它们,而不是基于美观。
| 角色 | 用途 | 角色上颜色 |
|---|---|---|
primary | 关键操作、激活状态、FAB | onPrimary |
primaryContainer | 较不突出的主要元素 | onPrimaryContainer |
secondary | 辅助 UI、过滤芯片 | onSecondary |
secondaryContainer | 导航栏激活指示器 | onSecondaryContainer |
tertiary | 强调、对比、互补 | onTertiary |
tertiaryContainer | 输入字段、较不突出的强调色 | onTertiaryContainer |
surface | 背景、卡片、面板 | onSurface |
surfaceVariant | 装饰性元素、分隔线 | onSurfaceVariant |
error | 错误状态、破坏性操作 | onError |
errorContainer | 错误背景 | onErrorContainer |
outline | 边框、分隔线 | — |
outlineVariant | 微妙边框 | — |
inverseSurface | Snackbar 背景 | inverseOnSurface |
// 正确:语义化的色彩角色
Text(
text = "错误消息",
color = MaterialTheme.colorScheme.error
)
Surface(color = MaterialTheme.colorScheme.errorContainer) {
Text(text = "错误详情", color = MaterialTheme.colorScheme.onErrorContainer)
}
// 错误:硬编码颜色
Text(text = "错误", color = Color(0xFFB00020)) // 反模式
规则:
- R1.4:每个前景元素必须为其背景使用匹配的
on颜色角色(例如,primary背景上的onPrimary文本)。 - R1.5:使用
surface及其变体作为背景。切勿将primary或secondary用作大的背景区域。 - R1.6:有节制地使用
tertiary,仅用于强调和互补对比。
1.3 明亮与暗黑主题
支持明亮和暗黑两种主题。默认尊重系统设置。
// Compose:检测系统主题
val darkTheme = isSystemInDarkTheme()
规则:
- R1.7:始终同时支持明亮和暗黑主题。切勿仅发布明亮主题。
- R1.8:暗黑主题的表面使用基于高度的色调映射,而不是纯黑色 (#000000)。使用
surface颜色角色,它会自动处理此问题。 - R1.9:在应用设置中提供手动主题覆盖(系统 / 明亮 / 暗黑)。
1.4 自定义颜色种子
当品牌需要自定义颜色时,提供种子颜色并使用 Material Theme Builder 生成色调调色板。
// 使用品牌种子的自定义颜色方案
private val BrandLightColorScheme = lightColorScheme(
primary = Color(0xFF1B6D2F),
onPrimary = Color(0xFFFFFFFF),
primaryContainer = Color(0xFFA4F6A8),
onPrimaryContainer = Color(0xFF002107),
// ... 从种子生成完整调色板
)
规则:
- R1.10:使用 Material Theme Builder 从种子颜色生成色调调色板。切勿手动选择单个色调。
- R1.11:使用自定义颜色时,仍应将动态颜色作为默认值,并将自定义颜色作为降级方案。
2. 导航 [关键]
2.1 导航栏(底部)
适用于 3-5 个顶级目标页面的手机主要导航模式。
// Compose:导航栏
NavigationBar {
items.forEachIndexed { index, item ->
NavigationBarItem(
icon = {
Icon(
imageVector = if (selectedItem == index) item.filledIcon else item.outlinedIcon,
contentDescription = item.label
)
},
label = { Text(item.label) },
selected = selectedItem == index,
onClick = { selectedItem = index }
)
}
}
规则:
- R2.1:在紧凑屏幕上为 3-5 个顶级目标页面使用导航栏。切勿用于少于 3 个或多于 5 个。
- R2.2:始终在导航栏项上显示标签。不允许仅图标的导航栏。
- R2.3:选中状态使用填充图标,未选中状态使用轮廓图标。
- R2.4:活动指示器使用
secondaryContainer颜色。请勿覆盖。
2.2 导航导轨
适用于中号和展开屏幕(平板电脑、折叠设备、桌面)。
// Compose:针对大屏幕的导航导轨
NavigationRail(
header = {
FloatingActionButton(
onClick = { /* 主要操作 */ },
containerColor = MaterialTheme.colorScheme.tertiaryContainer
) {
Icon(Icons.Default.Add, contentDescription = "创建")
}
}
) {
items.forEachIndexed { index, item ->
NavigationRailItem(
icon = { Icon(item.icon, contentDescription = item.label) },
label = { Text(item.label) },
selected = selectedItem == index,
onClick = { selectedItem = index }
)
}
}
规则:
- R2.5:在中 (600-839dp) 和展开 (840dp+) 窗口大小时使用导航导轨。在紧凑屏幕上与导航栏配对使用。
- R2.6:可选择在导轨头部包含一个 FAB 用于主要操作。
- R2.7:导轨上的标签是可选的,但为了清晰起见推荐使用。
2.3 导航抽屉
适用于 5+ 个目标页面或复杂的导航层级,通常在展开屏幕上使用。
// Compose:针对大屏幕的永久导航抽屉
PermanentNavigationDrawer(
drawerContent = {
PermanentDrawerSheet {
Text("应用名称", modifier = Modifier.padding(16.dp),
style = MaterialTheme.typography.titleMedium)
HorizontalDivider()
items.forEach { item ->
NavigationDrawerItem(
label = { Text(item.label) },
selected = item == selectedItem,
onClick = { selectedItem = item },
icon = { Icon(item.icon, contentDescription = null) }
)
}
}
}
) {
Scaffold { /* 页面内容 */ }
}
规则:
- R2.8:在紧凑屏幕上使用模态抽屉,在展开屏幕上使用永久抽屉。
- R2.9:将抽屉项分组为带有分隔线和节标题的部分。
2.4 预测性返回手势
Android 13+ 支持带有动画预览的预测性返回。
// Compose:使用 BackHandler 的预测性返回 (androidx.activity.compose)
BackHandler(enabled = true) {
// 当返回被确认时调用;在导航控制器中返回上一级
navController.popBackStack()
}
// Compose:使用 predictiveBackHandler 修饰符的预测性返回进度动画
// (androidx.activity:activity-compose 1.8+)
Modifier.predictiveBackHandler(enabled = true) { progress ->
// progress 是一个 Flow<BackEventCompat>,包含 x, y, swipeEdge, progress (0.0–1.0)
progress.collect { backEvent ->
animationState = backEvent.progress
}
}
<!-- AndroidManifest.xml:选择启用预测性返回 -->
<application android:enableOnBackInvokedCallback="true">
规则:
- R2.10:在清单中选择启用预测性返回。在 Compose 应用中,使用
BackHandler(来自androidx.activity.compose)拦截返回事件。在 基于 View 的应用中,实现OnBackInvokedCallback(API 33+)或OnBackPressedCallback(AndroidX),而不是重写onBackPressed()。 - R2.11:系统返回手势在导航堆栈中返回。向上按钮(工具栏箭头)在应用层级中向上导航。这两者可能不同。
- R2.12:除非有未保存的用户输入,否则切勿拦截系统返回以显示“你确定吗?”对话框。
- R2.13:不要压制系统提供的返回预览动画。如果实现了自定义进入/退出过渡,请使用
BackEventCompat.progress(0.0–1.0) 进行插值,并尊重BackEventCompat.swipeEdge(EDGE_LEFT/EDGE_RIGHT),以便退出屏幕按比例缩小并向触发边缘移动,与系统动画匹配。 - R2.14:优先识别而非回忆。保持目标页面有标签、选中状态可见、返回堆栈上下文保留,以便用户在每次导航步骤后不必重新构建他们所在的位置。
// Compose:根据预测性返回进度驱动自定义动画
Modifier.predictiveBackHandler(enabled = true) { progress ->
progress.collect { backEvent ->
// backEvent.progress: 0.0 (手势开始) → 1.0 (确认)
// backEvent.swipeEdge: BackEventCompat.EDGE_LEFT 或 EDGE_RIGHT
exitScale = 1f - (backEvent.progress * 0.1f)
exitOffsetX = if (backEvent.swipeEdge == BackEventCompat.EDGE_LEFT) -backEvent.progress * 32.dp.toPx() else backEvent.progress * 32.dp.toPx()
}
}
2.5 导航组件选择
| 屏幕尺寸 | 3-5 个目标页面 | 5+ 个目标页面 |
|---|---|---|
| 紧凑 (< 600dp) | 导航栏 | 模态抽屉 + 导航栏 |
| 中 (600-839dp) | 导航导轨 | 模态抽屉 + 导航导轨 |
| 展开 (840dp+) | 导航导轨 | 永久抽屉 |
3. 布局与响应式 [高优先级]
3.1 窗口尺寸类
使用窗口尺寸类进行自适应布局,而不是原始像素断点。
// Compose:窗口尺寸类
val windowSizeClass = calculateWindowSizeClass(this)
when (windowSizeClass.widthSizeClass) {
WindowWidthSizeClass.Compact -> CompactLayout()
WindowWidthSizeClass.Medium -> MediumLayout()
WindowWidthSizeClass.Expanded -> ExpandedLayout()
}
| 类 | 宽度 | 典型设备 | 列数 |
|---|---|---|---|
| 紧凑 | < 600dp | 手机竖屏 | 4 |
| 中 | 600-839dp | 平板竖屏、折叠设备 | 8 |
| 展开 | 840dp+ | 平板横屏、桌面 | 12 |
规则:
- R3.1:始终使用
material3-window-size-class中的WindowSizeClass进行响应式布局决策。 - R3.2:切勿使用固定像素断点。设备类别是流动的。
- R3.3:支持所有三种宽度尺寸类。至少支持紧凑和展开。
3.2 Material 网格
应用规范的 Material 网格边距和间距。
| 尺寸类 | 边距 | 间距 | 列数 |
|---|---|---|---|
| 紧凑 | 16dp | 8dp | 4 |
| 中 | 24dp | 16dp | 8 |
| 展开 | 24dp | 24dp | 12 |
规则:
- R3.4:在展开屏幕上,内容不应跨越整个宽度。使用约 840dp 的最大内容宽度或列表-详情布局。
- R3.5:应用与网格规格一致的水平边距。
3.3 边缘到边缘显示
Android 15+ 强制要求边缘到边缘。所有应用应绘制在系统栏后面。
// Compose:边缘到边缘设置
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
enableEdgeToEdge()
super.onCreate(savedInstanceState)
setContent {
Scaffold(
modifier = Modifier.fillMaxSize(),
// Scaffold 自动处理顶部/底部栏的内边距
) { innerPadding ->
Content(modifier = Modifier.padding(innerPadding))
}
}
}
}
规则:
- R3.6:在
setContent之前调用enableEdgeToEdge()。在状态栏和导航栏后面绘制。 - R3.7:使用
WindowInsets将内容与系统栏隔开。Scaffold会自动处理顶部栏和底部栏内容的内边距。 - R3.8:可滚动内容应在透明系统栏后面滚动,并在列表顶部和底部添加适当的内边距。
3.4 可折叠设备支持
// Compose:检测折叠姿态
val foldingFeatures = WindowInfoTracker.getOrCreate(context)
.windowLayoutInfo(context)
.collectAsState(initial = WindowLayoutInfo(emptyList()))
规则:
- R3.9:检测铰链/折叠位置,避免将关键内容放置在折叠处。
- R3.10:使用来自 Material3 自适应库的
ListDetailPaneScaffold或SupportingPaneScaffold进行可折叠感知布局。
4. 排版 [高优先级]
4.1 Material 字体类型比例
| 角色 | 默认大小 | 默认字重 | 用途 |
|---|---|---|---|
| displayLarge | 57sp | 400 | 英雄文本、引导页 |
| displayMedium | 45sp | 400 | 大号功能文本 |
| displaySmall | 36sp | 400 | 突出的展示文本 |
| headlineLarge | 32sp | 400 | 屏幕标题 |
| headlineMedium | 28sp | 400 | 章节标题 |
| headlineSmall | 24sp | 400 | 卡片标题 |
| titleLarge | 22sp | 400 | 顶部应用栏标题 |
| titleMedium | 16sp | 500 | 标签页、导航 |
| titleSmall | 14sp | 500 | 副标题 |
| bodyLarge | 16sp | 400 | 主要正文文本 |
| bodyMedium | 14sp | 400 | 次要正文文本 |
| bodySmall | 12sp | 400 | 说明文字 |
| labelLarge | 14sp | 500 | 按钮、突出标签 |
| labelMedium | 12sp | 500 | 芯片 |