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
-
- Object
- DiagnosticableTree
- Widget
- StatefulWidget
- DeferredScreen
- 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 oninitState; 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 toAnimate(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< loaders) → voidvoid> Function()> -
Marks every tear-off in
loadersas already loaded. Use from app boot to opt routes that have been preloaded into the synchronous render path even if noDeferredScreenfor them has mounted yet.