Android Material Design 3 主题配色终极指南：XML 与 Compose 全解析 ...

最小必要颜色配置

1. <!-- res/values/themes.xml -->
2. <style name="Theme.MyApp" parent="Theme.Material3.DayNight">
3.     <!-- 基础三原色 -->
4.     <item name="colorPrimary">@color/purple_500</item>
5.     <item name="colorSecondary">@color/teal_200</item>
6.     <item name="colorTertiary">@color/orange_200</item>
7.    
8.     <!-- 背景+文字 -->
9.     <item name="colorSurface">@color/white</item>
10.     <item name="colorOnSurface">@color/black</item>
11. </style>

复制代码

对应效果：

• 按钮/导航栏：紫色
  
• 开关/复选框：水绿色
  
• 悬浮按钮：橙色容器
  
• 背景：白色
  
• 文字：黑色
  

基础控件颜色映射

控件使用的颜色属性按钮colorPrimary + colorOnPrimary开关colorSecondary卡片colorSurface文本colorOnSurface XML 和 Compose 双版本的完备代码解释，按功能模块划分：

---

一、基础颜色配置

1. XML 版本 (res/values/themes.xml)

1. <!-- 主品牌色：用于FAB、主要按钮等 -->
2. <item name="colorPrimary">@color/purple_500</item>
4. <!-- 主色上的内容色：确保与主色有足够对比度 -->
5. <item name="colorOnPrimary">@color/white</item>
7. <!-- 次要品牌色：用于开关、单选按钮等 -->
8. <item name="colorSecondary">@color/teal_200</item>
10. <!-- 背景系统：页面基础背景 -->
11. <item name="colorSurface">@color/white</item>
13. <!-- 背景上的内容色：普通文本颜色 -->
14. <item name="colorOnSurface">@color/black</item>
16. <!-- 错误色：错误提示文本/边框 -->
17. <item name="colorError">@color/red_500</item>

复制代码

2. Compose 版本 (Theme.kt)

1. val LightColorScheme = lightColorScheme(
2.     // 主色容器：FAB背景色
3.     primary = Color(0xFF6750A4),
4.     // 主色上的内容：FAB图标颜色
5.     onPrimary = Color(0xFFFFFFFF),
6.     // 次要色：Switch滑块颜色
7.     secondary = Color(0xFF958DA5),
8.     // 背景色：页面底色
9.     surface = Color(0xFFFFFBFE),
10.     // 背景上的内容：普通文本
11.     onSurface = Color(0xFF1C1B1F),
12.     // 错误色
13.     error = Color(0xFFB3261E)
14. )

复制代码

---

二、控件颜色映射

1. 按钮 (Button)

1. <!-- XML版 -->
2. <Button
3.     android:backgroundTint="?attr/colorPrimary"
4.     android:textColor="?attr/colorOnPrimary"/>

复制代码

1. // Compose版
2. Button(
3.     colors = ButtonDefaults.buttonColors(
4.         containerColor = MaterialTheme.colorScheme.primary,
5.         contentColor = MaterialTheme.colorScheme.onPrimary,
6.         // 禁用状态颜色（自动降低透明度）
7.         disabledContainerColor = MaterialTheme.colorScheme.surfaceVariant,
8.         disabledContentColor = MaterialTheme.colorScheme.onSurfaceVariant
9.     )
10. ) { Text("按钮") }

复制代码

2. 卡片 (Card)

1. <!-- XML版 -->
2. <androidx.cardview.widget.CardView
3.     app:cardBackgroundColor="?attr/colorSurface"
4.     app:strokeColor="?attr/colorOutline">

复制代码

1. // Compose版
2. Card(
3.     colors = CardDefaults.cardColors(
4.         containerColor = MaterialTheme.colorScheme.surface,
5.         contentColor = MaterialTheme.colorScheme.onSurface
6.     ),
7.     border = CardDefaults.outlinedCardBorder(
8.         borderColor = MaterialTheme.colorScheme.outline
9.     )
10. ) { /* 内容 */ }

复制代码

3. 开关 (Switch)

1. <!-- XML版 -->
2. <Switch
3.     android:trackTint="?attr/colorSecondaryContainer"
4.     android:thumbTint="?attr/colorOnSecondary"/>

复制代码

1. // Compose版
2. Switch(
3.     colors = SwitchDefaults.colors(
4.         checkedThumbColor = MaterialTheme.colorScheme.onSecondary,
5.         checkedTrackColor = MaterialTheme.colorScheme.secondary,
6.         uncheckedThumbColor = MaterialTheme.colorScheme.surfaceVariant,
7.         uncheckedTrackColor = MaterialTheme.colorScheme.onSurfaceVariant
8.     )
9. )

