restorableReplace<T extends Object?> method

  1. @optionalTypeArgs
String restorableReplace<T extends Object?>({
  1. required Route oldRoute,
  2. required RestorableRouteBuilder<T> newRouteBuilder,
  3. Object? arguments,
})

Replaces a route on the navigator with a new route.

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

The old route must not be currently visible, as this method skips the animations and therefore the removal would be jarring if it was visible. To replace the top-most route, consider pushReplacement instead, which does animate the new route, and delays removing the old route until the new route has finished animating.

The removed route is removed without being completed, so this method does not take a return value argument.

The new route, the route below the new route (if any), and the route above the new route, are all notified (see Route.didReplace, Route.didChangeNext, and Route.didChangePrevious). If the Navigator has any Navigator.observers, they will be notified as well (see NavigatorObserver.didReplace). The removed route is disposed without being notified. The future that had been returned from pushing that routes will not complete.

This can be useful in combination with removeRouteBelow when building a non-linear user experience.

The T type argument is the type of the return value of the new route.

The method takes a RestorableRouteBuilder as argument, which must be a static function annotated with @pragma('vm:entry-point'). It must instantiate and return a new Route object that will be added to the navigator. The provided arguments object is passed to the routeBuilder. The navigator calls the static routeBuilder function again during state restoration to re-create the route object.

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

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.

Implementation

@optionalTypeArgs
String restorableReplace<T extends Object?>({ required Route<dynamic> oldRoute, required RestorableRouteBuilder<T> newRouteBuilder, Object? arguments }) {
  assert(oldRoute._navigator == this);
  assert(_debugIsStaticCallback(newRouteBuilder), 'The provided routeBuilder must be a static function.');
  assert(debugIsSerializableForRestoration(arguments), 'The arguments object must be serializable via the StandardMessageCodec.');
  final _RouteEntry entry = _RestorationInformation.anonymous(
    routeBuilder: newRouteBuilder,
    arguments: arguments,
    restorationScopeId: _nextPagelessRestorationScopeId,
  ).toRouteEntry(this, initialState: _RouteLifecycle.replace);
  _replaceEntry(entry, oldRoute);
  return entry.restorationId!;
}