restorablePushReplacementNamed<T extends Object?, TO extends Object?> method Null safety

  1. @optionalTypeArgs
String restorablePushReplacementNamed<T extends Object?, TO extends Object?>(
  1. BuildContext context,
  2. String routeName,
  3. {TO? result,
  4. Object? arguments}
)
optionalTypeArgs">@optionalTypeArgs

Replace the current route of the navigator that most tightly encloses the given context by pushing the route named routeName and then disposing the previous route once the new route has finished animating in.

Unlike Routes pushed via pushReplacementNamed, Routes pushed with this method are restored during state restoration according to the rules outlined in the "State Restoration" section of Navigator.

If non-null, result will be used as the result of the route that is removed; the future that had been returned from pushing that old route will complete with result. Routes such as dialogs or popup menus typically use this mechanism to return the value selected by the user to the widget that created their route. The type of result, if provided, must match the type argument of the class of the old route (TO).

The route name will be passed to the Navigator.onGenerateRoute callback. The returned route will be pushed into the navigator.

The new route and the route below the removed route are notified (see Route.didPush and Route.didChangeNext). If the Navigator has any Navigator.observers, they will be notified as well (see NavigatorObserver.didReplace). The removed route is notified once the new route has finished animating (see Route.didComplete). The removed route's exit animation is not run (see popAndPushNamed for a variant that does animated the removed route).

Ongoing gestures within the current route are canceled when a new route is pushed.

The T type argument is the type of the return value of the new route, and TO is the type of the return value of the old route.

To use pushReplacementNamed, a Navigator.onGenerateRoute callback must be provided.

The provided arguments are passed to the pushed route via RouteSettings.arguments. Any object that is serializable via the StandardMessageCodec can be passed as arguments. Often, a Map is used to pass key-value pairs.

The arguments may be used in Navigator.onGenerateRoute or Navigator.onUnknownRoute to construct the route.

The method returns an opaque ID for the pushed route that can be used by the RestorableRouteFuture to gain access to the actual Route object added to the navigator and its return value. You can ignore the return value of this method, if you do not care about the route object or the route's return value.

link
Typical usage is as follows: 
void _switchToAudioVolume() {
  Navigator.restorablePushReplacementNamed(context, '/settings/volume');
}

Implementation

@optionalTypeArgs
static String restorablePushReplacementNamed<T extends Object?, TO extends Object?>(
  BuildContext context,
  String routeName, {
  TO? result,
  Object? arguments,
}) {
  return Navigator.of(context).restorablePushReplacementNamed<T, TO>(routeName, arguments: arguments, result: result);
}