SimpMusic Material Design 3 主题实战:动态配色、类型比例与 KMP 跨平台实现
SimpMusic Material Design 3 主题实战:动态配色、类型比例与 KMP 跨平台实现
本篇围绕 Material Design 3(Material You)主题系统展开,覆盖颜色系统、排版、形状、高程与响应式布局五大组成部分,并以 SimpMusic(一个基于 YouTube Music 后端的跨平台音乐应用)的 Compose Multiplatform 源码为实证:读完你将掌握如何为 Compose 应用搭建完整的 M3 主题层——从 Android 12+ 壁纸动态取色、种子色运行时生成调色板,到跨平台的 expect/actual 主题编排,以及平板/折叠屏的自适应断点方案。
SimpMusic 仓库中对应的主题代码集中在 Theme.kt、Color.kt 与 Typo.kt 三个文件中;本文先按标准 M3 主题文档给出完整规范与参考实现,再逐节对照仓库源码说明实际落地方式与取舍。
一、颜色系统
1.1 动态颜色(Material You)
Material You 的核心理念是"个性化":在 Android 12(Build.VERSION_CODES.S)及以上设备上,直接从用户壁纸提取配色并生成整套 ColorScheme,无需手工维护色板。标准的 AppTheme 写法如下:
@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,
shapes = AppShapes,
content = content
)
}
关键约束有两个:
- 版本门槛:
dynamicDarkColorScheme/dynamicLightColorScheme只在 API 31+ 可用,因此必须用Build.VERSION.SDK_INT >= Build.VERSION_CODES.S守卫,低版本回退到静态色板; - 作用域:动态色只影响 Compose 内容层,状态栏/导航栏图标颜色仍需在 Window 层同步处理。
SimpMusic 中该模式被重构为 KMP 的 expect/actual 结构,以便同一套主题代码在 Android 与 Desktop 上复用。声明位于 PlatformColorScheme.kt:
expect fun platformDynamicColorScheme(isDark: Boolean): ColorScheme?
Android 侧实现在 PlatformColorScheme.android.kt:
@Composable
actual fun platformDynamicColorScheme(isDark: Boolean): ColorScheme? {
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.S) return null
val context = LocalContext.current
return if (isDark) {
// Keep the OLED look: pin background/surface to pure black like the seed scheme.
dynamicDarkColorScheme(context).copy(
background = Color.Black,
surface = Color.Black,
)
} else {
dynamicLightColorScheme(context)
}
}
actual fun isWallpaperDynamicColorSupported(): Boolean =
Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
两处工程化细节值得注意:
- 动态深色仍钉住纯黑:壁纸取色得到的中性面偏灰,应用用
.copy(background = Color.Black, surface = Color.Black)把 background/surface 固定为纯黑,保证 OLED 观感与省电; isWallpaperDynamicColorSupported()决定设置项可见性:SettingScreen.kt 中"壁纸取色"选项只在isWallpaperDynamicColorSupported()为 true 时加入选项列表,低于 Android 12 的设备只会看到"默认"与"自定义"两项。
Desktop 侧 PlatformColorScheme.jvm.kt 直接返回 null(桌面端无壁纸取色),主题回落到种子色生成路径——这是 expect/actual 相对文档中"写死 SDK 判断"版本的优势:平台能力差异被隔离到 actual 实现,AppTheme 主体保持平台无关。
1.2 自定义色板
不支持动态色的环境(低版本 Android、桌面端)需要静态色板兜底。M3 标准调色板以 tonal palette 方式组织:primary/secondary/tertiary 三条色带,各配 on* 文本色与 *Container 容器色,再加 error 四件套与 surface 系列。完整亮色示例:
// Define color palette
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_tertiary = Color(0xFF7D5260)
val md_theme_light_onTertiary = Color(0xFFFFFFFF)
val md_theme_light_tertiaryContainer = Color(0xFFFFD8E4)
val md_theme_light_onTertiaryContainer = Color(0xFF31111D)
val md_theme_light_error = Color(0xFFB3261E)
val md_theme_light_onError = Color(0xFFFFFFFF)
val md_theme_light_errorContainer = Color(0xFFF9DEDC)
val md_theme_light_onErrorContainer = Color(0xFF410E0B)
val md_theme_light_background = Color(0xFFFFFBFE)
val md_theme_light_onBackground = Color(0xFF1C1B1F)
val md_theme_light_surface = Color(0xFFFFFBFE)
val md_theme_light_onSurface = Color(0xFF1C1B1F)
val md_theme_light_surfaceVariant = Color(0xFFE7E0EC)
val md_theme_light_onSurfaceVariant = Color(0xFF49454F)
val md_theme_light_outline = Color(0xFF79747E)
val md_theme_light_outlineVariant = Color(0xFFCAC4D0)
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,
tertiary = md_theme_light_tertiary,
onTertiary = md_theme_light_onTertiary,
tertiaryContainer = md_theme_light_tertiaryContainer,
onTertiaryContainer = md_theme_light_onTertiaryContainer,
error = md_theme_light_error,
onError = md_theme_light_onError,
errorContainer = md_theme_light_errorContainer,
onErrorContainer = md_theme_light_onErrorContainer,
background = md_theme_light_background,
onBackground = md_theme_light_onBackground,
surface = md_theme_light_surface,
onSurface = md_theme_light_onSurface,
surfaceVariant = md_theme_light_surfaceVariant,
onSurfaceVariant = md_theme_light_onSurfaceVariant,
outline = md_theme_light_outline,
outlineVariant = md_theme_light_outlineVariant
)
// Dark colors follow the same pattern
val DarkColorScheme = darkColorScheme(
primary = md_theme_dark_primary,
// ... other colors
)
SimpMusic 走的是另一条现代路径:不手写真调色板,而是用 MaterialKolor 在运行时从一个种子色生成整套 ColorScheme。品牌种子色定义在 Color.kt:
/**
* Brand seed color. The whole Material 3 ColorScheme is generated from this
* color at runtime — see [AppTheme].
*/
val seed = Color(0xFF8ECAE6)
生成逻辑在 Theme.kt:
val seedColor =
if (themeColorSource == DataStoreManager.THEME_COLOR_CUSTOM) {
customThemeColor ?: seed
} else {
seed
}
val colorScheme =
wallpaperScheme
?: rememberDynamicColorScheme(
seedColor = seedColor,
isDark = isDark,
isAmoled = isDark,
style = PaletteStyle.TonalSpot,
modifyColorScheme = { cs -> if (isDark) cs else cs.withNeutralLightSurfaces() },
)
参数含义逐一对应 M3 概念:
| 参数 | 取值 | 作用 |
|---|---|---|
seedColor |
品牌种子色或用户自定义色 | 整个 ColorScheme 由它派生,一处改色全 App 换肤 |
isDark |
由主题模式解析 | 决定生成亮/暗调色板 |
isAmoled |
与 isDark 相同 |
暗色下将 background/surface 压到纯黑(AMOLED 优化) |
style |
PaletteStyle.TonalSpot |
M3 标准调色板结构(primary/secondary/tertiary 分属不同色相区域) |
modifyColorScheme |
亮色时调用 withNeutralLightSurfaces() |
覆盖种子色带来的暖色中性面 |
其中 withNeutralLightSurfaces()(Theme.kt)把亮色主题的 surface 系列改写为纯中性灰阶(R=G=B,无种子色染色):页面背景用 #FAFAFA(M3 推荐的 tone 98)而非纯白——源码注释说明纯白满屏在桌面大窗口上刺眼,而 #FFFFFF 保留给 surfaceBright / surfaceContainerLowest,让卡片与底部弹窗仍有"比页面更亮"的提升层级。
自定义种子色的入口在设置页:用户选"自定义"后弹出取色器,HEX 字符串由 parseThemeColorHex 解析:
/** Parses "RRGGBB" or "AARRGGBB" (optionally "#"-prefixed) into a [Color]; null if malformed. */
fun parseThemeColorHex(hex: String): Color? {
val clean = hex.trim().removePrefix("#")
val argb =
when (clean.length) {
6 -> "FF$clean"
8 -> clean
else -> return null
}
return argb.toLongOrNull(16)?.let { Color(it) }
}
注意其防御性设计:非法格式返回 null,调用方 customThemeColor ?: seed 回落到品牌色,不会因为用户输入把主题打崩。
1.3 颜色角色(Color Roles)的使用
ColorScheme 的每个槽位都有明确语义,组件通过角色名取色而不是硬编码值,才能自动适配亮/暗与动态色:
| 角色 | 语义 | 典型组件 |
|---|---|---|
primary / onPrimary |
关键操作 | 填充按钮、FAB |
primaryContainer / onPrimaryContainer |
弱强调容器 | 高亮 Chip、选中态容器 |
secondary / onSecondary |
次级操作 | FilledTonal 按钮 |
tertiary / onTertiary |
对比强调 | 徽章、点缀 |
error / onError |
破坏性操作、报错 | 删除按钮 |
surface / onSurface |
主内容面 | 页面、卡片 |
surfaceVariant / onSurfaceVariant |
次级内容面 | 次级文本、分割区域 |
outline / outlineVariant |
描边、分隔线 | OutlinedButton 边框 |
参考用法示例(覆盖上面全部角色):
@Composable
fun ColorRolesExample() {
Column(
modifier = Modifier.padding(16.dp),
verticalArrangement = Arrangement.spacedBy(16.dp)
) {
// Primary - Key actions, FABs
Button(onClick = { }) {
Text("Primary Action")
}
// Primary Container - Less prominent containers
Surface(
color = MaterialTheme.colorScheme.primaryContainer,
shape = RoundedCornerShape(12.dp)
) {
Text(
"Primary Container",
modifier = Modifier.padding(16.dp),
color = MaterialTheme.colorScheme.onPrimaryContainer
)
}
// Secondary - Less prominent actions
FilledTonalButton(onClick = { }) {
Text("Secondary Action")
}
// Tertiary - Contrast accents
Badge(
containerColor = MaterialTheme.colorScheme.tertiaryContainer,
contentColor = MaterialTheme.colorScheme.onTertiaryContainer
) {
Text("New")
}
// Error - Destructive actions
Button(
onClick = { },
colors = ButtonDefaults.buttonColors(
containerColor = MaterialTheme.colorScheme.error
)
) {
Text("Delete")
}
// Surface variants
Surface(
color = MaterialTheme.colorScheme.surfaceVariant,
shape = RoundedCornerShape(8.dp)
) {
Text(
"Surface Variant",
modifier = Modifier.padding(16.dp),
color = MaterialTheme.colorScheme.onSurfaceVariant
)
}
}
}
一个容易被忽略的配套技巧在 Theme.kt:SimpMusic 在 MaterialTheme 外层通过 CompositionLocalProvider 把 LocalContentColor 统一提供为 colorScheme.onSurfaceVariant。图标、按钮等未显式指定 contentColor 的 Material 组件会读取 LocalContentColor,这一行等价于"全局次级文本/图标色"的默认值,避免了在各处重复写 color = MaterialTheme.colorScheme.onSurfaceVariant。
1.4 扩展语义色
M3 标准槽位覆盖不了业务语义(成功、警告、收藏、骨架屏等)。规范做法是定义一个扩展数据类,经 staticCompositionLocalOf 注入,而不是让组件到处引用全局 val:
// Custom semantic colors beyond M3 defaults
data class ExtendedColors(
val success: Color,
val onSuccess: Color,
val successContainer: Color,
val onSuccessContainer: Color,
val warning: Color,
val onWarning: Color,
val warningContainer: Color,
val onWarningContainer: Color
)
val LocalExtendedColors = staticCompositionLocalOf {
ExtendedColors(
success = Color(0xFF4CAF50),
onSuccess = Color.White,
successContainer = Color(0xFFE8F5E9),
onSuccessContainer = Color(0xFF1B5E20),
warning = Color(0xFFFF9800),
onWarning = Color.White,
warningContainer = Color(0xFFFFF3E0),
onWarningContainer = Color(0xFFE65100)
)
}
@Composable
fun AppTheme(
content: @Composable () -> Unit
) {
val extendedColors = ExtendedColors(
// ... define colors based on light/dark theme
)
CompositionLocalProvider(
LocalExtendedColors provides extendedColors
) {
MaterialTheme(
colorScheme = colorScheme,
content = content
)
}
}
// Usage
@Composable
fun SuccessBanner() {
val extendedColors = LocalExtendedColors.current
Surface(
color = extendedColors.successContainer,
shape = RoundedCornerShape(8.dp)
) {
Row(
modifier = Modifier.padding(16.dp),
horizontalArrangement = Arrangement.spacedBy(12.dp)
) {
Icon(
Icons.Default.CheckCircle,
contentDescription = null,
tint = extendedColors.success
)
Text(
"Operation successful!",
color = extendedColors.onSuccessContainer
)
}
}
}
SimpMusic 的落地版本是 AppColors(Theme.kt):
@Immutable
data class AppColors(
val favorite: Color,
val lyricActive: Color,
val shimmerBackground: Color,
val shimmerLine: Color,
val overlay: Color,
val overlayHeavy: Color,
)
private val DarkAppColors =
AppColors(
favorite = favoriteColor,
lyricActive = lyricActiveColor,
shimmerBackground = shimmerBackground,
shimmerLine = shimmerLine,
overlay = overlay,
overlayHeavy = blackMoreOverlay,
)
// Overlays stay dark in both themes: they cover artwork, where content is always light.
private val LightAppColors =
DarkAppColors.copy(
shimmerBackground = shimmerBackgroundLight,
shimmerLine = shimmerLineLight,
)
val LocalAppColors = staticCompositionLocalOf { DarkAppColors }
对应的基础色值在 Color.kt:favoriteColor = Color(0xFFFF4081)(红心收藏态)、lyricActiveColor = Color(0xFFFFFF00)(歌词当前行高亮)、shimmer 骨架屏双色 token 及两组 overlay。两处设计决策与文档范式一致且更进一步:
- 亮暗主题共享大部分扩展色:
LightAppColors用copy()只覆写 shimmer 两个值——注释说明 overlay 永远偏暗,因为遮罩覆盖的是专辑封面(内容天然偏亮),与主题方向无关; @Immutable标注:让 Compose 跳过对不可变数据类的字段级相等性检查,减少无谓重组,这是文档示例没有体现的性能细节。
另外 Color.kt 保留了一个 @Deprecated 的旧色 md_theme_dark_primary = Color(0xFFB2C5FF),仅用于设置页存储条,并用注释明确"新代码一律改用 MaterialTheme.colorScheme.primary"——这正是扩展色治理的示范:遗留色集中标记弃用,而不是散落各处。
二、排版(Typography)
2.1 Material 3 类型比例
M3 类型比例按视觉强调度分四组共 15 级:Display(英雄文本/大数字)、Headline(短标题)、Title(中强调标题)、Body(长文)、Label(按钮/Chip 等控件文本)。完整定义:
val AppTypography = Typography(
// Display styles - Hero text, large numerals
displayLarge = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 57.sp,
lineHeight = 64.sp,
letterSpacing = (-0.25).sp
),
displayMedium = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 45.sp,
lineHeight = 52.sp,
letterSpacing = 0.sp
),
displaySmall = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 36.sp,
lineHeight = 44.sp,
letterSpacing = 0.sp
),
// Headline styles - High emphasis, short text
headlineLarge = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 32.sp,
lineHeight = 40.sp,
letterSpacing = 0.sp
),
headlineMedium = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 28.sp,
lineHeight = 36.sp,
letterSpacing = 0.sp
),
headlineSmall = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 24.sp,
lineHeight = 32.sp,
letterSpacing = 0.sp
),
// Title styles - Medium emphasis headers
titleLarge = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 22.sp,
lineHeight = 28.sp,
letterSpacing = 0.sp
),
titleMedium = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Medium,
fontSize = 16.sp,
lineHeight = 24.sp,
letterSpacing = 0.15.sp
),
titleSmall = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Medium,
fontSize = 14.sp,
lineHeight = 20.sp,
letterSpacing = 0.1.sp
),
// Body styles - Long-form text
bodyLarge = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 16.sp,
lineHeight = 24.sp,
letterSpacing = 0.5.sp
),
bodyMedium = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 14.sp,
lineHeight = 20.sp,
letterSpacing = 0.25.sp
),
bodySmall = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 12.sp,
lineHeight = 16.sp,
letterSpacing = 0.4.sp
),
// Label styles - Buttons, chips, navigation
labelLarge = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Medium,
fontSize = 14.sp,
lineHeight = 20.sp,
letterSpacing = 0.1.sp
),
labelMedium = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Medium,
fontSize = 12.sp,
lineHeight = 16.sp,
letterSpacing = 0.5.sp
),
labelSmall = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Medium,
fontSize = 11.sp,
lineHeight = 16.sp,
letterSpacing = 0.5.sp
)
)
速查表(字号 / 行高 / 字距):
| 级别 | 字号 | 行高 | 字距 | 字重 |
|---|---|---|---|---|
| displayLarge | 57.sp | 64.sp | -0.25.sp | Normal |
| displayMedium | 45.sp | 52.sp | 0 | Normal |
| displaySmall | 36.sp | 44.sp | 0 | Normal |
| headlineLarge | 32.sp | 40.sp | 0 | Normal |
| headlineMedium | 28.sp | 36.sp | 0 | Normal |
| headlineSmall | 24.sp | 32.sp | 0 | Normal |
| titleLarge | 22.sp | 28.sp | 0 | Normal |
| titleMedium | 16.sp | 24.sp | 0.15.sp | Medium |
| titleSmall | 14.sp | 20.sp | 0.1.sp | Medium |
| bodyLarge | 16.sp | 24.sp | 0.5.sp | Normal |
| bodyMedium | 14.sp | 20.sp | 0.25.sp | Normal |
| bodySmall | 12.sp | 16.sp | 0.4.sp | Normal |
| labelLarge | 14.sp | 20.sp | 0.1.sp | Medium |
| labelMedium | 12.sp | 16.sp | 0.5.sp | Medium |
| labelSmall | 11.sp | 16.sp | 0.5.sp | Medium |
2.2 自定义字体
把 FontFamily.Default 替换为品牌字体族即可全局换字。多字重打包进一个 FontFamily,让 FontWeight 选择真正映射到不同字体文件:
// Load custom fonts
val Inter = FontFamily(
Font(R.font.inter_regular, FontWeight.Normal),
Font(R.font.inter_medium, FontWeight.Medium),
Font(R.font.inter_semibold, FontWeight.SemiBold),
Font(R.font.inter_bold, FontWeight.Bold)
)
val AppTypography = Typography(
displayLarge = TextStyle(
fontFamily = Inter,
fontWeight = FontWeight.Normal,
fontSize = 57.sp,
lineHeight = 64.sp
),
// Apply to all styles...
)
// Variable fonts (Android 12+)
val InterVariable = FontFamily(
Font(
R.font.inter_variable,
variationSettings = FontVariation.Settings(
FontVariation.weight(400)
)
)
)
SimpMusic 的字体走 Compose Resources(KMP 各平台共享资源):字体文件放在 composeResources/font(poppins_regular.ttf、poppins_medium.ttf、poppins_bold.ttf、space_mono_regular.ttf),Typo.kt 中:
@Composable
fun fontFamily(): FontFamily =
FontFamily(
Font(Res.font.poppins_medium, FontWeight.Normal, FontStyle.Normal),
)
注意它只注册了单一字重文件(Poppins Medium),把该文件映射为 FontWeight.Normal,其余字重靠合成加粗——这是"单一字体文件 + 合成粗体"的轻量策略,与文档示例中四文件精确映射是两种取舍。
2.3 主题感知的文本颜色
文档示例中文字颜色由组件默认从 colorScheme 推导;SimpMusic 更进一步,把 Typography 本身做成 从 colorScheme 计算的 @Composable 函数(Typo.kt):
@Composable
fun typo(
colorScheme: ColorScheme = MaterialTheme.colorScheme,
forceDark: Boolean = LocalForceDarkText.current,
): Typography {
val fontFamily = fontFamily()
// Titles were pure white, everything else muted gray (#A8A8A8) in the old dark-only palette.
// forceDark keeps that; otherwise both come from the scheme (theme-aware light/dark).
val titleColor = if (forceDark) Color.White else colorScheme.onBackground
val bodyColor = if (forceDark) Color(0xFFA8A8A8) else colorScheme.onSurfaceVariant
...
}
这里解决了一个音乐类应用特有的问题:歌手页、专辑页、播放页等"沉浸式"界面始终叠在深色封面上,即便 App 是亮色主题也必须用深色文字配色。LocalForceDarkText 这个 CompositionLocal 由 ForceDarkContent(见第 6 节)置为 true,于是同一份 Typography 在两种渲染模式下给出不同颜色:
forceDark = true:标题纯白、正文#A8A8A8(历史深色视觉,保证封面之上可读);forceDark = false:标题取colorScheme.onBackground、正文取colorScheme.onSurfaceVariant,随亮/暗主题自动切换。
同时字号体系是应用自定义的紧凑比例(titleLarge = 25.sp Bold、bodyLarge = 18.sp 等),并未照搬 M3 标准数值——标准比例适合作为初始基线,落地时按信息密度调整,这正是把"类型比例"当作 token 而非教条使用的方式。
三、形状系统(Shape System)
M3 的形状系统同样是五级 token,从 Chip 到全屏弹窗逐级放大圆角:
val AppShapes = Shapes(
// Extra small - Chips, small buttons
extraSmall = RoundedCornerShape(4.dp),
// Small - Text fields, small cards
small = RoundedCornerShape(8.dp),
// Medium - Cards, dialogs
medium = RoundedCornerShape(12.dp),
// Large - Large cards, bottom sheets
large = RoundedCornerShape(16.dp),
// Extra large - Full-screen dialogs
extraLarge = RoundedCornerShape(28.dp)
)
组件通过 MaterialTheme.shapes.* 引用 token,保持全局一致;需要打破节奏时再内联自定义形状(如下方非对称圆角):
@Composable
fun ShapedComponents() {
Column(
verticalArrangement = Arrangement.spacedBy(16.dp)
) {
// Small shape for text field
OutlinedTextField(
value = "",
onValueChange = {},
shape = MaterialTheme.shapes.small,
label = { Text("Input") }
)
// Medium shape for cards
Card(
shape = MaterialTheme.shapes.medium
) {
Text("Card content", modifier = Modifier.padding(16.dp))
}
// Large shape for prominent containers
Surface(
shape = MaterialTheme.shapes.large,
color = MaterialTheme.colorScheme.primaryContainer
) {
Text("Featured", modifier = Modifier.padding(24.dp))
}
// Custom asymmetric shape
Surface(
shape = RoundedCornerShape(
topStart = 24.dp,
topEnd = 24.dp,
bottomStart = 0.dp,
bottomEnd = 0.dp
),
color = MaterialTheme.colorScheme.surface
) {
Text("Bottom sheet style", modifier = Modifier.padding(16.dp))
}
}
}
| Shape token | 圆角 | 适用组件 |
|---|---|---|
| extraSmall | 4.dp | Chip、小型按钮 |
| small | 8.dp | 文本框、小卡片 |
| medium | 12.dp | 卡片、对话框 |
| large | 16.dp | 大卡片、底部弹窗 |
| extraLarge | 28.dp | 全屏对话框 |
非对称 RoundedCornerShape(topStart, topEnd, bottomStart, bottomEnd) 是实现底部抽屉(Bottom Sheet)视觉的标准手法:上方两角 24.dp 圆角、下方贴屏边保持直角。
四、高程与阴影(Elevation)
M3 的高程分两条通道:shadowElevation(真实投影,强调"漂浮感")与 tonalElevation(用主色按 tonal 算法染面,替代投影传达层级,在深色 AMOLED 主题下更克制)。官方五级对应关系:
| 级别 | tonalElevation | shadowElevation | 典型组件 |
|---|---|---|---|
| 0 | 0.dp | 0.dp | 无高程(平贴背景) |
| 1 | 1.dp | 1.dp | 低强调面 |
| 2 | 3.dp | 2.dp | 卡片、Switch |
| 3 | 6.dp | 4.dp | 导航组件(NavigationBar 等) |
| 4 | 8.dp | 6.dp | NavigationRail |
| 5 | 12.dp | 8.dp | FAB |
@Composable
fun ElevationExample() {
Column(
verticalArrangement = Arrangement.spacedBy(16.dp)
) {
// Level 0 - No elevation
Surface(
tonalElevation = 0.dp,
shadowElevation = 0.dp
) {
Text("Level 0", modifier = Modifier.padding(16.dp))
}
// Level 1 - Low emphasis surfaces
Surface(
tonalElevation = 1.dp,
shadowElevation = 1.dp
) {
Text("Level 1", modifier = Modifier.padding(16.dp))
}
// Level 2 - Cards, switches
Surface(
tonalElevation = 3.dp,
shadowElevation = 2.dp
) {
Text("Level 2", modifier = Modifier.padding(16.dp))
}
// Level 3 - Navigation components
Surface(
tonalElevation = 6.dp,
shadowElevation = 4.dp
) {
Text("Level 3", modifier = Modifier.padding(16.dp))
}
// Level 4 - Navigation rail
Surface(
tonalElevation = 8.dp,
shadowElevation = 6.dp
) {
Text("Level 4", modifier = Modifier.padding(16.dp))
}
// Level 5 - FAB
Surface(
tonalElevation = 12.dp,
shadowElevation = 8.dp
) {
Text("Level 5", modifier = Modifier.padding(16.dp))
}
}
}
同一"层级差"思想在 SimpMusic 桌面端外壳中也被显式编码(Color.kt 与 App.kt):窗口本身取极值色(深色主题纯黑 0xFF000000、浅色主题纯白),侧边面板"回退一档"取 desktopPanelDark = Color(0xFF121212)(或亮色下的 surfaceContainer),使面板读起来像被抬升了一层——即不靠投影而靠 surface 色阶实现视觉高程,与 tonal elevation 的理念同源。
五、响应式布局:WindowSizeClass 与折叠屏
5.1 窗口尺寸类
M3 把窗口宽度归为三档,每档对应一套导航范式:Compact 用底部导航,Medium 用导航栏(NavigationRail),Expanded 用常驻抽屉 + 多栏。参考实现:
@Composable
fun AdaptiveLayout() {
val windowSizeClass = calculateWindowSizeClass(LocalContext.current as Activity)
when (windowSizeClass.widthSizeClass) {
WindowWidthSizeClass.Compact -> {
// Phone portrait - Single column, bottom nav
CompactLayout()
}
WindowWidthSizeClass.Medium -> {
// Tablet portrait, phone landscape - Navigation rail
MediumLayout()
}
WindowWidthSizeClass.Expanded -> {
// Tablet landscape, desktop - Navigation drawer, multi-pane
ExpandedLayout()
}
}
}
@Composable
fun CompactLayout() {
Scaffold(
bottomBar = { NavigationBar { /* items */ } }
) { padding ->
Content(modifier = Modifier.padding(padding))
}
}
@Composable
fun MediumLayout() {
Row {
NavigationRail { /* items */ }
Content(modifier = Modifier.weight(1f))
}
}
@Composable
fun ExpandedLayout() {
PermanentNavigationDrawer(
drawerContent = {
PermanentDrawerSheet { /* items */ }
}
) {
Row {
ListPane(modifier = Modifier.weight(0.4f))
DetailPane(modifier = Modifier.weight(0.6f))
}
}
}
SimpMusic 的 KMP 代码没有直接调用 calculateWindowSizeClass(它依赖 Android 的 Activity),而是用 material3-adaptive 依赖(见 libs.versions.toml 的 compose-material3-adaptive)在 commonMain 中拿窗口尺寸做断点判断,App.kt:
val isTablet = windowSize.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND)
val isTabletLandscape = isTablet && currentOrientation() == Orientation.LANDSPACE
即:以官方 WINDOW_SIZE_CLASS_MEDIUM 断点(600dp)作为"平板"门槛,再叠加横竖屏判断,切换底部导航与侧栏两套布局——与文档中 Compact/Medium/Expanded 三档思路一致,只是把档位坍缩成项目实际需要的两个布尔量。
5.2 折叠屏支持
Compose 的 LocalFoldingFeature 提供铰链位置、方向与状态,可据此为折叠态单独布局:
@Composable
fun FoldableAwareLayout() {
val foldingFeature = LocalFoldingFeature.current
when {
foldingFeature?.state == FoldingFeature.State.HALF_OPENED -> {
// Device is half-folded (tabletop mode)
TwoHingeLayout(
top = { CameraPreview() },
bottom = { CameraControls() }
)
}
foldingFeature?.orientation == FoldingFeature.Orientation.VERTICAL -> {
// Vertical fold (book mode)
TwoPaneLayout(
first = { NavigationPane() },
second = { ContentPane() }
)
}
else -> {
// Regular or fully opened
SinglePaneLayout()
}
}
}
三种典型姿态的应对策略:
HALF_OPENED(台架半折):上下屏分属两块物理区域,可做"上屏预览 + 下屏控制"的分屏;Orientation.VERTICAL(书本模式竖折):双屏并排,适合导航/详情两栏;- 其余(直板或完全展开):单栏布局。
六、SimpMusic 的主题编排实战
把前述要素组装起来,Theme.kt 中的 AppTheme 展示了生产级主题入口的完整形态:
@OptIn(ExperimentalMaterial3ExpressiveApi::class, ExperimentalMaterial3Api::class)
@Composable
fun AppTheme(
themeMode: String = DataStoreManager.THEME_MODE_DARK,
themeColorSource: String = DataStoreManager.THEME_COLOR_DEFAULT,
customThemeColor: Color? = null,
liquidGlassEnabled: Boolean = true,
content: @Composable() () -> Unit,
) {
val isDark = isDarkTheme(themeMode)
val wallpaperScheme =
if (themeColorSource == DataStoreManager.THEME_COLOR_WALLPAPER) {
platformDynamicColorScheme(isDark)
} else {
null
}
val seedColor =
if (themeColorSource == DataStoreManager.THEME_COLOR_CUSTOM) {
customThemeColor ?: seed
} else {
seed
}
val colorScheme =
wallpaperScheme
?: rememberDynamicColorScheme(
seedColor = seedColor,
isDark = isDark,
isAmoled = isDark,
style = PaletteStyle.TonalSpot,
modifyColorScheme = { cs -> if (isDark) cs else cs.withNeutralLightSurfaces() },
)
val forcedDarkScheme =
if (isDark) {
colorScheme
} else {
rememberDynamicColorScheme(
seedColor = seedColor,
isDark = true,
isAmoled = true,
style = PaletteStyle.TonalSpot,
)
}
SystemBarAppearanceEffect(isDark)
MaterialExpressiveTheme(
colorScheme = colorScheme,
content = {
CompositionLocalProvider(
LocalRippleConfiguration provides SoftRippleConfiguration,
LocalContentColor provides colorScheme.onSurfaceVariant,
LocalAppColors provides if (isDark) DarkAppColors else LightAppColors,
LocalIsDarkTheme provides isDark,
LocalForcedDarkColorScheme provides forcedDarkScheme,
LocalLiquidGlassEnabled provides liquidGlassEnabled,
content = content,
)
},
typography = typo(colorScheme),
)
}
6.1 主题模式与取色来源
模式解析被抽成独立函数(Theme.kt),三档模式映射为布尔:
@Composable
fun isDarkTheme(themeMode: String): Boolean =
when (themeMode) {
DataStoreManager.THEME_MODE_LIGHT -> false
DataStoreManager.THEME_MODE_SYSTEM -> isSystemInDarkTheme()
else -> true // 默认 DARK
}
颜色来源三档(THEME_COLOR_DEFAULT / THEME_COLOR_WALLPAPER / THEME_COLOR_CUSTOM)与取色来源正交:壁纸取色只在 Android 12+ 生效(第 1.1 节),自定义色经 parseThemeColorHex 容错解析后替换种子色,两档都不满足时回落到品牌种子 0xFF8ECAE6。
6.2 MaterialExpressiveTheme 与版本锁定
AppTheme 用的是 MaterialExpressiveTheme(Material 3 Expressive 的主题入口)而非裸 MaterialTheme。依赖版本在 libs.versions.toml 中被刻意双份锁定:
material3-expressive = "1.5.0-alpha22" # MUST equal the androidx material3 that material3-multiplatform maps to (1.12.0-alpha03 -> 1.5.0-alpha22, read off its .module). ...
material3-multiplatform = "1.12.0-alpha03"
注释说明了原因:commonMain 编译所用的 androidx material3 版本必须与 multiplatform 包装层所映射的版本完全一致,否则会出现 alpha 版本间 API 签名漂移导致的运行时 NoSuchMethodError(注释中记录了一次因版本错配导致的 Slider 崩溃)。这是对"跨平台 + 实验性依赖"组合的重要运维经验:两个 material3 坐标要成组升级。
6.3 涟漪(Ripple)定制
深色近黑背景上,M3 默认的涟漪透明度会读成"灰色闪光"。SimpMusic 用 LocalRippleConfiguration 全局压低了涟漪强度(Theme.kt):
@OptIn(ExperimentalMaterial3Api::class)
@Suppress("DEPRECATION")
private val SoftRippleConfiguration =
RippleConfiguration(
rippleAlpha =
RippleAlpha(
draggedAlpha = 0.06f,
focusedAlpha = 0.04f,
hoveredAlpha = 0.03f,
pressedAlpha = 0.04f,
),
)
各 alpha 约为 Material 默认值的 40%,源码注释解释了两点取舍:颜色字段刻意留空,让涟漪继续从 LocalContentColor 派生(保证在强制深色子树里方向正确);该配置同时作用于裸 Modifier.clickable,因为 MaterialTheme 已把 material3.ripple() 作为 LocalIndication 提供。
6.4 沉浸式强制深色子树(ForceDarkContent)
"亮色主题下的深色封面页"不能只改文字颜色——图标、按钮、默认控件都从 LocalContentColor 和 MaterialTheme.colorScheme 取色,只调文字会在浅色方案下变成深灰不可读。ForceDarkContent 的解法是整棵子树换方案:
@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Composable
fun ForceDarkContent(content: @Composable () -> Unit) {
val darkScheme = LocalForcedDarkColorScheme.current ?: MaterialTheme.colorScheme
MaterialExpressiveTheme(
colorScheme = darkScheme,
content = {
CompositionLocalProvider(
LocalForceDarkText provides true,
LocalIsDarkTheme provides true,
LocalContentColor provides darkScheme.onSurfaceVariant,
LocalAppColors provides DarkAppColors,
content = content,
)
},
typography = typo(darkScheme, forceDark = true),
)
}
为避免每个沉浸式页面各自生成一份深色调色板,AppTheme 在顶层就把 forcedDarkScheme 算好并通过 LocalForcedDarkColorScheme 下发。这套"子树主题覆写"手法正是 CompositionLocal 体系相对 XML Theme.Material3 的扩展能力:主题作用域可以任意嵌套。
6.5 系统栏外观同步
动态取色只影响 Compose 内容,状态栏/导航栏图标方向必须在 Window 层补齐(PlatformColorScheme.android.kt):
@Composable
actual fun SystemBarAppearanceEffect(isDark: Boolean) {
val view = LocalView.current
val context = LocalContext.current
if (!view.isInEditMode) {
SideEffect {
val window = context.getActivityOrNull()?.window ?: return@SideEffect
val controller = WindowCompat.getInsetsController(window, view)
// Light theme → dark icons; dark theme → light icons.
controller.isAppearanceLightStatusBars = !isDark
controller.isAppearanceLightNavigationBars = !isDark
}
}
}
AppTheme 在构建主题时即调用该效果,保证换肤瞬间系统栏图标颜色同步翻转,避免出现"深底深图标"的不可见状态。
七、参考文件速查
| 主题组成 | 文档参考位置 | 仓库实现 |
|---|---|---|
| AppTheme / 动态色 | 本文 1.1 节 | Theme.kt |
| 种子色 / 扩展语义色 | 本文 1.2 / 1.4 节 | Color.kt |
| 平台动态取色(Android) | 本文 1.1 节 | PlatformColorScheme.android.kt |
| 平台动态取色(Desktop) | 本文 1.1 节 | PlatformColorScheme.jvm.kt |
| 排版与字体 | 本文第二节 | Typo.kt、composeResources/font |
| 响应式断点 | 本文 5.1 节 | App.kt |
| 取色来源设置 UI | 本文 6.1 节 | SettingScreen.kt |
| material3 依赖版本 | 本文 6.2 节 | libs.versions.toml |
综合来看,M3 主题系统的落地路径可以概括为三步:先用种子色 + rememberDynamicColorScheme 生成基础 ColorScheme(Android 12+ 可叠加壁纸取色);再用 CompositionLocal 注入业务扩展色、涟漪、强制深色等横切能力;最后按 WindowSizeClass 断点适配大屏与折叠屏。SimpMusic 的 ui/theme 三文件加上平台 actual 实现,构成了这套流程在 Compose Multiplatform 项目中的完整参照。