StreamBuilder：什么是 StreamBuilder、工作原理及在 Flutter 中的应用

什么是 StreamBuilder

StreamBuilder — 是 Flutter SDK 包中的一个小部件，它订阅 Stream 并在流的每次新事件中重建其子元素。StreamBuilder 接收一个 Stream 对象，并根据从流中获取的最新快照返回一个小部件。

在 Flutter 架构中，StreamBuilder 属于 Builder 小部件组，将 UI 构建与数据状态分离。与状态更改需要显式调用 setState 的 StatefulWidget 不同，StreamBuilder 自动响应异步事件，简化了代码并降低了同步错误的风险。

与处理单个异步值的 FutureBuilder 不同，StreamBuilder 专为连续数据流设计。FutureBuilder 在收到第一个结果后结束，而 StreamBuilder 继续监听流并在每个新事件中更新 UI。

StreamBuilder 用于数据持续到达的所有场景：WebSocket 连接、传感器回调、Firebase 通知、蓝牙事件队列和通过 BLoC 的应用程序状态广播。根据 GitHub 上的 Flutter 项目分析（2025），StreamBuilder 与 FutureBuilder 和 LayoutBuilder 一起位列三大最常用的 Builder 小部件。

结论：在 UI 需要反映持续变化的数据的任何地方使用 StreamBuilder，避免通过 StatefulWidget 进行手动状态管理。

StreamBuilder 如何工作

StreamBuilder 在构建时订阅 Stream，并在小部件销毁时取消订阅。每次 Stream 发出事件时，StreamBuilder 都会收到一个新的 AsyncSnapshot 并调用 builder 函数来重建 UI。

该过程包括三个阶段。第一：StreamBuilder 通过 stream.listen 方法在传入的 Stream 上创建订阅。第二：在每个事件中，StreamBuilder 更新内部 AsyncSnapshot 并将小部件标记为 “脏” 以进行重建。第三：框架使用新快照调用 builder 函数，UI 显示当前数据。

重要提示：StreamBuilder 在内部使用 StreamSubscription。如果直接传入 Stream，StreamBuilder 在初始化时订阅一次。如果 Stream 发生变化（例如，在父级重建时），StreamBuilder 会取消订阅旧流并订阅新流。此行为由 initialData 和 buildWhen 参数控制，这些参数允许优化重建次数。

结论：理解订阅的生命周期是正确使用 StreamBuilder 的基础。流管理不当会导致内存泄漏或 UI 中数据过时。

ConnectionState：流的四种状态

AsyncSnapshot 对象的 connectionState 属性确定 StreamBuilder 正处于处理流的哪个阶段。可分为四种状态：none、waiting、active、done。

ConnectionState.none

None — Stream 尚未开始传输数据的初始状态。在此状态下，snapshot.connectionState 等于 ConnectionState.none，snapshot.data 为 null。通常在此状态下显示占位符或等待第一个事件。如果 Stream 不提供初始数据，StreamBuilder 从此状态开始。

ConnectionState.waiting

Waiting — 等待来自异步流的数据的状态。Stream 处于活动状态，但数据尚未到达。例如，从网络加载数据或打开长期连接时会出现此状态。在此状态下，通常显示 CircularProgressIndicator 或加载骨架。

ConnectionState.active

Active — 流发出数据，UI 显示当前信息。在此状态下，snapshot.hasData 为 true，snapshot.data 包含流中的最新值。如果 Stream 是 Broadcast Stream，活动状态可以与等待新数据共存。

ConnectionState.done

Done — 流已完成，不再有新数据。Snapshot.data 包含流关闭前传递的最后一个值。如果流成功完成，snapshot.hasError 为 false。此状态用于显示最终结果：“加载完成” 消息或切换到下一个屏幕。

结论：通过 StreamBuilder 构建 UI 时，必须处理所有四种状态，以便界面正确显示加载、数据、错误和完成。

使用 StreamController 管理流

