Miuix主题系统实战:Monet动态取色、深色模式与文本样式完整教程

原创2026-10-11 18:46:34669 阅读

Miuix主题系统实战:Monet动态取色、深色模式与文本样式完整教程

Miuix 是面向 Compose Multiplatform 的 UI 组件库,而它的主题系统是整库的地基:一套 ThemeController 控制器 + MiuixTheme 包裹,就能让你的 App 同时获得深色模式、Monet 动态取色和统一的文本样式,且一套代码通吃 Android、iOS、桌面与 Web。

Miuix 主题系统四种模式效果对比

↑ 同一界面在浅色、深色、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) // 强制深色
}

Miuix 深色模式与浅色模式界面对比

↑ 按钮、进度条、输入框在浅色与深色模式下自动适配颜色,无需手动维护两套配色

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 支持,其他风格自动回退)

Miuix Monet 动态取色效果展示

↑ 同一套界面:左侧为默认配色,右侧为 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) { /* 内容 */ }

Miuix 文本样式与组件在不同主题下的渲染

↑ 不同主题模式下,标题、选项卡与图标均自动适配主题色与文本样式

进阶:完全自定义颜色方案

如果不想用内置配色,可以直接把自己的 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 模式,方便做条件渲染。

Miuix 自定义配色下的颜色面板与卡片效果

↑ 不同种子色驱动出的完整配色方案,卡片、调色板与组件颜色一一对应

常见问题速查

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 两份文档,基本可以零成本上手。

登录后查看全文
miuix