StreamBuilder: какво е, принцип на работа и приложение във Flutter

Какво е StreamBuilder

StreamBuilder — е уиджет от пакета Flutter SDK, който се абонира за Stream и преизгражда своя дъщерен елемент при всяко ново събитие на потока. StreamBuilder приема Stream обект и връща уиджет въз основа на последната моментна снимка, получена от потока.

В архитектурата на Flutter, StreamBuilder принадлежи към групата на Builder-уиджетите, които отделят изграждането на UI от състоянието на данните. За разлика от StatefulWidget, където промяната на състоянието изисква изрично извикване на setState, StreamBuilder реагира на асинхронни събития автоматично, което опростява кода и намалява риска от грешки при синхронизация.

За разлика от FutureBuilder, който обработва единична асинхронна стойност, StreamBuilder е предназначен за непрекъснати потоци от данни. FutureBuilder приключва след получаване на първия резултат, докато StreamBuilder продължава да слуша потока и да обновява UI при всяко ново събитие.

StreamBuilder се използва във всички сценарии, където данните пристигат непрекъснато: WebSocket връзки, обратни извиквания на сензори, известия от Firebase, опашки от Bluetooth събития и предаване на състоянието на приложението чрез BLoC. Според анализ на Flutter проекти в GitHub (2025), StreamBuilder е сред трите най-използвани Builder-уиджета, заедно с FutureBuilder и LayoutBuilder.

Заключение: използвайте StreamBuilder навсякъде, където UI трябва да отразява непрекъснато променящи се данни, избягвайки ръчно управление на състоянието чрез StatefulWidget.

Как работи StreamBuilder

StreamBuilder се абонира за Stream в момента на изграждане и се отписва при унищожаване на уиджета. Всеки път, когато Stream излъчва събитие, StreamBuilder получава нов AsyncSnapshot и извиква builder функцията за преизграждане на UI.

Процесът се състои от три етапа. Първи: StreamBuilder създава абонамент за подадения Stream чрез метода stream.listen. Втори: при всяко събитие StreamBuilder обновява вътрешния AsyncSnapshot и маркира уиджета като „замърсен“ за преизграждане. Трети: рамката извиква builder функцията с новата моментна снимка и UI показва актуалните данни.

Важно: StreamBuilder използва вътрешно StreamSubscription. Ако Stream е подаден директно, StreamBuilder се абонира веднъж при инициализация. Ако Stream се промени (например при преизграждане на родителя), StreamBuilder се отписва от стария поток и се абонира за новия. Това поведение се контролира от параметрите initialData и buildWhen, които позволяват оптимизиране на броя преизграждания.

Заключение: разбирането на жизнения цикъл на абонамента е основата за правилното използване на StreamBuilder. Неправилното управление на потоците води до изтичане на памет или остарели данни в UI.

ConnectionState: четири състояния на потока

Свойството connectionState на обекта AsyncSnapshot определя на кой етап от работата с потока се намира StreamBuilder. Различават се четири състояния: none, waiting, active, done.

ConnectionState.none

None — начално състояние, когато Stream все още не е започнал да предава данни. В това състояние snapshot.connectionState е равно на ConnectionState.none, а snapshot.data е null. Обикновено в това състояние се показва placeholder или изчакване на първото събитие. Ако 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. Това състояние се използва за показване на крайния резултат: съобщение „Зареждането завърши“ или преход към следващия екран.

Заключение: при изграждане на UI чрез StreamBuilder трябва да се обработват всичките четири състояния, за да може интерфейсът правилно да показва зареждане, данни, грешки и завършване.

Използване на StreamController за управление на потока

StreamController — е клас от пакета dart:async, който създава и управлява Stream. StreamController позволява добавяне на данни, обработка на грешки и затваряне на потока, контролирайки неговия жизнен цикъл.

StreamController бива два типа: single-subscription (един абонат) и broadcast (множество абонати). Single-subscription контролерът приема само един слушател наведнъж — повторното абониране ще предизвика изключение. Broadcast контролерът позволява на няколко StreamBuilder едновременно да слушат един поток, което е полезно за BLoC и споделено състояние на приложението.

При създаване на StreamController чрез StreamController<T>.broadcast(), данните, добавени преди първия абонамент, не се възпроизвеждат на новия абонат. Ако трябва да получите последната стойност при свързване, използвайте BehaviourSubject от пакета rxdart, който кешира последното събитие.

След приключване на работа с контролера трябва да се извика 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();
      }
    });
  }
}

В примера се създава контролер за генериране на числа от 0 до 10 с интервал от 1 секунда. След достигане на 10 се извиква close и потокът приключва. StreamBuilder, абониран за stream на този контролер, ще показва всяка нова стойност.

Пример 2 — използване на StreamBuilder с Broadcast Stream за показване на данни от множество източници.

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 променлива или StatefulWidget с фиксиран Stream.

Грешка 2: липса на обработка на грешки. Stream може да излъчва грешки чрез controller.sink.addError и ако builder не проверява snapshot.hasError, потребителят вижда празен екран или безкрайно зареждане. Решение: винаги проверявайте hasError и показвайте разбираемо съобщение.

Грешка 3: изтичане на памет поради незатворен StreamController. Ако контролерът не е затворен в dispose, потокът продължава да съществува и GC не освобождава памет. Решение: извиквайте controller.close() в dispose и слушайте done събитието за заключителни действия.

Грешка 4: използване на StreamBuilder с бавна builder функция. Тъй като builder се извиква при всяко събитие на потока, тежките изчисления вътре в него водят до пропускане на кадри. Решение: преместете изчисленията в отделен изолат или използвайте Stream.map за трансформация на данни.

Заключение: StreamBuilder е мощен, но взискателен инструмент. Следете жизнения цикъл на Stream, обработвайте грешки и избягвайте тежки операции в builder.