快速开始

本页带你在五分钟内跑起第一个 Miuix 页面：接入主题 → 搭建脚手架 → 使用组件。

最小示例

在应用根部包一层 MiuixSystemTheme（自动跟随系统明暗模式），组件即可通过 MiuixTheme.of(context) 取用配色与文本样式：

import 'package:flutter/material.dart';
import 'package:flutter_miuix/miuix.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    // MiuixSystemTheme 自动跟随系统明暗模式，并应用 Miuix 配色
    return MiuixSystemTheme(
      child: Builder(
        builder: (context) {
          final theme = MiuixTheme.of(context);
          return MaterialApp(
            debugShowCheckedModeBanner: false,
            theme: ThemeData(
              useMaterial3: true,
              colorScheme: ColorScheme.fromSeed(
                seedColor: theme.colors.primary,
                brightness: theme.brightness,
              ),
              brightness: theme.brightness,
            ),
            home: const HomePage(),
          );
        },
      ),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return MiuixScaffold(
      topBar: const MiuixTopAppBar(title: 'flutter_miuix'),
      content: (padding) => Center(
        child: MiuixButton(
          onPressed: () {},
          child: const MiuixText('Hello Miuix'),
        ),
      ),
    );
  }
}

为什么还要 MaterialApp？

flutter_miuix 的组件只依赖 MiuixTheme，不强制要求 Material。但实际应用通常仍需要 MaterialApp 提供路由、Overlay、文本方向等基础设施。示例中用 ColorScheme.fromSeed 把 Miuix 主色桥接给 Material 组件，让两边观感一致。

理解 MiuixScaffold

MiuixScaffold 是页面骨架，负责组织顶栏、底栏、悬浮按钮、Snackbar 与弹层：

MiuixScaffold(
  topBar: const MiuixTopAppBar(title: '标题'),   // 通常是 MiuixTopAppBar
  bottomBar: ...,                                // 通常是 MiuixNavigationBar
  floatingActionButton: ...,                     // 悬浮操作按钮
  snackbarHost: ...,                             // MiuixSnackbarHost
  content: (padding) => ListView(
    padding: padding,                            // ⚠️ 记得把 padding 应用到内容根部
    children: [...],
  ),
)

content 是一个 builder，参数 padding 包含了顶栏 / 底栏 / 系统安全区所需的内边距——务必应用到内容根部（如 ListView.padding 或 Padding），否则内容会被顶栏遮挡。这样设计是为了让内容可以滚动到毛玻璃顶栏之下，形成透出效果。

常用组件速览

// 开关
MiuixSwitch(
  value: isOn,
  onChanged: (v) => setState(() => isOn = v),
)

// 复选框（支持 true / false / null 半选三态）
MiuixCheckbox(
  value: checked,
  onChanged: (v) => setState(() => checked = v ?? false),
)

// 文本输入框（浮动标签 + 聚焦边框动画）
MiuixTextField(
  label: '用户名',
  onChanged: (v) {},
)

// 毛玻璃顶栏——一行开启液态玻璃
MiuixTopAppBar(title: '标题', blurred: true)

显示 Snackbar

创建一个 MiuixSnackbarHostState，把 MiuixSnackbarHost 挂到脚手架上，即可在任意位置入队消息：

class HomePage extends StatefulWidget {
  const HomePage({super.key});

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  final _snackbarHost = MiuixSnackbarHostState();

  @override
  Widget build(BuildContext context) {
    return MiuixScaffold(
      topBar: const MiuixTopAppBar(title: 'Snackbar 示例'),
      snackbarHost: MiuixSnackbarHost(state: _snackbarHost),
      content: (padding) => Center(
        child: MiuixButton(
          onPressed: () {
            _snackbarHost.showSnackbar('已保存', actionLabel: '撤销');
          },
          child: const MiuixText('显示 Snackbar'),
        ),
      ),
    );
  }
}

文档约定

阅读组件文档时的几个约定：

• 参数表中默认值列写「必填」表示该参数为 required（无默认值，必须传入）。
• 默认值形如 MiuixXxxDefaults.yyy 表示取自该组件的 Defaults 常量，具体数值见各组件的 Defaults 表格。
• 所有组件的尺寸、圆角、内边距等均可通过构造参数自定义，且都带有与原版一致的默认值。
• 颜色走 MiuixColors 语义角色，文本走 MiuixTextStyles 预设，随主题自动明暗切换。
• 所有示例均可直接编译运行，仅展示最常用参数；完整参数见各组件表格。

完整示例工程

仓库的 example/ 目录包含 14 个分类的演示页面：按钮、输入、菜单、显示、列表项、选择器、反馈、浮层、导航、侧边导航、实用工具、主题、模糊、基础。

下一步

• 主题定制 — 自定义配色、强制明暗、Monet 动态取色
• 输入组件 — 从 TextField 与 Switch 开始浏览组件 API