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:在 Manifest 中選擇啟用預測性返回。在 Compose 應用程式中,使用
BackHandler(來自androidx.activity.compose)來攔截返回事件。在 View-based 應用程式中,實作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 | 晶片 |
[其餘內容已截斷,等待翻譯]