很多时候我们会依赖一些异步数据来动态更新UI：

  • 比如在打开一个页面时我们需要先从互联网上获取数据，在获取数据的过程中我们显示一个加载框，等获取到数据时我们再渲染页面；
  • 又比如我们想展示Stream（比如文件流、互联网数据接收流）的进度。

当然，通过StatefulWidget我们完全可以实现上述这些功能。但由于在实际开发中依赖异步数据更新UI的这种场景非常常见，因此Flutter专门提供了

  • FutureBuilder
  • StreamBuilder

两个组件来快速实现这种功能。

FutureBuilder

FutureBuilder 会依赖一个Future，它会根据所依赖的Future的状态来动态构建自身
我们看一下 FutureBuilder 构造函数：

  1. FutureBuilder({
  2.   this.future,
  3.   this.initialData,
  4.   @required this.builder,
  5. })
  • future：FutureBuilder依赖的Future，通常是一个异步耗时任务
  • initialData：初始数据，用户设置默认数据

  • builder：Widget构建器；该构建器会在Future执行的不同阶段被多次调用，构建器签名如下：

    1. Function (BuildContext context, AsyncSnapshot snapshot)
    • snapshot 会包含当前异步任务的状态信息及结果信息 ，比如我们可以
      • 通过snapshot.connectionState 获取异步任务的状态信息
      • 通过snapshot.hasError 判断异步任务是否有错误等等，完整的定义读者可以查看AsyncSnapshot类定义

⚠️ Tip：另外，FutureBuilder的builder函数签名和StreamBuilder的builder是相同的
我们实现一个路由，当该路由打开时我们从网上获取数据，获取数据时弹一个加载框；获取结束时，如果成功则显示获取到的数据，如果失败则显示错误。由于我们还没有介绍在flutter中如何发起网络请求，所以在这里我们不真正去网络请求数据，而是模拟一下这个过程，隔3秒后返回一个字符串：

  1. Future<String> mockNetworkData() async {
  2.   return Future.delayed(Duration(seconds: 2), () => "我是从互联网上获取的数据");
  3. }

FutureBuilder使用代码如下：

  1. import 'package:flutter/material.dart';
  3. void main() => runApp(new MyApp());
  5. class MyApp extends StatelessWidget {
  6.   @override
  7.   Widget build(BuildContext context) {
  8.     return MaterialApp(
  9.         debugShowCheckedModeBanner: true,
  10.         title: '主题测试',
  11.         theme: ThemeData(
  12.           primarySwatch: Colors.blue,
  13.         ),
  14.         home: Scaffold(
  15.           appBar: AppBar(title: Text("主题测试")),
  16.           body: TestFutureBuilder(),
  17.         ));
  18.   }
  19. }
  21. Future<String> mockNetworkData() async {
  22.   return Future.delayed(Duration(seconds: 2), () => "我是从互联网上获取的数据");
  23. }
  25. class TestFutureBuilder extends StatefulWidget {
  26.   TestFutureBuilder({Key key}) : super(key: key);
  28.   @override
  29.   Test_FutureBuilderState createState() => Test_FutureBuilderState();
  30. }
  32. class Test_FutureBuilderState extends State<TestFutureBuilder> {
  33.   @override
  34.   Widget build(BuildContext context) {
  35.     return Center(
  36.       child: FutureBuilder<String>(
  37.         future: mockNetworkData(),
  38.         builder: (BuildContext context, AsyncSnapshot snapshot) {
  39.           // 请求已结束
  40.           if (snapshot.connectionState == ConnectionState.done) {
  41.             if (snapshot.hasError) {
  42.               // 请求失败，显示错误
  43.               return Text("Error: ${snapshot.error}");
  44.             } else {
  45.               // 请求成功，显示数据
  46.               return Text("Contents: ${snapshot.data}");
  47.             }
  48.           } else {
  49.             // 请求未结束，显示loading
  50.             return CircularProgressIndicator();
  51.           }
  52.         },
  53.       ),
  54.     );
  55.   }
  56. }

运行结果如图所示：
异步UI更新（FutureBuilder、StreamBuilder） - 图1异步UI更新（FutureBuilder、StreamBuilder） - 图2
上面代码中我们在builder中根据当前异步任务状态ConnectionState来返回不同的widget。ConnectionState是一个枚举类，定义如下：

  1. enum ConnectionState {
  3.   none, /// 当前没有异步任务，比如[FutureBuilder]的[future]为null时
  5.   waiting,  /// 异步任务处于等待状态
  7.   active,  /// Stream处于激活状态（流上已经有数据传递了），对于FutureBuilder没有该状态
  9.   done,  /// 异步任务已经终止
  10. }

