Android 主题系统：Material 3、Dynamic Color 与深色模式

Fri, 17 Oct 2025 11:24:19 +0800

主题系统的价值是把颜色、字体、形状和组件默认样式集中管理。Material 3 之后，颜色不再只是主色和强调色，而是一组有语义的 Color Scheme。

核心结论

主题系统解决的是全局视觉一致性，不是单个控件样式。
Material 3 用语义化色彩角色描述 UI，而不是直接到处写颜色值。
Dynamic Color 基于系统壁纸生成色板，适合 Android 12+。
Compose 使用 MaterialTheme，传统 View 使用 XML theme，两者可以共存但要统一设计令牌。
深色模式要关注对比度、语义色和图片资源，不只是反转颜色。

Material Design3(Material You)

核心概念

Material Design3 (MD3)是Google在Android 12+引入的设计系统，核心特性：

Dynamic Color：根据壁纸自动生成主题色
更圆润的组件：更大的圆角半径
色彩角色系统：40+个语义化颜色槽位
个性化：让每个用户的应用看起来独一无二

版本要求

// Material 3
implementation("com.google.android.material:material:1.12.0")

// Compose Material 3
implementation("androidx.compose.material3:material3:1.3.1")

主题系统架构

三层结构

Material Theme (Material 3)
↓
Application Theme (你的应用主题)
↓
Component Styles (组件样式)

色彩角色系统

Material 3 定义了5大色彩组：

1. Primary（主色）

<!-- 最重要的品牌色，用于主要操作 -->
<attr name="colorPrimary" /> <!-- 主色 -->
<attr name="colorOnPrimary" /> <!-- 主色上的文字/图标 -->
<attr name="colorPrimaryContainer" /> <!-- 主色容器 -->
<attr name="colorOnPrimaryContainer" /> <!-- 容器上的内容 -->

2. Secondary(次要色)

<!-- 次要操作，辅助主色 -->
<attr name="colorSecondary" />
<attr name="colorOnSecondary" />
<attr name="colorSecondaryContainer" />
<attr name="colorOnSecondaryContainer" />

3. Tertiary(第三色)

<!-- 用于强调或对比 -->
<attr name="colorTertiary" />
<attr name="colorOnTertiary" />
<attr name="colorTertiaryContainer" />
<attr name="colorOnTertiaryContainer" />

4. Error（错误色）

<!-- 错误状态 -->
<attr name="colorError" />
<attr name="colorOnError" />
<attr name="colorErrorContainer" />
<attr name="colorOnErrorContainer" />

5. Surface & Background(表面和背景)

<!-- 背景和表面 -->
<attr name="colorSurface" /> <!-- 卡片、对话框背景 -->
<attr name="colorOnSurface" /> <!-- 表面上的文字 -->
<attr name="colorSurfaceVariant" /> <!-- 表面变体 -->
<attr name="colorOnSurfaceVariant" /> <!-- 次要文字 -->
<attr name="colorBackground" /> <!-- 应用背景 -->
<attr name="colorOnBackground" /> <!-- 背景上的内容 -->

6. Outline & Other

<!-- 边框和其他 -->
<attr name="colorOutline" /> <!-- 分割线、边框 -->
<attr name="colorOutlineVariant" /> <!-- 更弱的边框 -->
<attr name="colorSurfaceTint" /> <!-- 表面着色（高度感） -->

Dynamic Color (动态配色)

所谓Dynamic Color：Android 12+系统会从用户壁纸提取颜色，生成整套主题色，实现”千人千面“。

实现方式

方式一：使用系统提供的主题

<!-- res/values/themes.xml -->
<resources>
 <!-- Android 12+ 会自动应用 Dynamic Color -->
 <style name="Theme.MyApp" parent="Theme.Material3.DayNight">
 <!-- 可选：覆盖特定颜色 -->
 <item name="colorPrimary">@color/custom_primary</item>
 </style>
