Flutter MaterialApp 完全指南（目录）

SyYhunfhds2026/5/14大约 2 分钟

Flutter MaterialApp 完全指南

简介

本文档是 Flutter MaterialApp 的完全指南，涵盖所有配置、API、参数介绍以及最佳实践。内容分为四篇文章，建议按顺序阅读。

文档目录

序号	标题	主要内容
一	核心配置	基础属性、路由相关属性、应用信息属性、调试属性
二	主题与样式	ThemeData、ColorScheme、Material 3、组件主题配置
三	导航与路由	基本导航、命名路由、动态路由、转场动画、嵌套导航
四	本地化与调试	多语言支持、调试工具、快捷键、状态恢复

快速参考

MaterialApp 核心属性速查

MaterialApp({
  // 基础
  Key? key,
  GlobalKey<NavigatorState>? navigatorKey,
  GlobalKey<ScaffoldMessengerState>? scaffoldMessengerKey,
  Widget? home,
  TransitionBuilder? builder,

  // 路由
  Map<String, WidgetBuilder>? routes,
  String? initialRoute,
  RouteFactory? onGenerateRoute,
  RouteFactory? onUnknownRoute,
  List<NavigatorObserver>? navigatorObservers,

  // 应用信息
  String title = '',
  GenerateAppTitle? onGenerateTitle,
  Color? color,

  // 主题
  ThemeData? theme,
  ThemeData? darkTheme,
  ThemeMode themeMode = ThemeMode.system,

  // 本地化
  Locale? locale,
  Iterable<LocalizationsDelegate>? localizationsDelegates,
  Iterable<Locale> supportedLocales = const [Locale('en', 'US')],

  // 调试
  bool debugShowCheckedModeBanner = true,
  bool showPerformanceOverlay = false,
  bool checkerboardRasterCacheImages = false,
  bool checkerboardOffscreenLayers = false,
  bool showSemanticsDebugger = false,
  bool debugShowMaterialGrid = false,

  // 其他
  Map<ShortcutActivator, Intent>? shortcuts,
  Map<Type, Action>? actions,
  String? restorationScopeId,
  ScrollBehavior? scrollBehavior,
})

路由搜索优先级

1. home 属性 → 处理 '/' 路由
2. routes 表 → 处理静态路由
3. onGenerateRoute → 处理动态路由
4. onUnknownRoute → 处理未知路由（404）

ThemeData 创建方式

// 方式一：使用 ColorScheme.fromSeed（推荐）
ThemeData(
  colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
)

// 方式二：使用 colorSchemeSeed（Material 3）
ThemeData(
  colorSchemeSeed: Colors.purple,
  useMaterial3: true,
)

// 方式三：手动配置所有属性
ThemeData(
  brightness: Brightness.light,
  primaryColor: Colors.blue,
  scaffoldBackgroundColor: Colors.white,
)

本地化最小配置

MaterialApp(
  localizationsDelegates: const [
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en', 'US'),
    Locale('zh', 'CN'),
  ],
)

调试属性说明

属性	用途
`debugShowCheckedModeBanner`	控制调试模式横幅显示
`showPerformanceOverlay`	显示 GPU/CPU 性能覆盖层
`checkerboardRasterCacheImages`	棋盘格显示缓存的raster图像
`checkerboardOffscreenLayers`	棋盘格显示离屏渲染层
`showSemanticsDebugger`	显示语义调试器
`debugShowMaterialGrid`	显示 8x8 Material Design 网格

提示

所有调试属性在发布版本（Release）中自动禁用。