restorablePushReplacement<T extends Object?, TO extends Object?> method
- RestorableRouteBuilder<
T> routeBuilder, { - TO? result,
- Object? arguments,
Replace the current route of the navigator by pushing a new route and then disposing the previous route once the new route has finished animating in.
Unlike Routes pushed via pushReplacement, 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 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).
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.
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.
To create a local project with this code sample, run:
flutter create --sample=widgets.NavigatorState.restorablePushReplacement.1 mysample
Implementation
@optionalTypeArgs
String restorablePushReplacement<T extends Object?, TO extends Object?>(RestorableRouteBuilder<T> routeBuilder, { TO? result, Object? arguments }) {
assert(_debugIsStaticCallback(routeBuilder), '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: routeBuilder,
arguments: arguments,
restorationScopeId: _nextPagelessRestorationScopeId,
).toRouteEntry(this, initialState: _RouteLifecycle.pushReplace);
_pushReplacementEntry(entry, result);
return entry.restorationId!;
}