Flutter 组件之 MaterialApp

1、介绍

MaterialApp 是 flutter 中提供入口的一个类。

2、属性介绍

MaterialApp MaterialApp({
  Key? key,
  GlobalKey<NavigatorState>? navigatorKey,    // 导航键
  GlobalKey<ScaffoldMessengerState>? scaffoldMessengerKey,    //主要是管理 Scaffolds
  Widget? home,    // 应用程序默认路由的小部件,用来定义当前应用打开的时候，所显示的界面
  Map<String, Widget Function(BuildContext)> routes = const <String, WidgetBuilder>{},    // 应用程序的顶级路由表
  String? initialRoute,    // 如果构建了导航器，则显示的第一个路由的名称
  Route<dynamic>? Function(RouteSettings)? onGenerateRoute,    // 应用程序导航到指定路由时使用的路由生成器回调
  List<Route<dynamic>> Function(String)? onGenerateInitialRoutes,    //生成初始化路由
  Route<dynamic>? Function(RouteSettings)? onUnknownRoute,    // 当 onGenerateRoute 无法生成路由(initialRoute除外)时调用
  List<NavigatorObserver> navigatorObservers = const <NavigatorObserver>[],    // 为该应用程序创建的导航器的观察者列表
  Widget Function(BuildContext, Widget?)? builder,    // 应用程序的顶级路由表
  String title = '',    // 设备用于为用户识别应用程序的单行描述
  String Function(BuildContext)? onGenerateTitle,    // 如果非空，则调用此回调函数来生成应用程序的标题字符串，否则使用标题。
  Color? color,    // 在操作系统界面中应用程序使用的主色。
  ThemeData? theme,    // 应用程序小部件使用的颜色。
  ThemeData? darkTheme,    //暗黑模式主题颜色
  ThemeData? highContrastTheme,    //系统请求“高对比度”使用的主题
  ThemeData? highContrastDarkTheme,    //系统请求“高对比度”暗黑模式下使用的主题颜色
  ThemeMode? themeMode = ThemeMode.system,    //使用哪种模式的主题（默认跟随系统）
  Duration themeAnimationDuration = kThemeAnimationDuration,    //主体动画持续时间
  Curve themeAnimationCurve = Curves.linear,    //主体动画曲线
  Locale? locale,    // 此应用程序本地化小部件的初始区域设置基于此值。
  Iterable<LocalizationsDelegate<dynamic>>? localizationsDelegates,    // 这个应用程序本地化小部件的委托。
  Locale? Function(List<Locale>?, Iterable<Locale>)? localeListResolutionCallback,  // 这个回调负责在应用程序启动时以及用户更改设备的区域设置时选择应用程序的区域设置。
  Locale? Function(Locale?, Iterable<Locale>)? localeResolutionCallback,    //监听系统语言切换事件
  Iterable<Locale> supportedLocales = const <Locale>[Locale('en', 'US')],  // 此应用程序已本地化的地区列表
  bool debugShowMaterialGrid = false,  // 打开绘制基线网格材质应用程序的网格纸覆盖
  bool showPerformanceOverlay = false,  // 打开性能叠加
  bool checkerboardRasterCacheImages = false,  // 打开栅格缓存图像的棋盘格
  bool checkerboardOffscreenLayers = false,    // 打开渲染到屏幕外位图的图层的棋盘格
  bool showSemanticsDebugger = false,    // 打开显示框架报告的可访问性信息的覆盖
  bool debugShowCheckedModeBanner = true,      // 在选中模式下打开一个小的“DEBUG”横幅，表示应用程序处于选中模式
  Map<ShortcutActivator, Intent>? shortcuts,    //应用程序意图的键盘快捷键的默认映射。
  Map<Type, Action<Intent>>? actions,    //包含和定义用户操作的映射
  String? restorationScopeId,    //应用程序状态恢复的标识符
  ScrollBehavior? scrollBehavior,    //统一滚动行为设置，设置后子组件将返回对应的滚动行为
  bool useInheritedMediaQuery = false,    //如果为true，则将使用继承的 MediaQuery。如果它不可用或者是错误的，那么将从窗口构建一个。默认为false。
})

3、使用示例

navigatorKey
navigatorKey 相当于 Navigator.of(context) ，如果应用程序想实现无 context 跳转，那么可以通过设置该 key, 通过 navigatorKey.currentState.overlay.context 获取全局 context。