复制代码

---

三、深色模式适配

1. XML 配置 (res/values-night/themes.xml)

1. <style name="Theme.MyApp" parent="Theme.Material3.DayNight">
2.     <!-- 深色背景 -->
3.     <item name="colorSurface">@color/dark_surface</item>
4.     <!-- 深色文字 -->
5.     <item name="colorOnSurface">@color/dark_on_surface</item>
6.     <!-- 深色轮廓线 -->
7.     <item name="colorOutline">@color/dark_outline</item>
8. </style>

复制代码

2. Compose 配置

1. val DarkColorScheme = darkColorScheme(
2.     surface = Color(0xFF1C1B1F),
3.     onSurface = Color(0xFFE6E1E5),
4.     outline = Color(0xFF938F99)
5. )
7. @Composable
8. fun MyAppTheme(
9.     darkTheme: Boolean = isSystemInDarkTheme(),
10.     content: @Composable () -> Unit
11. ) {
12.     val colorScheme = if (darkTheme) DarkColorScheme else LightColorScheme
13.     MaterialTheme(
14.         colorScheme = colorScheme,
15.         content = content
16.     )
17. }

复制代码

---

四、动态颜色（Android 12+）

1. XML 配置

1. <!-- res/values-v31/themes.xml -->
2. <style name="Theme.MyApp" parent="Theme.Material3.DayNight.DynamicColors">
3.     <item name="android:dynamicColorThemeOverlay">
4.         @style/ThemeOverlay.App.Dynamic
5.     </item>
6. </style>

复制代码

2. Compose 集成

1. @Composable
2. fun DynamicColorWrapper(content: @Composable () -> Unit) {
3.     val context = LocalContext.current
4.     val dynamicColor = Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
5.    
6.     if (dynamicColor) {
7.         DynamicColors.rememberDynamicColors().apply {
8.             if (isDynamicColorAvailable) {
9.                 LaunchedEffect(key1 = colorScheme) {
10.                     // 动态颜色应用后的回调
11.                 }
12.             }
13.         }
14.     }
15.     content()
16. }

复制代码

---

五、完备主题构建示例

XML 全量配置

1. <style name="Theme.MyApp" parent="Theme.Material3.DayNight">
2.     <!-- 主色系 -->
3.     <item name="colorPrimary">@color/primary_500</item>
4.     <item name="colorOnPrimary">@color/white</item>
5.     <item name="colorPrimaryContainer">@color/primary_100</item>
6.    
7.     <!-- 文字系统 -->
8.     <item name="textColorPrimary">?attr/colorOnSurface</item>
9.     <item name="textColorSecondary">?attr/colorOnSurfaceVariant</item>
10.    
11.     <!-- 控件状态 -->
12.     <item name="colorControlNormal">?attr/colorOnSurface</item>
13.     <item name="colorControlActivated">?attr/colorPrimary</item>
14. </style>

复制代码

Compose 全量主题

1. private val Typography = Typography(
2.     // 标题文字样式
3.     titleLarge = TextStyle(
4.         fontFamily = FontFamily.Default,
5.         fontWeight = FontWeight.Bold,
6.         fontSize = 22.sp,
7.         color = MaterialTheme.colorScheme.onSurface
8.     ),
9.     // 正文样式
10.     bodyMedium = TextStyle(
11.         fontFamily = FontFamily.Default,
12.         fontWeight = FontWeight.Normal,
13.         fontSize = 16.sp,
14.         color = MaterialTheme.colorScheme.onSurface
15.     )
16. )
18. @Composable
19. fun MyAppTheme(content: @Composable () -> Unit) {
20.     MaterialTheme(
21.         colorScheme = if (isDarkTheme()) DarkColorScheme else LightColorScheme,
22.         typography = Typography,
23.         shapes = Shapes(),
24.         content = content
25.     )
26. }

复制代码

---

关键注意事项

• XML 与 Compose 混用场景：
  
  1. // 在Compose中使用XML定义的颜色
  2. val color = Color(ContextCompat.getColor(context, R.color.primary_500))

  复制代码
• 颜色覆盖优先级：
  
  1. 控件直接设置 > 样式定义 > 主题默认值

  复制代码
• 调试命令：
  
  1. # 查看当前主题属性
  2. adb shell dumpsys activity top | grep "mTheme"

  复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。