当前版本 Flutter 3.19.5

前言

当谈论Flutter应用程序时，MaterialApp是不可或缺的一个部分。它是构建Flutter应用程序的基础，可以理解为整个应用程序的“外壳”。MaterialApp提供了许多配置选项，用于定义应用程序的整体外观和行为。它可以决定应用程序的标题、主题颜色、初始页面、路由导航等方面。

简单来说，MaterialApp就像是一个包含了所有必要元素的“容器”，帮助我们构建一个漂亮、流畅的Flutter应用程序。它遵循Material Design规范，为我们提供了一套统一的设计风格和用户体验，使得我们的应用程序看起来更加现代化和专业化。

以下是一个基本的使用示例

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      title: 'Flutter Demo',
      debugShowCheckedModeBanner: false,
      home: MyHomePage(),
    );
  }
}


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

  @override
  MyHomePageState createState() => MyHomePageState();
}

class MyHomePageState extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('this is a appBar'),
        backgroundColor: Colors.green,
      ),
    );
  }
}

MaterialApp API

属性

属性一览

• actions: 定义用户操作的映射
• backButtonDispatcher: 是否处理 Android 后退按钮
• builder: 应用程序的构建器，用于构建根部件之前执行一些操作
• checkerboardOffscreenLayers: 打开渲染到屏幕外位图的层的棋盘格
• checkerboardRasterCacheImages: 打开栅格缓存图像的棋盘格
• color: 程序切换时应用图标背景颜色（仅安卓有效）
• darkTheme: 暗模式下的主题样式
• debugShowCheckedModeBanner: 是否显示调试模式下的横幅
• debugShowMaterialGrid: 绘制基线网格叠加层（仅debug模式）
• highContrastDarkTheme: 系统请求“高对比度”暗黑模式下使用的主题颜色
• highContrastTheme: 系统请求“高对比度”使用的主题
• home: 应用程序的首页部件
• initialRoute: 应用程序的初始路由
• locale: 本地化
• localeListResolutionCallback: 失败或未提供设备的语言环境
• localeResolutionCallback: 负责计算语言环境
• localizationsDelegates: 本地化代理
• navigatorKey: 应用程序的导航键，用于在整个应用程序中管理导航状态
• navigatorObservers: 导航观察器的列表，用于监听导航事件
• onGenerateInitialRoutes: 生成初始化路由
• onGenerateRoute: 自动生成路由的回调函数
• onGenerateTitle: 程序切换时生成标题字符串
• onNavigationNotification: 接收 NavigationNotification 时使用的回调
• onUnknownRoute: 未知路由的回调函数
• restorationScopeId: 应用程序状态恢复的标识符
• routeInformationParser
• routeInformationProvider
• routerConfig
• routerDelegate
• routes: 应用程序的路由映射表，用于页面导航
• scaffoldMessengerKey: Scaffold的key
• scrollBehavior: 可滚动小部件的行为方式
• shortcuts: 应用程序意图的键盘快捷键的默认映射
• showPerformanceOverlay: 显示性能叠加
• showSemanticsDebugger: 打开显示可访问性信息的叠加层
• supportedLocales: 支持的本地化地区列表
• theme: 应用程序的整体主题样式
• themeAnimationCurve
• themeAnimationDuration
• themeAnimationStyle
• themeMode: 应用程序的主题模式，可以是亮色、暗色或跟随系统
• title: 应用程序的标题，显示在任务管理器中等位置

backButtonDispatcher: 是否处理 Android 后退按钮

实现

final BackButtonDispatcher? backButtonDispatcher;

示例

MaterialApp(
  backButtonDispatcher: RootBackButtonDispatcher(),
)

builder: 应用程序的构建器，用于构建根部件之前执行一些操作

实现

final TransitionBuilder? builder;

示例

MaterialApp(
  builder: (_, child) {
    return Scaffold(appBar: AppBar(title: Text("build")), body: child,);
  },
)

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

setlayer是Canvas里的操作，非常耗性能，所以要尽量避免这个操作。

使用了saveLayer的图像会显示为棋盘格式并随着页面刷新而闪烁

实现

final bool checkerboardOffscreenLayers;

示例

MaterialApp(
  checkerboardOffscreenLayers: true,
)

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

一个拖慢GPU渲染速度的是没有给静态图像做缓存，导致每次build都会重新绘制。

我们可以把静态图像加到RepaintBoundry中，引擎会自动判断图像是否复杂到需要repaint boundary。

实现

final bool checkerboardRasterCacheImages;

示例

MaterialApp(
  checkerboardRasterCacheImages: true,
)

color: 程序切换时应用图标背景颜色（仅安卓有效）

实现

final Color? color;

示例

MaterialApp(
  color: Color.red,
)

darkTheme: 暗模式下的主题样式

实现

final ThemeData? darkTheme;

示例

MaterialApp(
  darkTheme: ThemeData(
    colorScheme: ColorScheme.dark(
      background: Colors.pink,
    ),
  ),
  themeMode: ThemeMode.dark,
)

debugShowCheckedModeBanner: 是否显示调试模式下的横幅

实现

final bool debugShowCheckedModeBanner;

示例

MaterialApp(
  debugShowCheckedModeBanner: false,
)

debugShowMaterialGrid: 绘制基线网格叠加层（仅debug模式）

实现

final bool debugShowMaterialGrid;

示例

MaterialApp(
  debugShowMaterialGrid: true,
)

highContrastDarkTheme: 系统请求“高对比度”暗黑模式下使用的主题颜色

实现

final ThemeData? highContrastDarkTheme;

示例