注意，ConnectionState.active只在StreamBuilder中才会出现

StreamBuilder

我们知道，在Dart中 Stream 也是用于接收异步事件数据，和Future 不同的是，
它可以接收多个异步操作的结果，它常用于会多次读取数据的异步任务场景，如网络内容下载、文件读写等。StreamBuilder正是用于配合Stream来展示流上事件（数据）变化的UI组件。
下面看一下StreamBuilder的默认构造函数：

  1. StreamBuilder({
  2.   Key key,
  3.   this.initialData,
  4.   Stream<T> stream,
  5.   @required this.builder,
  6. })

可以看到和FutureBuilder的构造函数只有一点不同：前者需要一个future，而后者需要一个stream
我们创建一个计时器的示例：每隔1秒，计数加1。这里，我们使用Stream来实现每隔一秒生成一个数字:

  1. Stream<int> counter() {
  2.   //创建以[周期]间隔重复发出事件的流。
  3.   return Stream.periodic(Duration(milliseconds: 1), (i) {
  4.     return i;
  5.   });
  6. }

StreamBuilder使用代码如下：

  1. import 'package:flutter/material.dart';
  3. void main() => runApp(new MyApp());
  5. class MyApp extends StatelessWidget {
  6.   @override
  7.   Widget build(BuildContext context) {
  8.     return MaterialApp(
  9.         debugShowCheckedModeBanner: true,
  10.         title: 'StreamBuilder',
  11.         theme: ThemeData(
  12.           primarySwatch: Colors.blue,
  13.         ),
  14.         home: Scaffold(
  15.           appBar: AppBar(title: Text("StreamBuilder")),
  16.           body: TestFutureBuilder(),
  17.         ));
  18.   }
  19. }
  21. Stream<int> counter() {
  22.   //创建以[周期]间隔重复发出事件的流。
  23.   return Stream.periodic(Duration(milliseconds: 1), (i) {
  24.     return i;
  25.   });
  26. }
  28. class TestFutureBuilder extends StatefulWidget {
  29.   TestFutureBuilder({Key key}) : super(key: key);
  31.   @override
  32.   Test_FutureBuilderState createState() => Test_FutureBuilderState();
  33. }
  35. class Test_FutureBuilderState extends State<TestFutureBuilder> {
  36.   @override
  37. Widget build(BuildContext context) {
  38.     return StreamBuilder<int>(
  39.       stream: counter(), //
  40.       //initialData: ,// a Stream<int> or null
  41.       builder: (BuildContext context, AsyncSnapshot<int> snapshot) {
  42.         if (snapshot.hasError)
  43.           return Text('Error: ${snapshot.error}');
  44.         switch (snapshot.connectionState) {
  45.           case ConnectionState.none:
  46.             return Text('没有Stream');
  47.           case ConnectionState.waiting:
  48.             return Text('等待数据...');
  49.           case ConnectionState.active:
  50.             return Text('active: ${snapshot.data}');
  51.           case ConnectionState.done:
  52.             return Text('Stream已关闭');
  53.         }
  54.         return null; // unreachable
  55.       },
  56.     );
  57.   }
  58. }

读者可以自己运行本示例查看运行结果。注意，本示例只是为了演示StreamBuilder的使用，在实战中，凡是UI会依赖多个异步数据而发生变化的场景都可以使用StreamBuilder

