最小必要顏色配置

<!-- res/values/themes.xml -->
<style name="Theme.MyApp" parent="Theme.Material3.DayNight"><!-- 基礎三原色 --><item name="colorPrimary">@color/purple_500</item><item name="colorSecondary">@color/teal_200</item><item name="colorTertiary">@color/orange_200</item><!-- 背景+文字 --><item name="colorSurface">@color/white</item><item name="colorOnSurface">@color/black</item>
</style>

對應效果：

• 按鈕/導航欄：紫色
• 開關/復選框：水綠色
• 懸浮按鈕：橙色容器
• 背景：白色
• 文字：黑色

基礎控件顏色映射

控件	使用的顏色屬性
按鈕	colorPrimary + colorOnPrimary
開關	colorSecondary
卡片	colorSurface
文本	colorOnSurface

XML 和 Compose 雙版本的完整代碼注釋，按功能模塊劃分：

---

一、基礎顏色配置

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

<!-- 主品牌色：用于FAB、主要按鈕等 -->
<item name="colorPrimary">@color/purple_500</item><!-- 主色上的內容色：確保與主色有足夠對比度 -->
<item name="colorOnPrimary">@color/white</item><!-- 次要品牌色：用于開關、單選按鈕等 -->
<item name="colorSecondary">@color/teal_200</item><!-- 背景系統：頁面基礎背景 -->
<item name="colorSurface">@color/white</item><!-- 背景上的內容色：普通文本顏色 -->
<item name="colorOnSurface">@color/black</item><!-- 錯誤色：錯誤提示文本/邊框 -->
<item name="colorError">@color/red_500</item>

2. Compose 版本 (Theme.kt)

val LightColorScheme = lightColorScheme(// 主色容器：FAB背景色primary = Color(0xFF6750A4),// 主色上的內容：FAB圖標顏色onPrimary = Color(0xFFFFFFFF),// 次要色：Switch滑塊顏色secondary = Color(0xFF958DA5),// 背景色：頁面底色surface = Color(0xFFFFFBFE),// 背景上的內容：普通文本onSurface = Color(0xFF1C1B1F),// 錯誤色error = Color(0xFFB3261E)
)

---

二、控件顏色映射

1. 按鈕 (Button)

<!-- XML版 -->
<Buttonandroid:backgroundTint="?attr/colorPrimary"android:textColor="?attr/colorOnPrimary"/>

// Compose版
Button(colors = ButtonDefaults.buttonColors(containerColor = MaterialTheme.colorScheme.primary,contentColor = MaterialTheme.colorScheme.onPrimary,// 禁用狀態顏色（自動降低透明度）disabledContainerColor = MaterialTheme.colorScheme.surfaceVariant,disabledContentColor = MaterialTheme.colorScheme.onSurfaceVariant)
) { Text("按鈕") }

2. 卡片 (Card)

<!-- XML版 -->
<androidx.cardview.widget.CardViewapp:cardBackgroundColor="?attr/colorSurface"app:strokeColor="?attr/colorOutline">

// Compose版
Card(colors = CardDefaults.cardColors(containerColor = MaterialTheme.colorScheme.surface,contentColor = MaterialTheme.colorScheme.onSurface),border = CardDefaults.outlinedCardBorder(borderColor = MaterialTheme.colorScheme.outline)
) { /* 內容 */ }

3. 開關 (Switch)

<!-- XML版 -->
<Switchandroid:trackTint="?attr/colorSecondaryContainer"android:thumbTint="?attr/colorOnSecondary"/>

// Compose版
Switch(colors = SwitchDefaults.colors(checkedThumbColor = MaterialTheme.colorScheme.onSecondary,checkedTrackColor = MaterialTheme.colorScheme.secondary,uncheckedThumbColor = MaterialTheme.colorScheme.surfaceVariant,uncheckedTrackColor = MaterialTheme.colorScheme.onSurfaceVariant)
)

---

三、深色模式適配

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

<style name="Theme.MyApp" parent="Theme.Material3.DayNight"><!-- 深色背景 --><item name="colorSurface">@color/dark_surface</item><!-- 深色文字 --><item name="colorOnSurface">@color/dark_on_surface</item><!-- 深色輪廓線 --><item name="colorOutline">@color/dark_outline</item>
</style>

2. Compose 配置

val DarkColorScheme = darkColorScheme(surface = Color(0xFF1C1B1F),onSurface = Color(0xFFE6E1E5),outline = Color(0xFF938F99)
)@Composable
fun MyAppTheme(darkTheme: Boolean = isSystemInDarkTheme(),content: @Composable () -> Unit
) {val colorScheme = if (darkTheme) DarkColorScheme else LightColorSchemeMaterialTheme(colorScheme = colorScheme,content = content)
}

---

四、動態顏色（Android 12+）

1. XML 配置

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

2. Compose 集成

@Composable
fun DynamicColorWrapper(content: @Composable () -> Unit) {val context = LocalContext.currentval dynamicColor = Build.VERSION.SDK_INT >= Build.VERSION_CODES.Sif (dynamicColor) {DynamicColors.rememberDynamicColors().apply {if (isDynamicColorAvailable) {LaunchedEffect(key1 = colorScheme) {// 動態顏色應用后的回調}}}}content()
}

---

五、完整主題構建示例

XML 全量配置

<style name="Theme.MyApp" parent="Theme.Material3.DayNight"><!-- 主色系 --><item name="colorPrimary">@color/primary_500</item><item name="colorOnPrimary">@color/white</item><item name="colorPrimaryContainer">@color/primary_100</item><!-- 文字系統 --><item name="textColorPrimary">?attr/colorOnSurface</item><item name="textColorSecondary">?attr/colorOnSurfaceVariant</item><!-- 控件狀態 --><item name="colorControlNormal">?attr/colorOnSurface</item><item name="colorControlActivated">?attr/colorPrimary</item>
</style>

Compose 全量主題

private val Typography = Typography(// 標題文字樣式titleLarge = TextStyle(fontFamily = FontFamily.Default,fontWeight = FontWeight.Bold,fontSize = 22.sp,color = MaterialTheme.colorScheme.onSurface),// 正文樣式bodyMedium = TextStyle(fontFamily = FontFamily.Default,fontWeight = FontWeight.Normal,fontSize = 16.sp,color = MaterialTheme.colorScheme.onSurface)
)@Composable
fun MyAppTheme(content: @Composable () -> Unit) {MaterialTheme(colorScheme = if (isDarkTheme()) DarkColorScheme else LightColorScheme,typography = Typography,shapes = Shapes(),content = content)
}

---

關鍵注意事項

1. XML 與 Compose 混用場景：

   // 在Compose中使用XML定義的顏色
   val color = Color(ContextCompat.getColor(context, R.color.primary_500))
   

2. 顏色覆蓋優先級：

   控件直接設置 > 樣式定義 > 主題默認值
   

3. 調試命令：

   # 查看當前主題屬性
   adb shell dumpsys activity top | grep "mTheme"