主题定制

flutter_miuix 的主题体系由三层组成，按需选用：

组件	适用场景
MiuixTheme	手动提供一份固定的 MiuixThemeData（最底层）
MiuixSystemTheme	自动跟随系统明暗模式，可自定义浅色 / 深色配色（最常用）
MiuixThemeController	完整的主题控制器：强制明暗、Monet 动态取色、palette 风格切换

完整 API 参考见主题、配色与动效。

跟随系统明暗：MiuixSystemTheme

绝大多数应用只需要在根部包一层 MiuixSystemTheme：

MiuixSystemTheme(
  child: Builder(builder: (context) {
    final theme = MiuixTheme.of(context);
    return MaterialApp(
      theme: ThemeData(brightness: theme.brightness),
      home: const HomePage(),
    );
  }),
)

读取主题

任意组件内通过 MiuixTheme.of(context) 获取当前主题：

final theme = MiuixTheme.of(context);

theme.colors.primary;        // 配色：50+ 个 HyperOS 语义角色
theme.textStyles.title2;     // 文本样式：14 种预设字号
theme.brightness;            // 当前亮度模式

未被任何主题组件包裹时，MiuixTheme.of 回退到 MiuixThemeData.light()；MiuixTheme.maybeOf(context) 则返回 null 且不建立依赖。

自定义配色

默认配色由 lightColorScheme() / darkColorScheme() 提供（与 HyperOS 规范一致：浅色主色 0xFF3482FF，深色主色 0xFF277AF7）。通过 copy 覆盖部分颜色后传给 MiuixSystemTheme：

MiuixSystemTheme(
  light: lightColorScheme().copy(
    primary: const Color(0xFFFF6B35),
    background: const Color(0xFFFFFBF8),
  ),
  dark: darkColorScheme().copy(
    primary: const Color(0xFFFF8C5A),
  ),
  child: ...,
)

MiuixColors 的全部语义角色（primary / surface / container / 禁用态等 50+ 个字段）见 MiuixColors 参考。

自定义文本样式

MiuixSystemTheme(
  textStyles: defaultTextStyles().copy(
    title1: const TextStyle(fontSize: 36, fontWeight: FontWeight.w600),
  ),
  child: ...,
)

所有样式仅保留字号 / 字重 / 行高，颜色由主题的 onBackground 在运行时提供。

完整控制：MiuixThemeController

需要强制明暗或 Monet 动态取色时，改用 MiuixThemeController：

MiuixThemeController(
  colorSchemeMode: MiuixColorSchemeMode.monetSystem,
  keyColor: const Color(0xFF6750A4),   // 种子色；为 null 时走平台壁纸取色
  child: MyApp(),
)

配色模式

MiuixColorSchemeMode	说明
system	跟随系统亮度，使用静态 light / dark 配色（默认）
light	强制浅色
dark	强制深色
monetSystem	跟随系统亮度 + Monet 动态取色
monetLight	浅色 + Monet 动态取色
monetDark	深色 + Monet 动态取色

Monet 取色流程

1. keyColor 非空 → 同步调用 miuixColorsFromSeed（纯 HCT 计算，无平台通道），从种子色生成整套 27 个角色的配色。
2. keyColor 为空 → 异步调用 miuixPlatformDynamicColors：Android 上读取系统壁纸 / 主题种子色；其他平台回退到固定种子 0xFF6750A4。结果就绪前用 miuixMonetSystemColors 占位以避免闪烁。

Palette 风格

通过 paletteStyle 切换 Monet 配色风格（对应 Material 的 9 种 DynamicScheme）：

MiuixThemeController(
  colorSchemeMode: MiuixColorSchemeMode.monetSystem,
  keyColor: const Color(0xFF6750A4),
  paletteStyle: MiuixThemePaletteStyle.vibrant,
  child: MyApp(),
)

可选值：tonalSpot（默认）、neutral、vibrant、expressive、rainbow、fruitSalad、monochrome、fidelity、content。

手动生成配色

不使用 Controller 也可以直接从种子色生成一套 MiuixColors：

final colors = miuixColorsFromSeed(
  seed: const Color(0xFF6750A4),
  dark: false,
  paletteStyle: MiuixThemePaletteStyle.tonalSpot,
);

MiuixTheme(
  data: MiuixThemeData.light(colors: colors),
  child: ...,
)

与 Material 组件混用

Miuix 组件只依赖 MiuixTheme。如果页面中还有 Material 组件，建议用 Miuix 主色桥接 Material 的 ColorScheme，保持两边观感一致：

final theme = MiuixTheme.of(context);

MaterialApp(
  theme: ThemeData(
    useMaterial3: true,
    colorScheme: ColorScheme.fromSeed(
      seedColor: theme.colors.primary,
      brightness: theme.brightness,
    ),
    brightness: theme.brightness,
  ),
  home: ...,
)

下一步

• 主题、配色与动效 API 参考 — MiuixThemeData / MiuixColors / MiuixTextStyles / MiuixMotion 完整参数表
• 模糊与液态玻璃 — 毛玻璃与高光描边