FutureBuilder<T> class

A widget that builds itself based on the latest snapshot of interaction withaFuture.

Managing the future

Thefuture must have been obtained earlier, e.g. duringState.initState,State.didUpdateWidget, orState.didChangeDependencies. It must not becreated during theState.build orStatelessWidget.build method call whenconstructing theFutureBuilder. If thefuture is created at the sametime as theFutureBuilder, then every time theFutureBuilder's parent isrebuilt, the asynchronous task will be restarted.

A general guideline is to assume that everybuild method could get calledevery frame, and to treat omitted calls as an optimization.

Timing

Widget rebuilding is scheduled by the completion of the future, usingState.setState, but is otherwise decoupled from the timing of the future.Thebuilder callback is called at the discretion of the Flutter pipeline, andwill thus receive a timing-dependent sub-sequence of the snapshots thatrepresent the interaction with the future.

A side-effect of this is that providing a new but already-completed futureto aFutureBuilder will result in a single frame in theConnectionState.waiting state. This is because there is no way tosynchronously determine that aFuture has already completed.

Builder contract

For a future that completes successfully with data, assuminginitialDatais null, thebuilder will be called with either both or only the latter ofthe following snapshots:

AsyncSnapshot<String>.withData(ConnectionState.waiting, null)
AsyncSnapshot<String>.withData(ConnectionState.done, 'some data')

If that same future instead completed with an error, thebuilder would becalled with either both or only the latter of:

AsyncSnapshot<String>.withData(ConnectionState.waiting, null)
AsyncSnapshot<String>.withError(ConnectionState.done, 'some error', someStackTrace)

The initial snapshot data can be controlled by specifyinginitialData. Youwould use this facility to ensure that if thebuilder is invoked beforethe future completes, the snapshot carries data of your choice rather thanthe default null value.

The data and error fields of the snapshot change only as the connectionstate field transitions fromwaiting todone, and they will be retainedwhen changing theFutureBuilder configuration to another future. If theold future has already completed successfully with data as above, changingconfiguration to a new future results in snapshot pairs of the form:

AsyncSnapshot<String>.withData(ConnectionState.none, 'data of first future')
AsyncSnapshot<String>.withData(ConnectionState.waiting, 'data of second future')

In general, the latter will be produced only when the new future isnon-null, and the former only when the old future is non-null.

AFutureBuilder behaves identically to aStreamBuilder configured withfuture?.asStream(), except that snapshots withConnectionState.activemay appear for the latter, depending on how the stream is implemented.

This sample shows aFutureBuilder that displays a loading spinner while itloads data. It displays a success icon and text if theFuture completeswith a result, or an error icon and text if theFuture completes with anerror. Assume the_calculation field is set by pressing a button elsewherein the UI.

link

To create a local project with this code sample, run:
flutter create --sample=widgets.FutureBuilder.1 mysample

Inheritance

Constructors

FutureBuilder({Key?key,requiredFuture<T>?future,T?initialData,requiredAsyncWidgetBuilder<T>builder}): Creates a widget that builds itself based on the latest snapshot ofinteraction with aFuture.
const

Properties

builder→AsyncWidgetBuilder<T>: The build strategy currently used by this builder.
final
future→Future<T>?: The asynchronous computation to which this builder is currently connected,possibly null.
final
hashCode→int: The hash code for this object.
no setterinherited
initialData→ T?: The data that will be used to create the snapshots provided until anon-nullfuture has completed.
final
key→Key?: Controls how one widget replaces another widget in the tree.
finalinherited
runtimeType→Type: A representation of the runtime type of the object.
no setterinherited

Methods

createElement()→StatefulElement: Creates aStatefulElement to manage this widget's location in the tree.
inherited
createState()→State<FutureBuilder<T>>: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren()→List<DiagnosticsNode>: Returns a list ofDiagnosticsNode objects describing this node'schildren.
inherited
debugFillProperties(DiagnosticPropertiesBuilderproperties)→ void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocationinvocation)→ 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 debuggingtools and byDiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevelminLevel =DiagnosticLevel.info})→String: A string representation of this object.
inherited
toStringDeep({StringprefixLineOne ='',String?prefixOtherLines,DiagnosticLevelminLevel =DiagnosticLevel.debug,intwrapWidth =65})→String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({Stringjoiner =', ',DiagnosticLevelminLevel =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 ==(Objectother)→bool: The equality operator.
inherited

Static Properties

debugRethrowError↔bool: Whether the latest error received by the asynchronous computation shouldbe rethrown or swallowed. This property is useful for debugging purposes.
getter/setter pair

Flutter
widgets
FutureBuilder<T> class

Movatterモバイル変換