firka/flutter
firka/flutter
5
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve async builder docs (#15373)

Browse Source
This commit is contained in:
Ian Hickson 2018-03-18 22:00:47 -07:00 committed by GitHub
parent 42e4e16b47
commit b494e71e36
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 112 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
packages/flutter/lib/src/widgets/async.dart
View File

@ -38,6 +38,7 @@ import 'framework.dart';
/// on change of stream by overriding [afterDisconnected] and [afterConnected].
///
/// [T] is the type of stream events.
///
/// [S] is the type of interaction summary.
///
/// See also:
@ -165,12 +166,17 @@ class _StreamBuilderBaseState<T, S> extends State<StreamBuilderBase<T, S>> {
/// received from the asynchronous computation.
enum ConnectionState {
/// Not currently connected to any asynchronous computation.
///
/// For example, a [FutureBuilder] whose [FutureBuilder.future] is null.
none,
/// Connected to an asynchronous computation and awaiting interaction.
waiting,
/// Connected to an active asynchronous computation.
///
/// For example, a [Stream] that has returned at least one value, but is not
/// yet done.
active,
/// Connected to a terminated asynchronous computation.
@ -206,7 +212,15 @@ class AsyncSnapshot<T> {
/// Current state of connection to the asynchronous computation.
final ConnectionState connectionState;
/// Latest data received. Is null, if [error] is not.
/// The latest data received by the asynchronous computation.
///
/// If this is non-null, [hasData] will be true.
///
/// If [error] is not null, this will be null. See [hasError].
///
/// If the asynchronous computation has never returned a value, this may be
/// set to an initial data value specified by the relevant widget. See
/// [FutureBuilder.initialData] and [StreamBuilder.initialData].
final T data;
/// Returns latest data received, failing if there is no data.
@ -221,20 +235,35 @@ class AsyncSnapshot<T> {
throw new StateError('Snapshot has neither data nor error');
}
/// Latest error object received. Is null, if [data] is not.
/// The latest error object received by the asynchronous computation.
///
/// If this is non-null, [hasError] will be true.
///
/// If [data] is not null, this will be null.
final Object error;
/// Returns a snapshot like this one, but in the specified [state].
///
/// The [data] and [error] fields persist unmodified, even if the new state is
/// [ConnectionState.none].
AsyncSnapshot<T> inState(ConnectionState state) => new AsyncSnapshot<T>._(state, data, error);
/// Returns whether this snapshot contains a non-null data value.
/// Returns whether this snapshot contains a non-null [data] value.
///
/// This can be false even when the asynchronous computation has completed
/// successfully, if the computation did not return a non-null value. For
/// example, a [Future<void>] will complete with the null value even if it
/// completes successfully.
bool get hasData => data != null;
/// Returns whether this snapshot contains a non-null error value.
/// Returns whether this snapshot contains a non-null [error] value.
///
/// This is always true if the asynchronous computation's last result was
/// failure.
bool get hasError => error != null;
@override
String toString() => 'AsyncSnapshot($connectionState, $data, $error)';
String toString() => '$runtimeType($connectionState, $data, $error)';
@override
bool operator ==(dynamic other) {
@ -289,15 +318,15 @@ typedef Widget AsyncWidgetBuilder<T>(BuildContext context, AsyncSnapshot<T> snap
/// pipeline.
///
/// Changing the [StreamBuilder] configuration to another stream during event
/// generation introduces snapshot pairs of the form
/// generation introduces snapshot pairs of the form:
///
/// * `new AsyncSnapshot<int>.withData(ConnectionState.none, 5)`
/// * `new AsyncSnapshot<int>.withData(ConnectionState.waiting, 5)`
///
/// The latter will be produced only when the new stream is non-null. The former
/// only when the old stream is non-null.
/// The latter will be produced only when the new stream is non-null, and the
/// former only when the old stream is non-null.
///
/// The stream may produce errors, resulting in snapshots of the form
/// The stream may produce errors, resulting in snapshots of the form:
///
/// * `new AsyncSnapshot<int>.withError(ConnectionState.active, 'some error')`
///
@ -331,7 +360,6 @@ typedef Widget AsyncWidgetBuilder<T>(BuildContext context, AsyncSnapshot<T> snap
/// case ConnectionState.waiting: return new Text('Awaiting bids...');
/// case ConnectionState.active: return new Text('\$${snapshot.data}');
/// case ConnectionState.done: return new Text('\$${snapshot.data} (closed)');
/// default: throw "Unknown: ${snapshot.connectionState}";
/// }
/// },
/// )
@ -391,14 +419,15 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
/// will thus receive a timing-dependent sub-sequence of the snapshots that
/// represent the interaction with the future.
///
/// For a future that completes successfully with data, the [builder] may
/// be called with either both or only the latter of the following snapshots:
/// For a future that completes successfully with data, assuming [initialData]
/// is null, the [builder] will be called with either both or only the latter of
/// the following snapshots:
///
/// * `new AsyncSnapshot<String>.withData(ConnectionState.waiting, null)`
/// * `new AsyncSnapshot<String>.withData(ConnectionState.done, 'some data')`
///
/// For a future completing with an error, the [builder] may be called with
/// either both or only the latter of:
/// If that same future instead completed with an error, the [builder] would be
/// called with either both or only the latter of:
///
/// * `new AsyncSnapshot<String>.withData(ConnectionState.waiting, null)`
/// * `new AsyncSnapshot<String>.withError(ConnectionState.done, 'some error')`
@ -414,11 +443,11 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
/// old future has already completed successfully with data as above, changing
/// configuration to a new future results in snapshot pairs of the form:
///
/// * `new AsyncSnapshot<String>.withData(ConnectionState.none, 'some data')`
/// * `new AsyncSnapshot<String>.withData(ConnectionState.waiting, 'some data')`
/// * `new AsyncSnapshot<String>.withData(ConnectionState.none, 'data of first future')`
/// * `new AsyncSnapshot<String>.withData(ConnectionState.waiting, 'data of second future')`
///
/// In general, the latter will be produced only when the new future is
/// non-null. The former only when the old future is non-null.
/// non-null, and the former only when the old future is non-null.
///
/// A [FutureBuilder] behaves identically to a [StreamBuilder] configured with
/// `future?.asStream()`, except that snapshots with `ConnectionState.active`
@ -461,12 +490,40 @@ class FutureBuilder<T> extends StatefulWidget {
/// The asynchronous computation to which this builder is currently connected,
/// possibly null.
///
/// If no future has yet completed, including in the case where [future] is
/// null, the data provided to the [builder] will be set to [initialData].
final Future<T> future;
/// The build strategy currently used by this builder. Cannot be null.
/// The build strategy currently used by this builder.
///
/// The builder is provided with an [AsyncSnapshot] object whose
/// [AsyncSnapshot.connectionState] property will be one of the following
/// values:
///
/// * [ConnectionState.none]: [future] is null. The [AsyncSnapshot.data] will
/// be set to [initialData], unless a future has previously completed, in
/// which case the previous result persists.
///
/// * [ConnectionState.waiting]: [future] is not null, but has not yet
/// completed. The [AsyncSnapshot.data] will be set to [initialData],
/// unless a future has previously completed, in which case the previous
/// result persists.
///
/// * [ConnectionState.done]: [future] is not null, and has completed. If the
/// future completed successfully, the [AsyncSnapshot.data] will be set to
/// the value to which the future completed. If it completed with an error,
/// [AsyncSnapshot.hasError] will be true and [AsyncSnapshot.error] will be
/// set to the error object.
final AsyncWidgetBuilder<T> builder;
/// The data that will be used to create the initial snapshot. Null by default.
/// The data that will be used to create the snapshots provided until a
/// non-null [future] has completed.
///
/// If the future completes with an error, the data in the [AsyncSnapshot]
/// provided to the [builder] will become null, regardless of [initialData].
/// (The error itself will be available in [AsyncSnapshot.error], and
/// [AsyncSnapshot.hasError] will be true.)
final T initialData;
@override

72
packages/flutter/test/widgets/async_test.dart
View File

@ -59,12 +59,12 @@ void main() {
await tester.pumpWidget(new FutureBuilder<String>(
key: key, future: null, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.none, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.none, null, null)'), findsOneWidget);
final Completer<String> completer = new Completer<String>();
await tester.pumpWidget(new FutureBuilder<String>(
key: key, future: completer.future, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsOneWidget);
});
testWidgets('gracefully handles transition to null future', (WidgetTester tester) async {
final GlobalKey key = new GlobalKey();
@ -72,14 +72,14 @@ void main() {
await tester.pumpWidget(new FutureBuilder<String>(
key: key, future: completer.future, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsOneWidget);
await tester.pumpWidget(new FutureBuilder<String>(
key: key, future: null, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.none, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.none, null, null)'), findsOneWidget);
completer.complete('hello');
await eventFiring(tester);
expect(find.text('AsyncSnapshot(ConnectionState.none, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.none, null, null)'), findsOneWidget);
});
testWidgets('gracefully handles transition to other future', (WidgetTester tester) async {
final GlobalKey key = new GlobalKey();
@ -88,35 +88,35 @@ void main() {
await tester.pumpWidget(new FutureBuilder<String>(
key: key, future: completerA.future, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsOneWidget);
await tester.pumpWidget(new FutureBuilder<String>(
key: key, future: completerB.future, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsOneWidget);
completerB.complete('B');
completerA.complete('A');
await eventFiring(tester);
expect(find.text('AsyncSnapshot(ConnectionState.done, B, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.done, B, null)'), findsOneWidget);
});
testWidgets('tracks life-cycle of Future to success', (WidgetTester tester) async {
final Completer<String> completer = new Completer<String>();
await tester.pumpWidget(new FutureBuilder<String>(
future: completer.future, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsOneWidget);
completer.complete('hello');
await eventFiring(tester);
expect(find.text('AsyncSnapshot(ConnectionState.done, hello, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.done, hello, null)'), findsOneWidget);
});
testWidgets('tracks life-cycle of Future to error', (WidgetTester tester) async {
final Completer<String> completer = new Completer<String>();
await tester.pumpWidget(new FutureBuilder<String>(
future: completer.future, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsOneWidget);
completer.completeError('bad');
await eventFiring(tester);
expect(find.text('AsyncSnapshot(ConnectionState.done, null, bad)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.done, null, bad)'), findsOneWidget);
});
testWidgets('runs the builder using given initial data', (WidgetTester tester) async {
final GlobalKey key = new GlobalKey();
@ -126,7 +126,7 @@ void main() {
builder: snapshotText,
initialData: 'I',
));
expect(find.text('AsyncSnapshot(ConnectionState.none, I, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.none, I, null)'), findsOneWidget);
});
testWidgets('ignores initialData when reconfiguring', (WidgetTester tester) async {
final GlobalKey key = new GlobalKey();
@ -136,7 +136,7 @@ void main() {
builder: snapshotText,
initialData: 'I',
));
expect(find.text('AsyncSnapshot(ConnectionState.none, I, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.none, I, null)'), findsOneWidget);
final Completer<String> completer = new Completer<String>();
await tester.pumpWidget(new FutureBuilder<String>(
key: key,
@ -144,7 +144,7 @@ void main() {
builder: snapshotText,
initialData: 'Ignored',
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, I, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, I, null)'), findsOneWidget);
});
});
group('StreamBuilder', () {
@ -153,12 +153,12 @@ void main() {
await tester.pumpWidget(new StreamBuilder<String>(
key: key, stream: null, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.none, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.none, null, null)'), findsOneWidget);
final StreamController<String> controller = new StreamController<String>();
await tester.pumpWidget(new StreamBuilder<String>(
key: key, stream: controller.stream, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsOneWidget);
});
testWidgets('gracefully handles transition to null stream', (WidgetTester tester) async {
final GlobalKey key = new GlobalKey();
@ -166,11 +166,11 @@ void main() {
await tester.pumpWidget(new StreamBuilder<String>(
key: key, stream: controller.stream, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsOneWidget);
await tester.pumpWidget(new StreamBuilder<String>(
key: key, stream: null, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.none, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.none, null, null)'), findsOneWidget);
});
testWidgets('gracefully handles transition to other stream', (WidgetTester tester) async {
final GlobalKey key = new GlobalKey();
@ -179,14 +179,14 @@ void main() {
await tester.pumpWidget(new StreamBuilder<String>(
key: key, stream: controllerA.stream, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsOneWidget);
await tester.pumpWidget(new StreamBuilder<String>(
key: key, stream: controllerB.stream, builder: snapshotText
));
controllerB.add('B');
controllerA.add('A');
await eventFiring(tester);
expect(find.text('AsyncSnapshot(ConnectionState.active, B, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.active, B, null)'), findsOneWidget);
});
testWidgets('tracks events and errors of stream until completion', (WidgetTester tester) async {
final GlobalKey key = new GlobalKey();
@ -194,19 +194,19 @@ void main() {
await tester.pumpWidget(new StreamBuilder<String>(
key: key, stream: controller.stream, builder: snapshotText
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsOneWidget);
controller.add('1');
controller.add('2');
await eventFiring(tester);
expect(find.text('AsyncSnapshot(ConnectionState.active, 2, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.active, 2, null)'), findsOneWidget);
controller.add('3');
controller.addError('bad');
await eventFiring(tester);
expect(find.text('AsyncSnapshot(ConnectionState.active, null, bad)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.active, null, bad)'), findsOneWidget);
controller.add('4');
controller.close();
await eventFiring(tester);
expect(find.text('AsyncSnapshot(ConnectionState.done, 4, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.done, 4, null)'), findsOneWidget);
});
testWidgets('runs the builder using given initial data', (WidgetTester tester) async {
final StreamController<String> controller = new StreamController<String>();
@ -215,7 +215,7 @@ void main() {
builder: snapshotText,
initialData: 'I',
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, I, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, I, null)'), findsOneWidget);
});
testWidgets('ignores initialData when reconfiguring', (WidgetTester tester) async {
final GlobalKey key = new GlobalKey();
@ -225,7 +225,7 @@ void main() {
builder: snapshotText,
initialData: 'I',
));
expect(find.text('AsyncSnapshot(ConnectionState.none, I, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.none, I, null)'), findsOneWidget);
final StreamController<String> controller = new StreamController<String>();
await tester.pumpWidget(new StreamBuilder<String>(
key: key,
@ -233,7 +233,7 @@ void main() {
builder: snapshotText,
initialData: 'Ignored',
));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, I, null)'), findsOneWidget);
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, I, null)'), findsOneWidget);
});
});
group('FutureBuilder and StreamBuilder behave identically on Stream from Future', () {
@ -243,10 +243,10 @@ void main() {
new FutureBuilder<String>(future: completer.future, builder: snapshotText),
new StreamBuilder<String>(stream: completer.future.asStream(), builder: snapshotText),
]));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsNWidgets(2));
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsNWidgets(2));
completer.complete('hello');
await eventFiring(tester);
expect(find.text('AsyncSnapshot(ConnectionState.done, hello, null)'), findsNWidgets(2));
expect(find.text('AsyncSnapshot<String>(ConnectionState.done, hello, null)'), findsNWidgets(2));
});
testWidgets('when completing with error', (WidgetTester tester) async {
final Completer<String> completer = new Completer<String>();
@ -254,24 +254,24 @@ void main() {
new FutureBuilder<String>(future: completer.future, builder: snapshotText),
new StreamBuilder<String>(stream: completer.future.asStream(), builder: snapshotText),
]));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, null, null)'), findsNWidgets(2));
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, null, null)'), findsNWidgets(2));
completer.completeError('bad');
await eventFiring(tester);
expect(find.text('AsyncSnapshot(ConnectionState.done, null, bad)'), findsNWidgets(2));
expect(find.text('AsyncSnapshot<String>(ConnectionState.done, null, bad)'), findsNWidgets(2));
});
testWidgets('when Future is null', (WidgetTester tester) async {
await tester.pumpWidget(new Column(children: <Widget>[
new FutureBuilder<String>(future: null, builder: snapshotText),
new StreamBuilder<String>(stream: null, builder: snapshotText),
]));
expect(find.text('AsyncSnapshot(ConnectionState.none, null, null)'), findsNWidgets(2));
expect(find.text('AsyncSnapshot<String>(ConnectionState.none, null, null)'), findsNWidgets(2));
});
testWidgets('when initialData is used with null Future and Stream', (WidgetTester tester) async {
await tester.pumpWidget(new Column(children: <Widget>[
new FutureBuilder<String>(future: null, builder: snapshotText, initialData: 'I'),
new StreamBuilder<String>(stream: null, builder: snapshotText, initialData: 'I'),
]));
expect(find.text('AsyncSnapshot(ConnectionState.none, I, null)'), findsNWidgets(2));
expect(find.text('AsyncSnapshot<String>(ConnectionState.none, I, null)'), findsNWidgets(2));
});
testWidgets('when using initialData and completing with data', (WidgetTester tester) async {
final Completer<String> completer = new Completer<String>();
@ -279,10 +279,10 @@ void main() {
new FutureBuilder<String>(future: completer.future, builder: snapshotText, initialData: 'I'),
new StreamBuilder<String>(stream: completer.future.asStream(), builder: snapshotText, initialData: 'I'),
]));
expect(find.text('AsyncSnapshot(ConnectionState.waiting, I, null)'), findsNWidgets(2));
expect(find.text('AsyncSnapshot<String>(ConnectionState.waiting, I, null)'), findsNWidgets(2));
completer.complete('hello');
await eventFiring(tester);
expect(find.text('AsyncSnapshot(ConnectionState.done, hello, null)'), findsNWidgets(2));
expect(find.text('AsyncSnapshot<String>(ConnectionState.done, hello, null)'), findsNWidgets(2));
});
});
group('StreamBuilderBase', () {