</resources>

<!-- res/values-v31/themes.xml (Android 12+ 专用) -->
<resources>
 <!-- 使用 DynamicColors 主题 -->
 <style name="Theme.MyApp" parent="Theme.Material3.DayNight.NoActionBar">
 <!-- 系统自动应用壁纸颜色，无需定义 colorPrimary 等 -->
 </style>
</resources>

方式二：代码启用（更灵活）

// Application 或 Activity
class MyApplication : Application() {
 override fun onCreate() {
 super.onCreate()

 // 全局启用 Dynamic Color
 DynamicColors.applyToActivitiesIfAvailable(this)
 }
}

// 单个 Activity 启用
class MainActivity : AppCompatActivity() {
 override fun onCreate(savedInstanceState: Bundle?) {
 super.onCreate(savedInstanceState)

 // 只在此 Activity 启用
 DynamicColors.applyIfAvailable(this)
 }
}

方式三：提供回退方案

// 支持用户选择是否启用
class MyApplication : Application() {
 override fun onCreate() {
 super.onCreate()

 if (supportsDynamicColor() && userPrefersDynamicColor()) {
 DynamicColors.applyToActivitiesIfAvailable(this)
 }
 }

 private fun supportsDynamicColor(): Boolean {
 return Build.VERSION.SDK_INT >= Build.VERSION_CODES.S // Android 12+
 }
}

自定义Dynamic Color

<!-- 即使启用 Dynamic Color，也可覆盖特定颜色 -->
<style name="Theme.MyApp" parent="Theme.Material3.DayNight">
 <!-- 强制使用品牌色作为 Primary -->
 <item name="colorPrimary">@color/brand_color</item>
 <!-- 其他颜色让系统自动生成 -->
</style>

传统View主题

完整主题配置

<!-- res/values/colors.xml -->
<resources>
 <!-- Light Mode Colors -->
 <color name="md_theme_light_primary">#6750A4</color>
 <color name="md_theme_light_onPrimary">#FFFFFF</color>
 <color name="md_theme_light_primaryContainer">#EADDFF</color>
 <color name="md_theme_light_onPrimaryContainer">#21005D</color>

 <color name="md_theme_light_secondary">#625B71</color>
 <color name="md_theme_light_onSecondary">#FFFFFF</color>
 <color name="md_theme_light_secondaryContainer">#E8DEF8</color>
 <color name="md_theme_light_onSecondaryContainer">#1D192B</color>

 <color name="md_theme_light_surface">#FFFBFE</color>
 <color name="md_theme_light_onSurface">#1C1B1F</color>
 <color name="md_theme_light_background">#FFFBFE</color>

 <!-- Dark Mode Colors -->
 <color name="md_theme_dark_primary">#D0BCFF</color>
 <color name="md_theme_dark_onPrimary">#381E72</color>
 <!-- ... 其他深色模式颜色 -->
</resources>