GlobalKey<NavigatorState> _navigatorKey = GlobalKey();

MaterialApp(
  navigatorKey: _navigatorKey,
);

scaffoldMessengerKey
scaffoldMessengerKey 主要是管理 Scaffolds，可以实现无 context 调用 snack bars。

GlobalKey<ScaffoldMessengerState> _scaffoldKey = GlobalKey();

MaterialApp(
  scaffoldMessengerKey: _scaffoldKey,
);

_scaffoldKey.currentState.showSnackBar(SnackBar(content: Text("show SnackBar")));

home
程序进入后的第一个界面，传入一个 Widget。

MaterialApp(
  home: Scaffold(...),
);

routes
生成路由表，以键值对形式传入 key 为路由名字， value 为对应的 Widget。

MaterialApp(
  routes: {
    "/home": (_) => Home(),
    "/my": (_) => My()
    //....
  },
);

initialRoute
初始路由，如果设置了该参数并且在 routes 找到了对应的key，将会展示对应的 Widget ，否则展示 home。

 MaterialApp(
   routes: {
     "/home": (_) => Home(),
     "/my": (_) => My()
   },
   initialRoute: "/home",
 )

onGenerateRoute
当跳转路由时，如果在 routes 找不到对应的 key ，会执行该回调，会调用会返回一个 RouteSettings ，该对象中有 name 路由名称、 arguments 路由参数。

 MaterialApp(
   routes: {
     "/home": (_) => Home(),
     "/my": (_) => My()
     },
   initialRoute: "/home",
   onGenerateRoute: (setting) {
     // 这里可以做进一步的逻辑处理
     return MaterialPageRoute(builder: (_) => Home());
   },
)

onGenerateInitialRoutes
如果提供了 initialRoute ，则用于生成初始路由的路由生成器回调，如果未设置此属性，则底层 Navigator.onGenerateInitialRoutes 将默认为 Navigator.defaultGenerateInitialRoutes。

MaterialApp(
  initialRoute: "/home",
  onGenerateInitialRoutes: (initialRoute) {
    return [
      MaterialPageRoute(builder: (_) => Home()),
      MaterialPageRoute(builder: (_) => My()),
    ];
  }
 )

onUnknownRoute
效果和 onGenerateRoute 一样，只是先走 onGenerateRoute ，如果无法生成路由时则在调用 onUnknownRoute 。

MaterialApp(
   routes: {
     "/home": (_) => Home(),
     "/my": (_) => My()
     },
   initialRoute: "/home",
   onGenerateRoute: (setting) {
     return null;
   },
   onUnknownRoute: (setting) {
     return MaterialPageRoute(builder: (_) => Home());
   },
)

navigatorObservers
路由监听器，主要是就是监听页面路由堆栈的变化，当页面进行 push pop remove replace 等操作时会进行监听。

MaterialApp(
    navigatorObservers: [
    MyObserver()
  ],
)
  
 class MyObserver extends NavigatorObserver {
  @override
  void didPush(Route route, Route previousRoute) {
    print(route);
    print(previousRoute);
    super.didPush(route, previousRoute);
  }
}

builder
当构建 Widget 前调用，主要用于字体大小、主题颜色等配置

MaterialApp(
   routes: {
     "/home": (_) => Home(),
     "/my": (_) => My()
     },
   initialRoute: "/home",
   onGenerateRoute: (setting) {
     return null;
   },
   onUnknownRoute: (setting) {
     return MaterialPageRoute(builder: (_) => Home());
   },
     builder: (_, child) {
     return Scaffold(appBar: AppBar(title: Text("build")), body: child,);
   },
)

title
Android：任务管理器的程序快照之上
IOS: 程序切换管理器中

 MaterialApp(
   title: 'Flutter应用',
 );

onGenerateTitle
如果非空，则调用此回调函数以生成应用程序的标题字符串，否则会使用 title 。每次重建页面是该方法就会回调执行。

MaterialApp(
   title: 'Flutter应用',
   onGenerateTitle: (_) {
     return "我的天";
   },
 );

color
设置该值的在程序切换时应用图标的背景颜色，当应用图标为透明时。

MaterialApp(
  color: Colors.blue,
)

theme
应用程序的主题颜色。 themeMode 将控制将使用哪个主题。默认值是 ThemeData.light()。

MaterialApp(
  theme: ThemeData(
    // 主要颜色
    primaryColor: Colors.red
  ),
)

