Miuix主题系统实战:Monet动态取色、深色模式与文本样式完整教程
Miuix主题系统实战:Monet动态取色、深色模式与文本样式完整教程
Miuix 是面向 Compose Multiplatform 的 UI 组件库,而它的主题系统是整库的地基:一套 ThemeController 控制器 + MiuixTheme 包裹,就能让你的 App 同时获得深色模式、Monet 动态取色和统一的文本样式,且一套代码通吃 Android、iOS、桌面与 Web。
↑ 同一界面在浅色、深色、Monet 浅色、Monet 深色四种主题下的渲染效果
快速上手:两步接入 Miuix 主题系统
第 1 步,在 build.gradle.kts 中加入依赖(KMP 项目使用 commonMain):
kotlin {
sourceSets {
commonMain.dependencies {
implementation("top.yukonga.miuix.kmp:miuix-ui:<version>")
}
}
}
第 2 步,创建 ThemeController 并用 MiuixTheme 包裹整个 App:
@Composable
fun App() {
val controller = remember { ThemeController(ColorSchemeMode.System) }
MiuixTheme(controller = controller) {
// 你的界面内容
}
}
就这么多。所有 Miuix 组件(Button、Card、Switch……)都会自动读取当前主题的颜色和文本样式,无需逐一手写。核心实现在 MiuixTheme.kt 与 ThemeController.kt,官方文档见 docs/guide/theme.md。
深色模式怎么接:跟随系统或一键强制
ColorSchemeMode 提供 6 种模式,覆盖日常所有需求:
| 模式 | 行为 |
|---|---|
System |
跟随系统浅/深色(默认) |
Light / Dark |
强制浅色 / 强制深色 |
MonetSystem |
动态取色 + 跟随系统深浅 |
MonetLight / MonetDark |
动态取色 + 强制浅/深色 |
想让用户在 App 内手动切换深浅色?给 ThemeController 传 isDark 即可覆盖系统设置:
val controller = remember {
ThemeController(ColorSchemeMode.System, isDark = true) // 强制深色
}
↑ 按钮、进度条、输入框在浅色与深色模式下自动适配颜色,无需手动维护两套配色
Monet 动态取色:从一颗种子色到整套界面
这是 Miuix 主题系统的亮点 🎨。把 ColorSchemeMode 换成 MonetSystem(或 MonetLight/MonetDark),组件即进入动态取色模式:
- 不指定
keyColor:在 Android 上尝试读取系统壁纸色,即 Material You 效果; - 指定
keyColor:以这颗"种子色"生成整套配色,任何平台都可用。
val controller = remember {
ThemeController(
ColorSchemeMode.MonetSystem,
keyColor = Color(0xFF3482FF), // 种子色,可省略
paletteStyle = ThemePaletteStyle.Vibrant,
colorSpec = ThemeColorSpec.Spec2025
)
}
生成配色时可自由组合两个参数(完整定义见 ThemeController.kt):
| 参数 | 常用取值 | 效果 |
|---|---|---|
paletteStyle |
TonalSpot(默认) |
均衡的 Material You 风格 |
Neutral |
低饱和度、沉稳 | |
Vibrant |
高饱和、鲜艳 | |
Expressive |
大胆、有艺术感 | |
colorSpec |
Spec2021 |
经典 Material 3 色彩规范 |
Spec2025 |
2025 新版规范(仅 TonalSpot/Neutral/Vibrant/Expressive 支持,其他风格自动回退) |
↑ 同一套界面:左侧为默认配色,右侧为 Monet 动态取色生成的浅/深色方案
文本样式完整清单:14 种规格开箱即用
Miuix 内置了 14 种文本样式,全部通过 MiuixTheme.textStyles 访问,颜色会自动跟随主题的 onBackground:
| 样式 | 字号 | 字重 | 典型用途 |
|---|---|---|---|
title1 ~ title4 |
32 / 24 / 20 / 18sp | Normal | 大标题、页面标题 |
main / paragraph |
17sp | Normal | 主文本、段落(1.2em 行高) |
body1 / body2 |
16 / 14sp | Normal | 正文 |
headline1 / headline2 |
17 / 16sp | Normal | 列表标题 |
subtitle |
14sp | Bold | 加粗小标题 |
footnote1 / footnote2 |
13 / 11sp | Normal | 辅助说明 |
button |
17sp | Normal | 按钮文字 |
使用非常直观:
Text("页面标题", style = MiuixTheme.textStyles.title2)
Text("正文内容", style = MiuixTheme.textStyles.body1)
想改某一种规格?用 defaultTextStyles(...) 只覆写目标项,其余保持默认:
val customTextStyles = defaultTextStyles(
title1 = TextStyle(fontSize = 36.sp, fontWeight = FontWeight.Bold)
)
MiuixTheme(controller = controller, textStyles = customTextStyles) { /* 内容 */ }
↑ 不同主题模式下,标题、选项卡与图标均自动适配主题色与文本样式
进阶:完全自定义颜色方案
如果不想用内置配色,可以直接把自己的 Colors 交给主题。两种方式任选:
// 方式一:通过控制器提供自定义的浅/深色方案
val controller = remember {
ThemeController(
ColorSchemeMode.System,
lightColors = myLightColors,
darkColors = myDarkColors
)
}
// 方式二:跳过控制器,直接传入(适合静态主题)
MiuixTheme(colors = lightColorScheme()) { /* 内容 */ }
内置色板包含 primary、surface、outline 等 50 余个语义化色值,浅色与深色默认值全部列在 docs/guide/colors.md 中,自定义时可按需逐项替换。运行时还能通过 MiuixTheme.isDynamicColor 判断当前是否处于 Monet 模式,方便做条件渲染。
↑ 不同种子色驱动出的完整配色方案,卡片、调色板与组件颜色一一对应
常见问题速查
Q:深色模式下组件颜色没变?
确认整个界面树都在 MiuixTheme 包裹内;局部使用 MiuixTheme(colors = ...) 会提供独立配色并向下覆盖。
Q:Spec2025 为什么没生效?
只有 TonalSpot、Neutral、Vibrant、Expressive 四种 paletteStyle 支持 2025 规范,其余风格会静默回退到 Spec2021,不会报错。
Q:如何判断当前是浅色还是深色?
读取 MiuixTheme.colorSchemeMode,配合 isDynamicColor 即可区分六种模式;示例 App 的完整用法可参考 Theme.kt。
Q:想改某种文本样式的默认值?
优先用 defaultTextStyles() 局部覆写,而不是新建整个 TextStyles 对象,这样其余 13 种规格保持默认行为。
小结
| 需求 | 一行代码搞定 |
|---|---|
| 跟随系统深色模式 | ThemeController(ColorSchemeMode.System) |
| 强制深色 | ThemeController(ColorSchemeMode.System, isDark = true) |
| 壁纸取色(Material You) | ThemeController(ColorSchemeMode.MonetSystem) |
| 种子色取色 + 风格 | ThemeController(ColorSchemeMode.MonetSystem, keyColor = ..., paletteStyle = ...) |
| 自定义文本规格 | MiuixTheme(controller, textStyles = defaultTextStyles(...)) |
Miuix 的主题系统把"一套代码、全平台一致外观"这件事做得很彻底:模式选择、动态取色、文本规格三件事各自由一个参数负责,组合起来即可覆盖绝大多数 App 的主题需求。配合 docs/guide/theme.md、docs/guide/textstyles.md 两份文档,基本可以零成本上手。