MaterialApp(
  highContrastDarkTheme: ThemeData(
    colorScheme: ColorScheme.dark(
      background: Colors.pink,
    )
  ),
)

highContrastTheme: 系统请求“高对比度”使用的主题

实现

final ThemeData? highContrastTheme;

示例

MaterialApp(
  highContrastTheme: ThemeData(
    colorScheme: ColorScheme.dark(
      background: Colors.pink,
    )
  ),
)

home: 应用程序的首页部件

应用程序正常启动时首先显示的路由，除非指定了initialRoute,如果指定了home ，则路由不得包含 /，因为home会取代它的位置。

实现

final Widget? home;

示例

MaterialApp(
  home: MyHomePage(), // 设置应用程序的首页为自定义的MyHomePage部件
)

initialRoute: 应用程序的初始路由

实现

final String? initialRoute;

示例

MaterialApp(
  initialRoute: 'default',
  routes: {
    'default': (context) => const MyHomePage(title: 'Flutter Demo'),
  },
)

navigatorKey: 应用程序的导航键，用于在整个应用程序中管理导航状态

实现

final GlobalKey? navigatorKey;

示例

final globalNavigatorKey = GlobalKey();

MaterialApp(
  navigatorKey: globalNavigatorKey,
)

GestureDetector(
  onTap: () {
    globalNavigatorKey.currentState?.pushNamed('aaa');
  },
  child: Text('hahah'),
)

navigatorObservers: 导航观察器的列表，用于监听导航事件

实现

final List? navigatorObservers;

示例

final MyTransitionObserver analyticsObserver = MyTransitionObserver();

MaterialApp(
  navigatorObservers: [
    analyticsObserver
  ],
)

class MyTransitionObserver extends RouteObserver> {
  @override
  void didPush(Route route, Route? previousRoute) {
    print('didPush ${route.settings.name}');
  }

  @override
  void didReplace({Route? newRoute, Route? oldRoute}) { }

  @override
  void didPop(Route route, Route? previousRoute) { }

  @override
  void didRemove(Route route, Route? previousRoute) { }

  @override
  void didStartUserGesture(Route route, Route? previousRoute) { }

  @override
  void didStopUserGesture() { }
}

onGenerateInitialRoutes: 生成初始化路由

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

实现

final InitialRouteListFactory? onGenerateInitialRoutes;

示例

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

onGenerateRoute: 自动生成路由的回调函数

可以通过 onGenerateRoute() 函数提取参数，然后把参数传递给组件。

也可以在组件中通过 ModalRoute.of(context)!.settings.arguments 来获取参数

实现

final RouteFactory? onGenerateRoute;

示例

MaterialApp(
  onGenerateRoute: (settings) {
    if (settings.name == PassArgumentsScreen.routeName) {
      final args = settings.arguments as ScreenArguments;

      return MaterialPageRoute(
        builder: (context) {
          return PassArgumentsScreen(
            title: args.title,
            message: args.message,
          );
        },
      );
    }
  }
)

onGenerateTitle: 程序切换时生成标题字符串

实现

final GenerateAppTitle? onGenerateTitle;

示例

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

onUnknownRoute: 未知路由的回调函数

实现

final RouteFactory? onUnknownRoute;

示例

MaterialApp(
  onUnknownRoute: (RouteSettings settings) {
    return MaterialPageRoute(builder: (_) => const MyHomePage(title: '404'));
  }
)

routes: 应用程序的路由映射表，用于页面导航

实现

final Map? routes;

示例

MaterialApp(
  initialRoute: 'default',
  routes: {
    'default': (context) => const MyHomePage(title: 'Flutter Demo'),
  },
)

scaffoldMessengerKey: Scaffold的key

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

实现

final GlobalKey? scaffoldMessengerKey;

示例

GlobalKey _scaffoldKey = GlobalKey();

MaterialApp(
  scaffoldMessengerKey: _scaffoldKey,
);

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

scrollBehavior: 可滚动小部件的行为方式

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

实现

final ScrollBehavior? 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;
  }
}

showPerformanceOverlay: 显示性能叠加

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

实现

final bool showPerformanceOverlay;

示例

MaterialApp(
  showPerformanceOverlay: true
)

showSemanticsDebugger: 打开显示可访问性信息的叠加层

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

实现

final bool showSemanticsDebugger;

示例

MaterialApp(
  showSemanticsDebugger: true
)

supportedLocales: 支持的本地化地区列表

实现

final Iterable supportedLocales;

示例

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

theme: 应用程序的整体主题样式

此应用程序的默认视觉属性，例如颜色、字体和形状。

还可以指定第二个darkTheme ThemeData值，用于提供用户界面的深色版本。如果提供了darkTheme ，则themeMode将控制使用哪个主题。

实现

final ThemeData? theme;

示例

MaterialApp(
  theme: ThemeData(
    fontFamily: 'Roboto', // 设置字体样式为Roboto
    appBarTheme: AppBarTheme( // 设置AppBar样式
      backgroundColor: Colors.blue, // 设置AppBar的背景色
      elevation: 0, // 设置AppBar的阴影高度为0
      textTheme: TextTheme( // 设置AppBar的文本样式
        headline6: TextStyle(fontSize: 20, fontWeight: FontWeight.bold, color: Colors.white), // 设置标题文本样式
      ),
    ),
  ),
)

完整的ThemeData用法详解

themeMode: 应用程序的主题模式，可以是亮色、暗色或跟随系统

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

实现

final ThemeMode? themeMode;

示例

MaterialApp(
  themeMode: ThemeMode.dark
)

title: 应用程序的标题，显示在任务管理器中等位置

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

实现

final String title;

示例

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

...完...