DeferredScreen class

Wraps a screen whose Dart library is loaded on demand via import '...' deferred as alias; + alias.loadLibrary().

On the first navigation to the route, dart2js fetches the deferred chunk and resolves the future returned by loader. Subsequent navigations skip the fetch — loadLibrary() is idempotent and returns immediately. Once a loader has resolved, DeferredScreen remembers that fact in a static set keyed by the loader tear-off (top-level loadLibrary tear-offs are canonical, so identity comparison is stable). On the next mount it short-circuits the FutureBuilder and renders builder synchronously on the very first frame, eliminating the one-frame ConnectionState.waiting flash that would otherwise show on every revisit.

While a chunk is genuinely fetching, the placeholder spinner fades in with a small delay so sub-300 ms loads pass invisibly — the user sees the previous screen until the new screen is ready.

Native (iOS/Android) builds still have to call loadLibrary() once to mark the library "loaded" — accessing a deferred symbol before that throws _DeferredNotLoadedError. The completion runs via a microtask, so widget tests that mount a route through this widget must await tester.pumpAndSettle() (or pump for a non-zero duration) before asserting on the loaded screen.

Inheritance
Available extensions

Constructors

DeferredScreen({Key? key, required Future<void> loader(), required Widget builder()})
const

Properties

builder Widget Function()
Builds the actual screen once the deferred chunk is loaded. Must only reference symbols from the deferred-imported library inside this closure — they are not available before the future from loader resolves.
final
hashCode int
The hash code for this object.
no setterinherited
key Key?
Controls how one widget replaces another widget in the tree.
finalinherited
loader Future<void> Function()
Tear-off of the deferred-imported library's loadLibrary (e.g. auth.loadLibrary). Called once on initState; the result is retained so rebuilds don't re-trigger the load.
final
runtimeType Type
A representation of the runtime type of the object.
no setterinherited

Methods

animate({Key? key, List<Effect>? effects, AnimateCallback? onInit, AnimateCallback? onPlay, AnimateCallback? onComplete, bool? autoPlay, Duration? delay, AnimationController? controller, Adapter? adapter, double? target, double? value}) Animate

Available on Widget, provided by the AnimateWidgetExtensions extension

Wraps the target Widget in an Animate instance, and returns the instance for chaining calls. Ex. myWidget.animate() is equivalent to Animate(child: myWidget).
createElement() StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() State<DeferredScreen>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object.
inherited
toStringShort() String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited

Static Properties

loadedLoaders Set<Future<void> Function()>
Loader tear-offs that have already resolved at least once in this app session. Visible for testing so the test suite can reset state between cases.
final

Static Methods

markLoaded(Iterable<Future<void> Function()> loaders) → void
Marks every tear-off in loaders as already loaded. Use from app boot to opt routes that have been preloaded into the synchronous render path even if no DeferredScreen for them has mounted yet.