<!-- res/values/themes.xml -->
<resources>
 <style name="Theme.MyApp" parent="Theme.Material3.DayNight.NoActionBar">
 <!-- Primary -->
 <item name="colorPrimary">@color/md_theme_light_primary</item>
 <item name="colorOnPrimary">@color/md_theme_light_onPrimary</item>
 <item name="colorPrimaryContainer">@color/md_theme_light_primaryContainer</item>
 <item name="colorOnPrimaryContainer">@color/md_theme_light_onPrimaryContainer</item>

 <!-- Secondary -->
 <item name="colorSecondary">@color/md_theme_light_secondary</item>
 <item name="colorOnSecondary">@color/md_theme_light_onSecondary</item>
 <item name="colorSecondaryContainer">@color/md_theme_light_secondaryContainer</item>
 <item name="colorOnSecondaryContainer">@color/md_theme_light_onSecondaryContainer</item>

 <!-- Surface & Background -->
 <item name="colorSurface">@color/md_theme_light_surface</item>
 <item name="colorOnSurface">@color/md_theme_light_onSurface</item>
 <item name="android:colorBackground">@color/md_theme_light_background</item>

 <!-- 状态栏和导航栏 -->
 <item name="android:statusBarColor">@android:color/transparent</item>
 <item name="android:navigationBarColor">@color/md_theme_light_surface</item>
 <item name="android:windowLightStatusBar">true</item>
 <item name="android:windowLightNavigationBar">true</item>

 <!-- 形状（圆角） -->
 <item name="shapeAppearanceSmallComponent">@style/ShapeAppearance.MyApp.SmallComponent</item>
 <item name="shapeAppearanceMediumComponent">@style/ShapeAppearance.MyApp.MediumComponent</item>
 <item name="shapeAppearanceLargeComponent">@style/ShapeAppearance.MyApp.LargeComponent</item>
 </style>

 <!-- 自定义形状 -->
 <style name="ShapeAppearance.MyApp.SmallComponent" parent="ShapeAppearance.Material3.SmallComponent">
 <item name="cornerFamily">rounded</item>
 <item name="cornerSize">8dp</item>
 </style>

 <style name="ShapeAppearance.MyApp.MediumComponent" parent="ShapeAppearance.Material3.MediumComponent">
 <item name="cornerSize">12dp</item>
 </style>

 <style name="ShapeAppearance.MyApp.LargeComponent" parent="ShapeAppearance.Material3.LargeComponent">
 <item name="cornerSize">16dp</item>
 </style>
</resources>

<!-- res/values-night/colors.xml -->
<resources>
 <!-- 深色模式的颜色会自动被使用 -->
 <color name="md_theme_light_primary">@color/md_theme_dark_primary</color>
 <color name="md_theme_light_onPrimary">@color/md_theme_dark_onPrimary</color>
 <!-- ... -->
</resources>

在布局中使用

<!-- res/layout/activity_main.xml -->
<LinearLayout
 android:layout_width="match_parent"
 android:layout_height="match_parent"
 android:background="?attr/colorBackground">

 <!-- 使用主题颜色 -->
 <com.google.android.material.button.MaterialButton
 android:layout_width="wrap_content"
 android:layout_height="wrap_content"
 android:text="Primary Button"
 android:backgroundTint="?attr/colorPrimary"
 android:textColor="?attr/colorOnPrimary" />

 <!-- 次要按钮 -->
 <com.google.android.material.button.MaterialButton
 style="@style/Widget.Material3.Button.TonalButton"
 android:layout_width="wrap_content"
 android:layout_height="wrap_content"
 android:text="Secondary Button" />

 <!-- 卡片使用 Surface 色 -->
 <com.google.android.material.card.MaterialCardView
 android:layout_width="match_parent"
 android:layout_height="wrap_content"
 app:cardBackgroundColor="?attr/colorSurface"
 app:cardElevation="2dp">

 <TextView
 android:layout_width="wrap_content"
 android:layout_height="wrap_content"
 android:text="Card Content"
 android:textColor="?attr/colorOnSurface" />
 </com.google.android.material.card.MaterialCardView>
</LinearLayout>

Compose主题

完整Compose主题实现

// ui/theme/Color.kt
package com.example.myapp.ui.theme

import androidx.compose.ui.graphics.Color

// Light Theme Colors
val md_theme_light_primary = Color(0xFF6750A4)
val md_theme_light_onPrimary = Color(0xFFFFFFFF)
val md_theme_light_primaryContainer = Color(0xFFEADDFF)
val md_theme_light_onPrimaryContainer = Color(0xFF21005D)

val md_theme_light_secondary = Color(0xFF625B71)
val md_theme_light_onSecondary = Color(0xFFFFFFFF)
val md_theme_light_secondaryContainer = Color(0xFFE8DEF8)
val md_theme_light_onSecondaryContainer = Color(0xFF1D192B)

