Adds RouterConfig to simply API (#102786)

Author: chunhtai

packages/flutter/lib/src/cupertino/app.dart

@@ -188,15 +188,19 @@ class CupertinoApp extends StatefulWidget {
        routeInformationProvider = null,
        routeInformationParser = null,
        routerDelegate = null,
-       backButtonDispatcher = null;
+       backButtonDispatcher = null,
+       routerConfig = null;
 
   /// Creates a [CupertinoApp] that uses the [Router] instead of a [Navigator].
+  ///
+  /// {@macro flutter.widgets.WidgetsApp.router}
   const CupertinoApp.router({
     super.key,
     this.routeInformationProvider,
-    required RouteInformationParser<Object> this.routeInformationParser,
-    required RouterDelegate<Object> this.routerDelegate,
+    this.routeInformationParser,
+    this.routerDelegate,
     this.backButtonDispatcher,
+    this.routerConfig,
     this.theme,
     this.builder,
     this.title = '',
@@ -217,7 +221,8 @@ class CupertinoApp extends StatefulWidget {
     this.restorationScopeId,
     this.scrollBehavior,
     this.useInheritedMediaQuery = false,
-  }) : assert(title != null),
+  }) : assert(routerDelegate != null || routerConfig != null),
+       assert(title != null),
        assert(showPerformanceOverlay != null),
        assert(checkerboardRasterCacheImages != null),
        assert(checkerboardOffscreenLayers != null),
@@ -282,6 +287,9 @@ class CupertinoApp extends StatefulWidget {
   /// {@macro flutter.widgets.widgetsApp.backButtonDispatcher}
   final BackButtonDispatcher? backButtonDispatcher;
 
+  /// {@macro flutter.widgets.widgetsApp.routerConfig}
+  final RouterConfig<Object>? routerConfig;
+
   /// {@macro flutter.widgets.widgetsApp.builder}
   final TransitionBuilder? builder;
 
@@ -478,7 +486,7 @@ class CupertinoScrollBehavior extends ScrollBehavior {
 
 class _CupertinoAppState extends State<CupertinoApp> {
   late HeroController _heroController;
-  bool get _usesRouter => widget.routerDelegate != null;
+  bool get _usesRouter => widget.routerDelegate != null || widget.routerConfig != null;
 
   @override
   void initState() {
@@ -519,8 +527,9 @@ class _CupertinoAppState extends State<CupertinoApp> {
       return WidgetsApp.router(
         key: GlobalObjectKey(this),
         routeInformationProvider: widget.routeInformationProvider,
-        routeInformationParser: widget.routeInformationParser!,
-        routerDelegate: widget.routerDelegate!,
+        routeInformationParser: widget.routeInformationParser,
+        routerDelegate: widget.routerDelegate,
+        routerConfig: widget.routerConfig,
         backButtonDispatcher: widget.backButtonDispatcher,
         builder: widget.builder,
         title: widget.title,

packages/flutter/lib/src/material/app.dart

@@ -248,15 +248,19 @@ class MaterialApp extends StatefulWidget {
        routeInformationProvider = null,
        routeInformationParser = null,
        routerDelegate = null,
-       backButtonDispatcher = null;
+       backButtonDispatcher = null,
+       routerConfig = null;
 
   /// Creates a [MaterialApp] that uses the [Router] instead of a [Navigator].
+  ///
+  /// {@macro flutter.widgets.WidgetsApp.router}
   const MaterialApp.router({
     super.key,
     this.scaffoldMessengerKey,
     this.routeInformationProvider,
-    required RouteInformationParser<Object> this.routeInformationParser,
-    required RouterDelegate<Object> this.routerDelegate,
+    this.routeInformationParser,
+    this.routerDelegate,
+    this.routerConfig,
     this.backButtonDispatcher,
     this.builder,
     this.title = '',
@@ -283,8 +287,7 @@ class MaterialApp extends StatefulWidget {
     this.restorationScopeId,
     this.scrollBehavior,
     this.useInheritedMediaQuery = false,
-  }) : assert(routeInformationParser != null),
-       assert(routerDelegate != null),
+  }) : assert(routerDelegate != null || routerConfig != null),
        assert(title != null),
        assert(debugShowMaterialGrid != null),
        assert(showPerformanceOverlay != null),
@@ -353,6 +356,9 @@ class MaterialApp extends StatefulWidget {
   /// {@macro flutter.widgets.widgetsApp.backButtonDispatcher}
   final BackButtonDispatcher? backButtonDispatcher;
 
+  /// {@macro flutter.widgets.widgetsApp.routerConfig}
+  final RouterConfig<Object>? routerConfig;
+
   /// {@macro flutter.widgets.widgetsApp.builder}
   ///
   /// Material specific features such as [showDialog] and [showMenu], and widgets
@@ -832,7 +838,7 @@ class MaterialScrollBehavior extends ScrollBehavior {
 class _MaterialAppState extends State<MaterialApp> {
   late HeroController _heroController;
 
-  bool get _usesRouter => widget.routerDelegate != null;
+  bool get _usesRouter => widget.routerDelegate != null || widget.routerConfig != null;
 
   @override
   void initState() {
@@ -925,8 +931,9 @@ class _MaterialAppState extends State<MaterialApp> {
       return WidgetsApp.router(
         key: GlobalObjectKey(this),
         routeInformationProvider: widget.routeInformationProvider,
-        routeInformationParser: widget.routeInformationParser!,
-        routerDelegate: widget.routerDelegate!,
+        routeInformationParser: widget.routeInformationParser,
+        routerDelegate: widget.routerDelegate,
+        routerConfig: widget.routerConfig,
         backButtonDispatcher: widget.backButtonDispatcher,
         builder: _materialBuilder,
         title: widget.title,

packages/flutter/lib/src/widgets/app.dart

@@ -399,15 +399,23 @@ class WidgetsApp extends StatefulWidget {
        routeInformationProvider = null,
        routeInformationParser = null,
        routerDelegate = null,
-       backButtonDispatcher = null;
+       backButtonDispatcher = null,
+       routerConfig = null;
 
   /// Creates a [WidgetsApp] that uses the [Router] instead of a [Navigator].
+  ///
+  /// {@template flutter.widgets.WidgetsApp.router}
+  /// If the [routerConfig] is provided, the other router related delegates,
+  /// [routeInformationParser], [routeInformationProvider], [routerDelegate],
+  /// and [backButtonDispatcher], must all be null.
+  /// {@endtemplate}
   WidgetsApp.router({
     super.key,
     this.routeInformationProvider,
-    required RouteInformationParser<Object> this.routeInformationParser,
-    required RouterDelegate<Object> this.routerDelegate,
-    BackButtonDispatcher? backButtonDispatcher,
+    this.routeInformationParser,
+    this.routerDelegate,
+    this.routerConfig,
+    this.backButtonDispatcher,
     this.builder,
     this.title = '',
     this.onGenerateTitle,
@@ -429,11 +437,21 @@ class WidgetsApp extends StatefulWidget {
     this.actions,
     this.restorationScopeId,
     this.useInheritedMediaQuery = false,
-  }) : assert(
-         routeInformationParser != null &&
-         routerDelegate != null,
-         'The routeInformationParser and routerDelegate cannot be null.',
-       ),
+  }) : assert((){
+         if (routerConfig != null) {
+           assert(
+             (routeInformationProvider ?? routeInformationParser ?? routerDelegate ?? backButtonDispatcher) == null,
+             'If the routerConfig is provided, all the other router delegates must not be provided',
+           );
+           return true;
+         }
+         assert(routerDelegate != null, 'Either one of routerDelegate or routerConfig must be provided');
+         assert(
+           routeInformationProvider == null || routeInformationParser != null,
+           'If routeInformationProvider is provided, routeInformationParser must also be provided',
+         );
+         return true;
+       }()),
        assert(title != null),
        assert(color != null),
        assert(supportedLocales != null && supportedLocales.isNotEmpty),
@@ -444,7 +462,6 @@ class WidgetsApp extends StatefulWidget {
        assert(debugShowCheckedModeBanner != null),
        assert(debugShowWidgetInspector != null),
        navigatorObservers = null,
-       backButtonDispatcher = backButtonDispatcher ?? RootBackButtonDispatcher(),
        navigatorKey = null,
        onGenerateRoute = null,
        pageRouteBuilder = null,
@@ -524,7 +541,7 @@ class WidgetsApp extends StatefulWidget {
   ///
   /// See also:
   ///
-  ///  * [Router.routeInformationParser]: which receives this object when this
+  ///  * [Router.routeInformationParser], which receives this object when this
   ///    widget builds the [Router].
   /// {@endtemplate}
   final RouteInformationParser<Object>? routeInformationParser;
@@ -540,7 +557,7 @@ class WidgetsApp extends StatefulWidget {
   ///
   /// See also:
   ///
-  ///  * [Router.routerDelegate]: which receives this object when this widget
+  ///  * [Router.routerDelegate], which receives this object when this widget
   ///    builds the [Router].
   /// {@endtemplate}
   final RouterDelegate<Object>? routerDelegate;
@@ -555,7 +572,7 @@ class WidgetsApp extends StatefulWidget {
   ///
   /// See also:
   ///
-  ///  * [Router.backButtonDispatcher]: which receives this object when this
+  ///  * [Router.backButtonDispatcher], which receives this object when this
   ///    widget builds the [Router].
   /// {@endtemplate}
   final BackButtonDispatcher? backButtonDispatcher;
@@ -573,11 +590,25 @@ class WidgetsApp extends StatefulWidget {
   ///
   /// See also:
   ///
-  ///  * [Router.routeInformationProvider]: which receives this object when this
+  ///  * [Router.routeInformationProvider], which receives this object when this
   ///    widget builds the [Router].
   /// {@endtemplate}
   final RouteInformationProvider? routeInformationProvider;
 
+  /// {@template flutter.widgets.widgetsApp.routerConfig}
+  /// An object to configure the underlying [Router].
+  ///
+  /// If the [routerConfig] is provided, the other router related delegates,
+  /// [routeInformationParser], [routeInformationProvider], [routerDelegate],
+  /// and [backButtonDispatcher], must all be null.
+  ///
+  /// See also:
+  ///
+  ///  * [Router.withConfig], which receives this object when this
+  ///    widget builds the [Router].
+  /// {@endtemplate}
+  final RouterConfig<Object>? routerConfig;
+
   /// {@template flutter.widgets.widgetsApp.home}
   /// The widget for the default route of the app ([Navigator.defaultRouteName],
   /// which is `/`).
@@ -1295,42 +1326,53 @@ class _WidgetsAppState extends State<WidgetsApp> with WidgetsBindingObserver {
     super.dispose();
   }
 
+  void _clearRouterResource() {
+    _defaultRouteInformationProvider?.dispose();
+    _defaultRouteInformationProvider = null;
+    _defaultBackButtonDispatcher = null;
+  }
+
+  void _clearNavigatorResource() {
+    _navigator = null;
+  }
+
   void _updateRouting({WidgetsApp? oldWidget}) {
-    if (_usesRouter) {
-      assert(!_usesNavigator);
-      _navigator = null;
-      if (oldWidget == null || oldWidget.routeInformationProvider != widget.routeInformationProvider) {
+    if (_usesRouterWithDelegates) {
+      assert(!_usesNavigator && !_usesRouterWithConfig);
+      _clearNavigatorResource();
+      if (widget.routeInformationProvider == null && widget.routeInformationParser != null) {
+        _defaultRouteInformationProvider ??= PlatformRouteInformationProvider(
+          initialRouteInformation: RouteInformation(
+            location: _initialRouteName,
+          ),
+        );
+      } else {
         _defaultRouteInformationProvider?.dispose();
         _defaultRouteInformationProvider = null;
-        if (widget.routeInformationProvider == null) {
-          _defaultRouteInformationProvider = PlatformRouteInformationProvider(
-            initialRouteInformation: RouteInformation(
-              location: _initialRouteName,
-            ),
-          );
-        }
       }
+      if (widget.backButtonDispatcher == null) {
+        _defaultBackButtonDispatcher ??= RootBackButtonDispatcher();
+      }
+
     } else if (_usesNavigator) {
-      assert(!_usesRouter);
-      _defaultRouteInformationProvider?.dispose();
-      _defaultRouteInformationProvider = null;
+      assert(!_usesRouterWithDelegates && !_usesRouterWithConfig);
+      _clearRouterResource();
       if (_navigator == null || widget.navigatorKey != oldWidget!.navigatorKey) {
         _navigator = widget.navigatorKey ?? GlobalObjectKey<NavigatorState>(this);
       }
       assert(_navigator != null);
     } else {
-      assert(widget.builder != null);
-      assert(!_usesRouter);
-      assert(!_usesNavigator);
-      _navigator = null;
-      _defaultRouteInformationProvider?.dispose();
-      _defaultRouteInformationProvider = null;
+      assert(widget.builder != null || _usesRouterWithConfig);
+      assert(!_usesRouterWithDelegates && !_usesNavigator);
+      _clearRouterResource();
+      _clearNavigatorResource();
     }
     // If we use a navigator, we have a navigator key.
     assert(_usesNavigator == (_navigator != null));
   }
 
-  bool get _usesRouter => widget.routerDelegate != null;
+  bool get _usesRouterWithDelegates => widget.routerDelegate != null;
+  bool get _usesRouterWithConfig => widget.routerConfig != null;
   bool get _usesNavigator => widget.home != null
       || (widget.routes?.isNotEmpty ?? false)
       || widget.onGenerateRoute != null
@@ -1340,6 +1382,8 @@ class _WidgetsAppState extends State<WidgetsApp> with WidgetsBindingObserver {
 
   RouteInformationProvider? get _effectiveRouteInformationProvider => widget.routeInformationProvider ?? _defaultRouteInformationProvider;
   PlatformRouteInformationProvider? _defaultRouteInformationProvider;
+  BackButtonDispatcher get _effectiveBackButtonDispatcher => widget.backButtonDispatcher ?? _defaultBackButtonDispatcher!;
+  RootBackButtonDispatcher? _defaultBackButtonDispatcher;
 
   // NAVIGATOR
 
@@ -1409,7 +1453,7 @@ class _WidgetsAppState extends State<WidgetsApp> with WidgetsBindingObserver {
     assert(mounted);
     // The back button dispatcher should handle the pop route if we use a
     // router.
-    if (_usesRouter)
+    if (_usesRouterWithDelegates)
       return false;
 
     final NavigatorState? navigator = _navigator?.currentState;
@@ -1423,7 +1467,7 @@ class _WidgetsAppState extends State<WidgetsApp> with WidgetsBindingObserver {
     assert(mounted);
     // The route name provider should handle the push route if we uses a
     // router.
-    if (_usesRouter)
+    if (_usesRouterWithDelegates)
       return false;
 
     final NavigatorState? navigator = _navigator?.currentState;
@@ -1535,14 +1579,13 @@ class _WidgetsAppState extends State<WidgetsApp> with WidgetsBindingObserver {
   @override
   Widget build(BuildContext context) {
     Widget? routing;
-    if (_usesRouter) {
-      assert(_effectiveRouteInformationProvider != null);
+    if (_usesRouterWithDelegates) {
       routing = Router<Object>(
         restorationScopeId: 'router',
         routeInformationProvider: _effectiveRouteInformationProvider,
         routeInformationParser: widget.routeInformationParser,
         routerDelegate: widget.routerDelegate!,
-        backButtonDispatcher: widget.backButtonDispatcher,
+        backButtonDispatcher: _effectiveBackButtonDispatcher,
       );
     } else if (_usesNavigator) {
       assert(_navigator != null);
@@ -1560,6 +1603,11 @@ class _WidgetsAppState extends State<WidgetsApp> with WidgetsBindingObserver {
         observers: widget.navigatorObservers!,
         reportsRouteUpdateToEngine: true,
       );
+    } else if (_usesRouterWithConfig) {
+      routing = Router<Object>.withConfig(
+        restorationScopeId: 'router',
+        config: widget.routerConfig!,
+      );
     }
 
     Widget result;