darkTheme
应用程序深色主题颜色

MaterialApp(
  theme: ThemeData(
    // 主要颜色
    primaryColor: Colors.red
  ),
)

highContrastTheme
当系统请求“高对比度”时使用的 ThemeData ，当该值为空时会用 theme 应用该主题

MaterialApp(
  highContrastTheme: ThemeData(
    primaryColor: Colors.pink
  ),
)

highContrastDarkTheme
当系统再暗黑模式下请求“高对比度”时使用的 ThemeData ，当该值为空时会用 darkTheme 应用该主题。

MaterialApp(
  highContrastDarkTheme: ThemeData(
    primaryColor: Colors.green
  ),
)

themeMode
白天模式和暗黑模式模式切换，默认值为 ThemeMode.system

MaterialApp(
  themeMode: ThemeMode.dark
)

locale
主要用于语言切换时，如果为 null 时使用系统区域

MaterialApp(
  locale: Locale('zh', 'CN') // 中文简体
)

localizationsDelegates
本地化委托

MaterialApp(
  locale: Locale('zh', 'CN') // 中文简体
  localizationsDelegates: [
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
  ],
)

supportedLocales
当前应用支持的 Locale 列表

MaterialApp(
  locale: Locale('zh', 'CN'), // 中文简体
  supportedLocales: [
    Locale('en', 'US'), //美国英语
    Locale("zh", 'CN'), //中文简体
  ]
)

localeListResolutionCallback
监听系统语言切换事件，一些安卓系统特性，可设置多语言列表，默认以第一个列表为默认语言

MaterialApp(
  locale: Locale('zh', 'CN'), // 中文简体
  supportedLocales: [
    Locale('en', 'US'), //美国英语
    Locale("zh", 'CN'), //中文简体
  ],
  localeListResolutionCallback: (List<Locale> locales, Iterable<Locale> supportedLocales) {
    // 系统切换语言时调用
    return Locale("zh", 'CN');
  },
)

localeResolutionCallback
监听系统语言切换事件

MaterialApp(
  locale: Locale('zh', 'CN'), // 中文简体
  supportedLocales: [
    Locale('en', 'US'), //美国英语
    Locale("zh", 'CN'), //中文简体
  ],
  localeResolutionCallback: (Locale locale, Iterable<Locale> supportedLocales) {
    return Locale("zh", 'CN');
  },
)

debugShowMaterialGrid
在 debug 模式下展示基线网格

MaterialApp(
  debugShowMaterialGrid: true
)

showPerformanceOverlay
显示性能叠加，开启此模式主要用于性能测试

MaterialApp(
  showPerformanceOverlay: true
)

checkerboardRasterCacheImages
打开栅格缓存图像的棋盘格

MaterialApp(
  checkerboardRasterCacheImages: true
)

checkerboardOffscreenLayers
打开渲染到屏幕外位图的层的棋盘格

MaterialApp(
  checkerboardOffscreenLayers: true
)

showSemanticsDebugger
打开显示可访问性信息的叠加层，展示组件之间的关系、占位大小

MaterialApp(
  showSemanticsDebugger: true
)

debugShowCheckedModeBanner
调试显示检查模式横幅

MaterialApp(
  debugShowCheckedModeBanner: false
)

shortcuts以及actions
shortcuts 和 actions 是将物理键盘事件绑定到用户界面中的操作。

restorationScopeId
定义一个应用程序状态恢复的标识符，提供标识符会将 RootRestorationScope 插入 widget 层次结构，从而为后代 widget 启用状态恢复。还可以通过标识符使 WidgetsApp 构建的导航器恢复其状态（即恢复活动路由的历史堆栈）。

scrollBehavior
统一滚动行为设置，设置后子组件将返回对应的滚动行为

MaterialApp(
  scrollBehavior: ScrollBehaviorModified()
)
  
class ScrollBehaviorModified extends ScrollBehavior {
  const ScrollBehaviorModified();
  @override
  ScrollPhysics getScrollPhysics(BuildContext context) {
    switch (getPlatform(context)) {
      case TargetPlatform.iOS:
      case TargetPlatform.macOS:
      case TargetPlatform.android:
        return const BouncingScrollPhysics();
      case TargetPlatform.fuchsia:
      case TargetPlatform.linux:
      case TargetPlatform.windows:
        return const ClampingScrollPhysics();
    }
    return null;
  }
}