val md_theme_light_surface = Color(0xFFFFFBFE)
val md_theme_light_onSurface = Color(0xFF1C1B1F)
val md_theme_light_background = Color(0xFFFFFBFE)

// Dark Theme Colors
val md_theme_dark_primary = Color(0xFFD0BCFF)
val md_theme_dark_onPrimary = Color(0xFF381E72)
val md_theme_dark_primaryContainer = Color(0xFF4F378B)
val md_theme_dark_onPrimaryContainer = Color(0xFFEADDFF)

val md_theme_dark_secondary = Color(0xFFCCC2DC)
val md_theme_dark_onSecondary = Color(0xFF332D41)
val md_theme_dark_surface = Color(0xFF1C1B1F)
val md_theme_dark_onSurface = Color(0xFFE6E1E5)
val md_theme_dark_background = Color(0xFF1C1B1F)


// ui/theme/Theme.kt
package com.example.myapp.ui.theme

import android.app.Activity
import android.os.Build
import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.material3.*
import androidx.compose.runtime.Composable
import androidx.compose.runtime.SideEffect
import androidx.compose.ui.graphics.toArgb
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.platform.LocalView
import androidx.core.view.WindowCompat

private val LightColorScheme = lightColorScheme(
 primary = md_theme_light_primary,
 onPrimary = md_theme_light_onPrimary,
 primaryContainer = md_theme_light_primaryContainer,
 onPrimaryContainer = md_theme_light_onPrimaryContainer,

 secondary = md_theme_light_secondary,
 onSecondary = md_theme_light_onSecondary,
 secondaryContainer = md_theme_light_secondaryContainer,
 onSecondaryContainer = md_theme_light_onSecondaryContainer,

 surface = md_theme_light_surface,
 onSurface = md_theme_light_onSurface,
 background = md_theme_light_background
)

private val DarkColorScheme = darkColorScheme(
 primary = md_theme_dark_primary,
 onPrimary = md_theme_dark_onPrimary,
 primaryContainer = md_theme_dark_primaryContainer,
 onPrimaryContainer = md_theme_dark_onPrimaryContainer,

 secondary = md_theme_dark_secondary,
 onSecondary = md_theme_dark_onSecondary,
 surface = md_theme_dark_surface,
 onSurface = md_theme_dark_onSurface,
 background = md_theme_dark_background
)

@Composable
fun MyAppTheme(
 darkTheme: Boolean = isSystemInDarkTheme(),
 // 启用 Dynamic Color（Android 12+）
 dynamicColor: Boolean = true,
 content: @Composable () -> Unit
) {
 val colorScheme = when {
 // Android 12+ 支持 Dynamic Color
 dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
 val context = LocalContext.current
 if (darkTheme) dynamicDarkColorScheme(context)
 else dynamicLightColorScheme(context)
 }
 // 回退到静态主题
 darkTheme -> DarkColorScheme
 else -> LightColorScheme
 }

 // 设置状态栏颜色
 val view = LocalView.current
 if (!view.isInEditMode) {
 SideEffect {
 val window = (view.context as Activity).window
 window.statusBarColor = colorScheme.primary.toArgb()
 WindowCompat.getInsetsController(window, view).isAppearanceLightStatusBars = !darkTheme
 }
 }

 MaterialTheme(
 colorScheme = colorScheme,
 typography = Typography,
 content = content
 )
}


// ui/theme/Type.kt
package com.example.myapp.ui.theme

import androidx.compose.material3.Typography
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.sp

val Typography = Typography(
 bodyLarge = TextStyle(
 fontFamily = FontFamily.Default,
 fontWeight = FontWeight.Normal,
 fontSize = 16.sp,
 lineHeight = 24.sp,
 letterSpacing = 0.5.sp
 ),
 titleLarge = TextStyle(
 fontFamily = FontFamily.Default,
 fontWeight = FontWeight.Normal,
 fontSize = 22.sp,
 lineHeight = 28.sp,
 letterSpacing = 0.sp
 ),
 labelSmall = TextStyle(
 fontFamily = FontFamily.Default,
 fontWeight = FontWeight.Medium,
 fontSize = 11.sp,
 lineHeight = 16.sp,
 letterSpacing = 0.5.sp
 )
)


