[go_router] When replace is called, reuse the same key when possible

packages/go_router/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 6.4.0
+
+- Adds `replace` method to that replaces the current route with a new one and keeps the same page key. This is useful for when you want to update the query params without changing the page key ([#115902]https://github.com/flutter/flutter/issues/115902).
+
 ## 6.3.0
 
 - Aligns Dart and Flutter SDK constraints.

packages/go_router/lib/src/delegate.dart

@@ -50,7 +50,7 @@ class GoRouterDelegate extends RouterDelegate<RouteMatchList>
   ///
   /// This is used to generate a unique key for each route.
   ///
-  /// For example, it would could be equal to:
+  /// For example, it could be equal to:
   /// ```dart
   /// {
   ///   'family': 1,
@@ -75,15 +75,14 @@ class GoRouterDelegate extends RouterDelegate<RouteMatchList>
     return false;
   }
 
-  /// Pushes the given location onto the page stack
-  void push(RouteMatchList matches) {
-    assert(matches.last.route is! ShellRoute);
-
+  ValueKey<String> _getNewKeyForPath(String path) {
     // Remap the pageKey to allow any number of the same page on the stack
-    final int count = (_pushCounts[matches.fullpath] ?? 0) + 1;
-    _pushCounts[matches.fullpath] = count;
-    final ValueKey<String> pageKey =
-        ValueKey<String>('${matches.fullpath}-p$count');
+    final int count = (_pushCounts[path] ?? -1) + 1;
+    _pushCounts[path] = count;
+    return ValueKey<String>('$path-p$count');
+  }
+
+  void _push(RouteMatchList matches, ValueKey<String> pageKey) {
     final ImperativeRouteMatch newPageKeyMatch = ImperativeRouteMatch(
       route: matches.last.route,
       subloc: matches.last.subloc,
@@ -94,6 +93,21 @@ class GoRouterDelegate extends RouterDelegate<RouteMatchList>
     );
 
     _matchList.push(newPageKeyMatch);
+  }
+
+  /// Pushes the given location onto the page stack.
+  ///
+  /// See also:
+  /// * [pushReplacement] which replaces the top-most page of the page stack and
+  ///   always use a new page key.
+  /// * [replace] which replaces the top-most page of the page stack but treats
+  ///   it as the same page. The page key will be reused. This will preserve the
+  ///   state and not run any page animation.
+  void push(RouteMatchList matches) {
+    assert(matches.last.route is! ShellRoute);
+
+    final ValueKey<String> pageKey = _getNewKeyForPath(matches.fullpath);
+    _push(matches, pageKey);
     notifyListeners();
   }
 
@@ -148,13 +162,38 @@ class GoRouterDelegate extends RouterDelegate<RouteMatchList>
 
   /// Replaces the top-most page of the page stack with the given one.
   ///
+  /// The page key of the new page will always be different from the old one.
+  ///
   /// See also:
   /// * [push] which pushes the given location onto the page stack.
+  /// * [replace] which replaces the top-most page of the page stack but treats
+  ///   it as the same page. The page key will be reused. This will preserve the
+  ///   state and not run any page animation.
   void pushReplacement(RouteMatchList matches) {
+    assert(matches.last.route is! ShellRoute);
     _matchList.remove(_matchList.last);
     push(matches); // [push] will notify the listeners.
   }
 
+  /// Replaces the top-most page of the page stack with the given one but treats
+  /// it as the same page.
+  ///
+  /// The page key will be reused. This will preserve the state and not run any
+  /// page animation.
+  ///
+  /// See also:
+  /// * [push] which pushes the given location onto the page stack.
+  /// * [pushReplacement] which replaces the top-most page of the page stack but
+  ///   always uses a new page key.
+  void replace(RouteMatchList matches) {
+    assert(matches.last.route is! ShellRoute);
+    final RouteMatch routeMatch = _matchList.last;
+    final ValueKey<String> pageKey = routeMatch.pageKey;
+    _matchList.remove(routeMatch);
+    _push(matches, pageKey);
+    notifyListeners();
+  }
+
   /// For internal use; visible for testing only.
   @visibleForTesting
   RouteMatchList get matches => _matchList;

packages/go_router/lib/src/misc/extensions.dart

@@ -37,6 +37,13 @@ extension GoRouterHelper on BuildContext {
       );
 
   /// Push a location onto the page stack.
+  ///
+  /// See also:
+  /// * [pushReplacement] which replaces the top-most page of the page stack and
+  ///   always uses a new page key.
+  /// * [replace] which replaces the top-most page of the page stack but treats
+  ///   it as the same page. The page key will be reused. This will preserve the
+  ///   state and not run any page animation.
   void push(String location, {Object? extra}) =>
       GoRouter.of(this).push(location, extra: extra);
 
@@ -66,7 +73,10 @@ extension GoRouterHelper on BuildContext {
   ///
   /// See also:
   /// * [go] which navigates to the location.
-  /// * [push] which pushes the location onto the page stack.
+  /// * [push] which pushes the given location onto the page stack.
+  /// * [replace] which replaces the top-most page of the page stack but treats
+  ///   it as the same page. The page key will be reused. This will preserve the
+  ///   state and not run any page animation.
   void pushReplacement(String location, {Object? extra}) =>
       GoRouter.of(this).pushReplacement(location, extra: extra);
 
@@ -89,4 +99,36 @@ extension GoRouterHelper on BuildContext {
         queryParams: queryParams,
         extra: extra,
       );
+
+  /// Replaces the top-most page of the page stack with the given one but treats
+  /// it as the same page.
+  ///
+  /// The page key will be reused. This will preserve the state and not run any
+  /// page animation.
+  ///
+  /// See also:
+  /// * [push] which pushes the given location onto the page stack.
+  /// * [pushReplacement] which replaces the top-most page of the page stack but
+  ///   always uses a new page key.
+  void replace(String location, {Object? extra}) =>
+      GoRouter.of(this).replace(location, extra: extra);
+
+  /// Replaces the top-most page with the named route and optional parameters,
+  /// preserving the page key.
+  ///
+  /// This will preserve the state and not run any page animation. Optional
+  /// parameters can be providded to the named route, e.g. `name='person',
+  /// params={'fid': 'f2', 'pid': 'p1'}`.
+  ///
+  /// See also:
+  /// * [pushNamed] which pushes the given location onto the page stack.
+  /// * [pushReplacementNamed] which replaces the top-most page of the page
+  ///   stack but always uses a new page key.
+  void replaceNamed(
+    String name, {
+    Map<String, String> params = const <String, String>{},
+    Map<String, dynamic> queryParams = const <String, dynamic>{},
+    Object? extra,
+  }) =>
+      GoRouter.of(this).replaceNamed(name, extra: extra);
 }

packages/go_router/lib/src/router.dart

@@ -203,7 +203,14 @@ class GoRouter extends ChangeNotifier implements RouterConfig<RouteMatchList> {
       );
 
   /// Push a URI location onto the page stack w/ optional query parameters, e.g.
-  /// `/family/f2/person/p1?color=blue`
+  /// `/family/f2/person/p1?color=blue`.
+  ///
+  /// See also:
+  /// * [pushReplacement] which replaces the top-most page of the page stack and
+  ///   always use a new page key.
+  /// * [replace] which replaces the top-most page of the page stack but treats
+  ///   it as the same page. The page key will be reused. This will preserve the
+  ///   state and not run any page animation.
   void push(String location, {Object? extra}) {
     assert(() {
       log.info('pushing $location');
@@ -239,7 +246,10 @@ class GoRouter extends ChangeNotifier implements RouterConfig<RouteMatchList> {
   ///
   /// See also:
   /// * [go] which navigates to the location.
-  /// * [push] which pushes the location onto the page stack.
+  /// * [push] which pushes the given location onto the page stack.
+  /// * [replace] which replaces the top-most page of the page stack but treats
+  ///   it as the same page. The page key will be reused. This will preserve the
+  ///   state and not run any page animation.
   void pushReplacement(String location, {Object? extra}) {
     routeInformationParser
         .parseRouteInformationWithDependencies(
@@ -272,6 +282,52 @@ class GoRouter extends ChangeNotifier implements RouterConfig<RouteMatchList> {
     );
   }
 
+  /// Replaces the top-most page of the page stack with the given one but treats
+  /// it as the same page.
+  ///
+  /// The page key will be reused. This will preserve the state and not run any
+  /// page animation.
+  ///
+  /// See also:
+  /// * [push] which pushes the given location onto the page stack.
+  /// * [pushReplacement] which replaces the top-most page of the page stack but
+  ///   always uses a new page key.
+  void replace(String location, {Object? extra}) {
+    routeInformationParser
+        .parseRouteInformationWithDependencies(
+      RouteInformation(location: location, state: extra),
+      // TODO(chunhtai): avoid accessing the context directly through global key.
+      // https://github.com/flutter/flutter/issues/99112
+      _routerDelegate.navigatorKey.currentContext!,
+    )
+        .then<void>((RouteMatchList matchList) {
+      routerDelegate.replace(matchList);
+    });
+  }
+
+  /// Replaces the top-most page with the named route and optional parameters,
+  /// preserving the page key.
+  ///
+  /// This will preserve the state and not run any page animation. Optional
+  /// parameters can be providded to the named route, e.g. `name='person',
+  /// params={'fid': 'f2', 'pid': 'p1'}`.
+  ///
+  /// See also:
+  /// * [pushNamed] which pushes the given location onto the page stack.
+  /// * [pushReplacementNamed] which replaces the top-most page of the page
+  ///   stack but always uses a new page key.
+  void replaceNamed(
+    String name, {
+    Map<String, String> params = const <String, String>{},
+    Map<String, dynamic> queryParams = const <String, dynamic>{},
+    Object? extra,
+  }) {
+    replace(
+      namedLocation(name, params: params, queryParams: queryParams),
+      extra: extra,
+    );
+  }
+
   /// Pop the top-most route off the current screen.
   ///
   /// If the top-most route is a pop up or dialog, this method pops it instead

packages/go_router/lib/src/state.dart

@@ -4,7 +4,6 @@
 
 import 'package:flutter/widgets.dart';
 
-import '../go_router.dart';
 import 'configuration.dart';
 import 'misc/errors.dart';
 
@@ -64,7 +63,11 @@ class GoRouterState {
   /// The error associated with this sub-route.
   final Exception? error;
 
-  /// A unique string key for this sub-route, e.g. ValueKey('/family/:fid')
+  /// A unique string key for this sub-route.
+  /// E.g.
+  /// ```dart
+  /// ValueKey('/family/:fid')
+  /// ```
   final ValueKey<String> pageKey;
 
   /// Gets the [GoRouterState] from context.

packages/go_router/pubspec.yaml

@@ -1,7 +1,7 @@
 name: go_router
 description: A declarative router for Flutter based on Navigation 2 supporting
   deep linking, data-driven routes and more
-version: 6.3.0
+version: 6.4.0
 repository: https://github.com/flutter/packages/tree/main/packages/go_router
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+go_router%22