کار با جریان‌های داده (Streams) و StreamBuilder

Asynchronous programming: Streams

تفاوت Future و Stream در Dart، نحوه گوش دادن به داده‌های پیوسته با await for و listen و اتصال به UI با StreamBuilder

فهرست مطالب این صفحه

در حالی که یک Future تنها یک مقدار واحد (یا یک خطا) را در آینده تحویل می‌دهد، یک Stream دنباله‌ای از رویدادها و داده‌های ناهمگام را در طول زمان تولید می‌کند (مانند دریافت پیام‌های چت زنده، تغییرات موقعیت GPS یا وضعیت اتصال شبکه).

۱. ایجاد یک Stream با async* و yield

توابع مولد ناهمگام با علامت async* تعریف می‌شوند و با کلیدواژه yield مقادیر را به‌صورت پیوسته به جریان ارسال می‌کنند:

Dart
Stream<int> countStream(int maxCount) async* {
  for (int i = 1; i <= maxCount; i++) {
    await Future.delayed(const Duration(seconds: 1));
    yield i;
  }
}

Future<void> main() async {
  await for (final value in countStream(5)) {
    print('مقدار جدید دریافت شد: $value');
  }
}

۲. دو نوع Stream در Dart

  1. Single-Subscription Stream (تک‌مشترک): نوع پیش‌فرض است و فقط یک شنونده (listener) می‌تواند به آن متصل شود؛ داده‌ها را از ابتدا تا انتها به ترتیب تحویل می‌دهد (مانند خواندن یک فایل).
  2. Broadcast Stream (پخش همگانی): به چندین شنونده اجازه می‌دهد هم‌زمان به رویدادها گوش دهند (مانند رویدادهای رابط کاربری یا وضعیت احراز هویت).

۳. استفاده از StreamController برای مدیریت دستی جریان

Dart
import 'dart:async';

void main() {
  final controller = StreamController<String>.broadcast();

  final subscription = controller.stream.listen(
    (data) => print('رویداد: $data'),
    onError: (err) => print('خطا: $err'),
    onDone: () => print('جریان بسته شد'),
  );

  controller.sink.add('پیام اول');
  controller.sink.add('پیام دوم');

  subscription.cancel();
  controller.close();
}

نکته در Flutter: برای نمایش مستقیم داده‌های یک Stream در رابط کاربری فلاتر، از ویجت StreamBuilder استفاده کنید و حتماً StreamController را در متد dispose() ببندید (controller.close()).