// MainActivity.kt
class MainActivity : ComponentActivity() {
 override fun onCreate(savedInstanceState: Bundle?) {
 super.onCreate(savedInstanceState)
 setContent {
 MyAppTheme {
 Surface(
 modifier = Modifier.fillMaxSize(),
 color = MaterialTheme.colorScheme.background
 ) {
 AppContent()
 }
 }
 }
 }
}

@Composable
fun AppContent() {
 Column(
 modifier = Modifier
 .fillMaxSize()
 .padding(16.dp)
 ) {
 // 使用主题颜色
 Button(
 onClick = { },
 colors = ButtonDefaults.buttonColors(
 containerColor = MaterialTheme.colorScheme.primary,
 contentColor = MaterialTheme.colorScheme.onPrimary
 )
 ) {
 Text("Primary Button")
 }

 // 使用 Surface 卡片
 Card(
 modifier = Modifier
 .fillMaxWidth()
 .padding(top = 16.dp),
 colors = CardDefaults.cardColors(
 containerColor = MaterialTheme.colorScheme.surfaceVariant
 )
 ) {
 Text(
 text = "Card Content",
 style = MaterialTheme.typography.bodyLarge,
 color = MaterialTheme.colorScheme.onSurfaceVariant,
 modifier = Modifier.padding(16.dp)
 )
 }
 }
}

深色模式

完整实现方法

1.系统跟随

// 使用 DayNight 主题
<style name="Theme.MyApp" parent="Theme.Material3.DayNight">
 <!-- 自动根据系统设置切换 -->
</style>

2. 手动切换

// 提供用户选择
class SettingsActivity : AppCompatActivity() {
 override fun onCreate(savedInstanceState: Bundle?) {
 super.onCreate(savedInstanceState)

 // 获取当前模式
 val currentMode = AppCompatDelegate.getDefaultNightMode()

 // 切换模式
 when (userSelection) {
 "light" -> AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
 "dark" -> AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
 "system" -> AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM)
 }
 }
}

// Compose 中切换
@Composable
fun ThemeSettings() {
 var darkMode by remember { mutableStateOf(false) }

 MyAppTheme(darkTheme = darkMode) {
 Switch(
 checked = darkMode,
 onCheckedChange = { darkMode = it }
 )
 }
}

3. 深色模式注意事项

<!-- 为深色模式提供专用资源 -->
<!-- res/values-night/colors.xml -->
<color name="window_background">#121212</color>

<!-- res/drawable-night/ic_logo.xml -->
<!-- 深色模式下使用不同的图标 -->

<!-- res/values-night/themes.xml -->
<style name="Theme.MyApp" parent="Theme.Material3.DayNight">
 <item name="android:windowLightStatusBar">false</item>
</style>

最佳实践

1. 使用Material 3

// ✅ 使用 M3
 implementation("com.google.android.material:material:1.12.0")
 parent="Theme.Material3.DayNight"

 // ❌ 不要用旧版本
 parent="Theme.MaterialComponents.DayNight"

2. 启用Dynamic Color

// ✅ 让应用更个性化
 DynamicColors.applyToActivitiesIfAvailable(this)

3. 使用语义化颜色

// ✅ 使用主题属性
 android:textColor="?attr/colorOnSurface"

 // ❌ 不要硬编码
 android:textColor="#000000"

4. 提供深色模式

// ✅ 支持系统深色模式
 parent="Theme.Material3.DayNight"

 // ❌ 只支持亮色
 parent="Theme.Material3.Light"

Material Design on zed的博客