Miuix七大模块架构解析：miuix-ui、miuix-blur、miuix-nav选型完全指南

Miuix 是一款基于 Compose Multiplatform 的 UI 组件库，用小米 HyperOS 设计语言打造跨平台应用界面。它拆分为 7 个可独立引入的模块：核心组件 miuix-ui、设置项 miuix-preference、图标 miuix-icons、模糊特效 miuix-blur、圆角形状 miuix-squircle、导航 miuix-nav 和底层着色器 miuix-shader。本文带你快速看懂每个模块的定位与依赖关系，帮你按场景选型、按需引入，避免不必要的体积开销。

🗺️ 一张表看懂 Miuix 七大模块

模块	定位	依赖关系
miuix-ui	核心 UI 组件库（按钮、卡片、弹窗、主题系统）	依赖 miuix-core
miuix-preference	设置页组件（Switch/Checkbox/Slider 偏好项）	依赖 miuix-ui
miuix-icons	扩展图标库	可独立使用
miuix-blur	背景模糊、色彩混合特效	可独立使用
miuix-squircle	连续曲率圆角（Squircle）形状	可独立使用
miuix-nav	自研导航运行时（连续栈深度动画）	可独立使用
miuix-shader	底层 RuntimeShader / RenderEffect 抽象	底层基础设施

模块清单可在 settings.gradle.kts 中完整看到，官方文档也列出了同样结构：docs/guide/getting-started.md。

🧩 miuix-ui：核心组件库（必选）

miuix-ui 是全家桶的地基，覆盖日常开发 90% 的界面需求：

• 基础组件：Button、Text、Card、Icon、Snackbar、ProgressIndicator 等
• 交互组件：Slider、Switch、Checkbox、SearchBar、TabRow、Scaffold
• 弹窗体系：Overlay 与 Window 两套弹窗（Dialog、BottomSheet、DropdownMenu 等），跨平台表现一致
• 主题系统：通过 MiuixTheme + ThemeController 支持六种配色模式（System/Light/Dark/Monet 系列），Monet 动态色可跟随壁纸自动换色

源码位于 miuix-ui/src/commonMain/kotlin/top/yukonga/miuix/kmp/basic/，每个组件一个文件，结构清晰。主题细节可参考 docs/guide/theme.md。

⚙️ miuix-preference：设置页组件库

做「设置」页面时不用自己拼卡片：SwitchPreference、CheckboxPreference、RadioButtonPreference、SliderPreference、ArrowPreference 以及 Dropdown/Spinner 偏好项一应俱全。

• 源码：miuix-preference/src/commonMain/kotlin/top/yukonga/miuix/kmp/preference/
• 注意：它依赖 miuix-ui，是唯一非独立模块，引入后会一起带入 UI 组件

如果只需要一个设置页，引入 miuix-preference 就够了，不需要单独再加 miuix-ui。

🎨 miuix-icons：扩展图标库

内置超过 156 个扩展图标文件（位于 miuix-icons/src/commonMain/kotlin/top/yukonga/miuix/kmp/icon/extended/），风格与组件库统一。可完全独立引入——如果你的项目已经用了其他图标方案，可以整个跳过这个模块。

🌫️ miuix-blur：模糊特效库

想要 HyperOS 那种「毛玻璃」背景模糊？miuix-blur 通过 Modifier 扩展提供：

• 背景模糊（Backdrop Blur）：分离高斯模糊 RuntimeShader
• 色彩混合（Color Blend）与纹理效果
• 跨平台支持 Android / Desktop / iOS / macOS / Web

⚠️ 选型注意点：Android 端要求 minSdk 33（依赖 RuntimeShader）。低版本设备会自动回退，但需要你用能力检测代码做保护。详细说明见 docs/guide/blur.md，核心实现如 BackdropEffects.kt。

⭕ miuix-squircle：连续曲率圆角

普通 RoundedCornerShape 的角是纯四分之一圆弧，在直线与弧交界处曲率突变；Squircle（连续曲率圆角）则把曲率分布到更大角区，呈现手机图标那种「顺滑圆角」。

• 提供 fill / clip / border 的 Modifier 扩展和底层 Path 构建器
• 源码：miuix-squircle/src/commonMain/kotlin/top/yukonga/miuix/kmp/squircle/SquirclePath.kt
• 低版本 Android 会自动回退到普通圆角渲染，不会崩溃
• 文档：docs/guide/squircle.md

🧭 miuix-nav：自研导航运行时

这是整个库中最「硬核」的模块：一个不依赖 androidx.navigation3 的独立导航运行时，核心模型是「连续栈深度」——整条返回栈由单个 Animatable<Float>（animatedTop）驱动，带来三个能力：

• 连续 push/pop：一次推入多个页面时动画是连续扫过，而非合并成一次淡入淡出
• 全自定义转场：视觉完全由栈深度这个浮点值决定
• 1:1 手势返回：边缘滑动返回天然支持

核心类 NavDisplay 位于 miuix-nav/src/commonMain/kotlin/top/yukonga/miuix/kmp/nav/core/NavDisplay.kt，完整用法（含 rememberNavBackStack、手势仲裁）见 docs/guide/miuix-nav.md。

🎛️ miuix-shader：底层着色器抽象

miuix-shader 是对 RuntimeShader / RenderEffect 的跨平台统一封装（commonMain 定义接口，androidMain / skikoMain 各自实现），为 miuix-blur、miuix-squircle 等模块提供底层能力。一般不需要直接引入，了解其存在即可。源码：miuix-shader/src/commonMain/kotlin/top/yukonga/miuix/kmp/shader/。

🎯 场景化选型指南

你的场景	建议引入
从零开始做 HyperOS 风格 App	miuix-ui + miuix-preference + miuix-icons
只需毛玻璃模糊效果	只加 miuix-blur（Android 需 minSdk 33）
想要顺滑图标圆角	只加 miuix-squircle
想要连续手势返回导航	只加 miuix-nav
全部都要	五个模块全引，互不冲突

🚀 快速接入步骤

1. 确保仓库中包含 mavenCentral()
2. 在 commonMain.dependencies 中按需添加（版本号以 Maven Central 为准）：

implementation("top.yukonga.miuix.kmp:miuix-ui:<version>")        // 核心
implementation("top.yukonga.miuix.kmp:miuix-blur:<version>")      // 可选
implementation("top.yukonga.miuix.kmp:miuix-nav:<version>")       // 可选

3. 用 MiuixTheme 包裹根界面即可：

val controller = remember { ThemeController(ColorSchemeMode.System) }
MiuixTheme(controller = controller) { /* 你的内容 */ }

跨平台支持细节（Android / iOS / macOS / Desktop / Web 的平台检测与适配）见 docs/guide/multiplatform.md。

💡 小结：Miuix 的模块化设计让你「用多少引多少」——miuix-ui 打底，miuix-blur 加质感，miuix-nav 加交互，miuix-squircle 和 miuix-icons 按需点缀。按需组合，才是最好的选型。