FutureBuilder和StreamBuilder源码

  1. import 'dart:async' show StreamSubscription;
  2. import 'package:flutter/foundation.dart';
  3. import 'framework.dart';
  5. abstract class StreamBuilderBase<T, S> extends StatefulWidget {
  6.   const StreamBuilderBase({ Key? key, this.stream }) : super(key: key);
  7.   final Stream<T>? stream;
  8.   S initial();
  9.   S afterConnected(S current) => current;
  10.   S afterData(S current, T data);
  11.   S afterError(S current, Object error, StackTrace stackTrace) => current;
  12.   S afterDone(S current) => current;
  13.   S afterDisconnected(S current) => current;
  14.   Widget build(BuildContext context, S currentSummary);
  15.   @override
  16.   State<StreamBuilderBase<T, S>> createState() => _StreamBuilderBaseState<T, S>();
  17. }
  19. class _StreamBuilderBaseState<T, S> extends State<StreamBuilderBase<T, S>> {
  20.   StreamSubscription<T>? _subscription; // ignore: cancel_subscriptions
  21.   late S _summary;
  23.   @override
  24.   void initState() {
  25.     super.initState();
  26.     _summary = widget.initial();
  27.     _subscribe();
  28.   }
  30.   @override
  31.   void didUpdateWidget(StreamBuilderBase<T, S> oldWidget) {
  32.     super.didUpdateWidget(oldWidget);
  33.     if (oldWidget.stream != widget.stream) {
  34.       if (_subscription != null) {
  35.         _unsubscribe();
  36.         _summary = widget.afterDisconnected(_summary);
  37.       }
  38.       _subscribe();
  39.     }
  40.   }
  42.   @override
  43.   Widget build(BuildContext context) => widget.build(context, _summary);
  45.   @override
  46.   void dispose() {
  47.     _unsubscribe();
  48.     super.dispose();
  49.   }
  51.   void _subscribe() {
  52.     if (widget.stream != null) {
  53.       _subscription = widget.stream!.listen((T data) {
  54.         setState(() {
  55.           _summary = widget.afterData(_summary, data);
  56.         });
  57.       }, onError: (Object error, StackTrace stackTrace) {
  58.         setState(() {
  59.           _summary = widget.afterError(_summary, error, stackTrace);
  60.         });
  61.       }, onDone: () {
  62.         setState(() {
  63.           _summary = widget.afterDone(_summary);
  64.         });
  65.       });
  66.       _summary = widget.afterConnected(_summary);
  67.     }
  68.   }
  70.   void _unsubscribe() {
  71.     if (_subscription != null) {
  72.       _subscription!.cancel();
  73.       _subscription = null;
  74.     }
  75.   }
  76. }
  78. enum ConnectionState {
  79.   none,
  81.   waiting,
  83.   active,
  85.   done,
  86. }
  88. @immutable
  89. class AsyncSnapshot<T> {
  90.   const AsyncSnapshot._(this.connectionState, this.data, this.error, this.stackTrace)
  91.     : assert(connectionState != null),
  92.       assert(!(data != null && error != null)),
  93.       assert(stackTrace == null || error != null);
  95.   const AsyncSnapshot.nothing() : this._(ConnectionState.none, null, null, null);
  97.   const AsyncSnapshot.waiting() : this._(ConnectionState.waiting, null, null, null);
  99.   const AsyncSnapshot.withData(ConnectionState state, T data): this._(state, data, null, null);
  101.   const AsyncSnapshot.withError(
  102.     ConnectionState state,
  103.     Object error, [
  104.     StackTrace stackTrace = StackTrace.empty,
  105.   ]) : this._(state, null, error, stackTrace);
  107.   final ConnectionState connectionState;
  109.   final T? data;
  111.   T get requireData {
  112.     if (hasData)
  113.       return data!;
  114.     if (hasError)
  115.       throw error!;
  116.     throw StateError('Snapshot has neither data nor error');
  117.   }
  119.   final Object? error;
  121.   final StackTrace? stackTrace;
  123.   AsyncSnapshot<T> inState(ConnectionState state) => AsyncSnapshot<T>._(state, data, error, stackTrace);
  125.   bool get hasData => data != null;
  127.   bool get hasError => error != null;
  129.   @override
  130.   String toString() => '${objectRuntimeType(this, 'AsyncSnapshot')}($connectionState, $data, $error, $stackTrace)';
  132.   @override
  133.   bool operator ==(Object other) {
  134.     if (identical(this, other))
  135.       return true;
  136.     return other is AsyncSnapshot<T>
  137.         && other.connectionState == connectionState
  138.         && other.data == data
  139.         && other.error == error
  140.         && other.stackTrace == stackTrace;
  141.   }
  143.   @override
  144.   int get hashCode => hashValues(connectionState, data, error);
  145. }
  147. typedef AsyncWidgetBuilder<T> = Widget Function(BuildContext context, AsyncSnapshot<T> snapshot);
  149. class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
  150.   const StreamBuilder({
  151.     Key? key,
  152.     this.initialData,
  153.     Stream<T>? stream,
  154.     required this.builder,
  155.   }) : assert(builder != null),
  156.        super(key: key, stream: stream);
  158.   final AsyncWidgetBuilder<T> builder;
  160.   final T? initialData;
  162.   @override
  163.   AsyncSnapshot<T> initial() => initialData == null
  164.       ? AsyncSnapshot<T>.nothing()
  165.       : AsyncSnapshot<T>.withData(ConnectionState.none, initialData as T);
  167.   @override
  168.   AsyncSnapshot<T> afterConnected(AsyncSnapshot<T> current) => current.inState(ConnectionState.waiting);
  170.   @override
  171.   AsyncSnapshot<T> afterData(AsyncSnapshot<T> current, T data) {
  172.     return AsyncSnapshot<T>.withData(ConnectionState.active, data);
  173.   }
  175.   @override
  176.   AsyncSnapshot<T> afterError(AsyncSnapshot<T> current, Object error, StackTrace stackTrace) {
  177.     return AsyncSnapshot<T>.withError(ConnectionState.active, error, stackTrace);
  178.   }
  180.   @override
  181.   AsyncSnapshot<T> afterDone(AsyncSnapshot<T> current) => current.inState(ConnectionState.done);
  183.   @override
  184.   AsyncSnapshot<T> afterDisconnected(AsyncSnapshot<T> current) => current.inState(ConnectionState.none);
  186.   @override
  187.   Widget build(BuildContext context, AsyncSnapshot<T> currentSummary) => builder(context, currentSummary);
  188. }
  190. // TODO(ianh): remove unreachable code above once https://github.com/dart-lang/sdk/issues/35520 is fixed
  191. class FutureBuilder<T> extends StatefulWidget {
  192.   const FutureBuilder({
  193.     Key? key,
  194.     this.future,
  195.     this.initialData,
  196.     required this.builder,
  197.   }) : assert(builder != null),
  198.        super(key: key);
  200.   final Future<T>? future;
  202.   final AsyncWidgetBuilder<T> builder;
  204.   final T? initialData;
  206.   static bool debugRethrowError = false;
  208.   @override
  209.   State<FutureBuilder<T>> createState() => _FutureBuilderState<T>();
  210. }
  212. class _FutureBuilderState<T> extends State<FutureBuilder<T>> {
  213.   Object? _activeCallbackIdentity;
  214.   late AsyncSnapshot<T> _snapshot;
  216.   @override
  217.   void initState() {
  218.     super.initState();
  219.     _snapshot = widget.initialData == null
  220.         ? AsyncSnapshot<T>.nothing()
  221.         : AsyncSnapshot<T>.withData(ConnectionState.none, widget.initialData as T);
  222.     _subscribe();
  223.   }
  225.   @override
  226.   void didUpdateWidget(FutureBuilder<T> oldWidget) {
  227.     super.didUpdateWidget(oldWidget);
  228.     if (oldWidget.future != widget.future) {
  229.       if (_activeCallbackIdentity != null) {
  230.         _unsubscribe();
  231.         _snapshot = _snapshot.inState(ConnectionState.none);
  232.       }
  233.       _subscribe();
  234.     }
  235.   }
  237.   @override
  238.   Widget build(BuildContext context) => widget.builder(context, _snapshot);
  240.   @override
  241.   void dispose() {
  242.     _unsubscribe();
  243.     super.dispose();
  244.   }
  246.   void _subscribe() {
  247.     if (widget.future != null) {
  248.       final Object callbackIdentity = Object();
  249.       _activeCallbackIdentity = callbackIdentity;
  250.       widget.future!.then<void>((T data) {
  251.         if (_activeCallbackIdentity == callbackIdentity) {
  252.           setState(() {
  253.             _snapshot = AsyncSnapshot<T>.withData(ConnectionState.done, data);
  254.           });
  255.         }
  256.       }, onError: (Object error, StackTrace stackTrace) {
  257.         if (_activeCallbackIdentity == callbackIdentity) {
  258.           setState(() {
  259.             _snapshot = AsyncSnapshot<T>.withError(ConnectionState.done, error, stackTrace);
  260.           });
  261.         }
  262.         assert(() {
  263.           if(FutureBuilder.debugRethrowError) {
  264.             Future<Object>.error(error, stackTrace);
  265.           }
  266.           return true;
  267.         }());
  269.       });
  270.       _snapshot = _snapshot.inState(ConnectionState.waiting);
  271.     }
  272.   }
  274.   void _unsubscribe() {
  275.     _activeCallbackIdentity = null;
  276.   }
  277. }