StreamController — 是 dart:async 包中的一个类，用于创建和管理 Stream。StreamController 允许添加数据、处理错误和关闭流，从而控制其生命周期。

StreamController 有两种类型：single-subscription（单个订阅者）和 broadcast（多个订阅者）。Single-subscription 控制器一次只接受一个监听器——重新订阅将引发异常。Broadcast 控制器允许多个 StreamBuilder 同时监听同一个流，这对于 BLoC 和共享应用程序状态非常有用。

通过 StreamController<T>.broadcast() 创建 StreamController 时，在首次订阅之前添加的数据不会重播给新订阅者。如果需要在连接时获取最新值，请使用 rxdart 包中的 BehaviourSubject，它会缓存最新事件。

完成控制器的工作后，必须调用 controller.close()。不调用 close 会导致资源泄漏：流保持打开状态，订阅者仍然留在内存中，GC 不会释放相关对象。

结论：使用具有明确生命周期管理的 StreamController。对于 single-subscription 流，使用标准控制器；对于共享状态，使用 broadcast 控制器或 BehaviourSubject。

StreamBuilder 代码示例

示例 1 演示了使用 StreamController 和 StreamBuilder 的倒计时计时器。

import 'dart:async';

class TimerWidget extends StatefulWidget {
  const TimerWidget({super.key});

  final StreamController<int> controller = StreamController<int>();

  void startTimer() {
    int count = 0;
    Timer.periodic(Duration(seconds: 1), (timer) {
      controller.sink.add(count++);
      if (count > 10) {
        controller.close();
        timer.cancel();
      }
    });
  }
}

在示例中，创建了一个控制器，用于以 1 秒的间隔生成 0 到 10 的数字。达到 10 后，调用 close，流结束。订阅此控制器流的 StreamBuilder 将显示每个新值。

示例 2 — 使用带有 Broadcast Stream 的 StreamBuilder 显示来自多个源的数据。

final StreamController<String> broadcastController =
    StreamController<String>.broadcast();

StreamBuilder<String>(
  stream: broadcastController.stream,
  initialData: 'Waiting for data...',
  builder: (context, AsyncSnapshot<String> snapshot) {
    if (snapshot.connectionState == ConnectionState.waiting) {
      return const Center(
        child: CircularProgressIndicator(),
      );
    }
    if (snapshot.hasError) {
      return Text('Error: ${snapshot.error}');
    }
    return Text('Data: ${snapshot.data}');
  },
)

第二个示例显示了所有状态的处理：initialData 用于初始显示，waiting 用于加载指示器，hasError 用于错误，data 用于成功结果。这种模式是使用 StreamBuilder 的生产代码的标准。

结论：使用 initialData 避免第一时间出现空白屏幕，并始终处理 hasError 以向用户正确显示错误。

使用 StreamBuilder 的常见错误

错误 1： 在每次父级重建时创建新的 Stream。如果 Stream 通过每次构建都创建新对象的表达式传递，StreamBuilder 会取消订阅旧流并订阅新流，导致无限重建循环。解决方法：使用 remembered 变量或具有固定 Stream 的 StatefulWidget。

错误 2： 缺少错误处理。Stream 可以通过 controller.sink.addError 发出错误，如果 builder 不检查 snapshot.hasError，用户将看到空白屏幕或无限加载。解决方法：始终检查 hasError 并显示易于理解的消息。

错误 3： 由于 StreamController 未关闭导致的内存泄漏。如果控制器未在 dispose 中关闭，流将继续存在，GC 不会释放内存。解决方法：在 dispose 中调用 controller.close() 并监听 done 事件以执行结束操作。

错误 4： 使用具有缓慢 builder 函数的 StreamBuilder。由于 builder 在流的每个事件中被调用，其中的繁重计算会导致丢帧。解决方法：将计算移动到单独的隔离区或使用 Stream.map 进行数据转换。

结论：StreamBuilder 是一个强大但要求严格的工具。关注 Stream 的生命周期，处理错误，并避免在 builder 中进行繁重操作。