Dart Stream

Stream est le mécanisme en Dart pour gérer des séquences d’événements asynchrones continus.

Si Future est un résultat asynchrone ponctuel, alors Stream est un flux de données asynchrone répété et continu.

Ce chapitre présente le concept de Stream, l’écoute avec await for, la création de StreamController, et les différences entre les streams single-subscription et broadcast.


Streams et séquences d’événements

Un Stream est comme un tapis roulant ; les données arrivent une par une au fil du temps.

Vous n’avez pas besoin d’attendre toutes les données d’un coup ; au lieu de cela, vous traitez chaque élément au fur et à mesure qu’il arrive.

Cas d’utilisation typiques des Streams :

ScénariosExemple
Événements d’entrée utilisateurClics de bouton, mouvements de souris, saisie au clavier
Lecture de fichiersLire de gros fichiers ligne par ligne
Données réseauMessages WebSocket, API en temps réel
MinuteurÉvénements de type Timer qui se déclenchent une fois par seconde
Changements d’étatFlux de gestion d’état dans Flutter.

Exemple

Utilisation de base de Stream — écoute avec listen :

void main() {
  // Créer un Stream : émettre un nombre toutes les 1 seconde
  var stream = Stream<int>.periodic(
    Duration(seconds: 1),
    (count) => count + 1,  // count commence à 0
  );

  print('Début de l’écoute du Stream...');

  // listen s’abonne au Stream
  var subscription = stream.listen(
    (data) {
      // Appelé chaque fois que de nouvelles données arrivent
      print('DONNÉES D'EXEMPLE : $data');
    },
    onError: (error) {
      // Appelé lorsque Stream rencontre une erreur
      print('Erreur : $error');
    },
    onDone: () {
      // Appelé lorsque Stream est fermé
      print('Flux fermé');
    },
  );

  // Appel de l'abonnement après 5 secondes
  Future.delayed(Duration(seconds: 5), () {
    subscription.cancel();
    print('Abonnement annulé');
  });
}
开始监听 Stream...
EXAMPLE 收到数据: 1
EXAMPLE 收到数据: 2
EXAMPLE 收到数据: 3
EXAMPLE 收到数据: 4
EXAMPLE 收到数据: 5
已取消订阅

listen() renvoie un objet StreamSubscription, que vous pouvez utiliser pour contrôler l’abonnement :

MéthodesFonction
subscription.pause()Mettre en pause la réception des données
subscription.resume()Reprendre la réception des données
subscription.cancel()Annuler l’abonnement
subscription.isPausedIndique s’il est dans un état en pause

Écouter avec await for

Outre l’approche par rappel listen(), vous pouvez également utiliser une boucle await for pour consommer un Stream.

await for rend la logique de traitement d’un Stream aussi claire qu’une boucle for ordinaire.

Exemple

// Générer un flux de données fini
Stream<int> countStream(int max) async* {
  for (int i = 1; i <= max; i++) {
    await Future.delayed(Duration(milliseconds: 300));
    yield i;  // yield émet des données vers le Stream
  }
}

Future<void> main() async {
  print('Commencer à consommer le Stream avec await for...');

  // await for : attendre que chaque donnée arrive et la traiter une par une
  await for (var value in countStream(5)) {
    print('EXEMPLE compteur : $value');
  }

  print('Consommation du Stream terminée');
}
开始用 await for 消费 Stream...
EXAMPLE 计数: 1
EXAMPLE 计数: 2
EXAMPLE 计数: 3
EXAMPLE 计数: 4
EXAMPLE 计数: 5
Stream 消费完毕

Caractéristiques de await for :

  • La syntaxe est similaire à une boucle for normale, mais chaque itération attend que la prochaine donnée arrive.
  • Lorsque le Stream se ferme, la boucle se termine automatiquement.
  • Cela ne peut être utilisé que dans des fonctions async.
  • Si vous devez sortir plus tôt, utilisez break (comme dans une boucle for normale).

await for convient aux scénarios où vous devez traiter toutes les données séquentiellement, comme la lecture de toutes les lignes d'un fichier. listen() convient aux scénarios où vous devez répondre à des événements en continu, comme des clics de bouton. Les deux peuvent se remplacer, mais chacun a ses propres atouts.


StreamController crée Stream

StreamController est un outil pour créer et contrôler manuellement des Streams.

Vous pouvez ajouter des données, des erreurs ou le fermer à tout moment.

Exemple

import 'dart:async';

// Utiliser StreamController pour implémenter un minuteur de compte à rebours simple
class CountdownTimer {
  final StreamController<int> _controller = StreamController<int>();
  Timer? _timer;
  int _remaining = 0;

  // Exposer le Stream pour un abonnement externe
  Stream<int> get tickStream => _controller.stream;

  // Démarrer le compte à rebours
  void start(int seconds) {
    _remaining = seconds;

    // Envoyer immédiatement la valeur initiale
    _controller.add(_remaining);

    _timer = Timer.periodic(Duration(seconds: 1), (timer) {
      _remaining--;

      if (_remaining > 0) {
        _controller.add(_remaining);  // Envoyer les données
      } else {
        _controller.add(0);           // Envoyer le 0 final
        _controller.close();          // Fermer le flux
        timer.cancel();
      }
    });
  }

  // Annuler le compte à rebours
  void cancel() {
    _timer?.cancel();
    _controller.addError('Compte à rebours annulé');  // Envoyer une erreur
    _controller.close();
  }

  // Libérer les ressources
  void dispose() {
    _controller.close();
  }
}

Future<void> main() async {
  var timer = CountdownTimer();

  // S'abonner à l'événement de compte à rebours
  timer.tickStream.listen(
    (remaining) {
      print('EXEMPLE compte à rebours : $remaining secondes');
    },
    onError: (error) {
      print('Erreur : $error');
    },
    onDone: () {
      print('Compte à rebours terminé !');
    },
  );

  timer.start(5);

  // Attendre que le compte à rebours soit terminé
  await Future.delayed(Duration(seconds: 6));
  timer.dispose();
}
EXAMPLE 倒计时: 5 秒
EXAMPLE 倒计时: 4 秒
EXAMPLE 倒计时: 3 秒
EXAMPLE 倒计时: 2 秒
EXAMPLE 倒计时: 1 秒
EXAMPLE 倒计时: 0 秒
倒计时结束!

Fonctions génératrices async*

Si vous avez seulement besoin de générer simplement une séquence de données, async* est plus pratique que StreamController.

Exemple

// async* indique qu'il s'agit d'une fonction génératrice asynchrone
// Le type de retour doit être Stream
Stream<String> readLinesAsync() async* {
  var lines = ['Première ligne', 'Deuxième ligne', 'Troisième ligne', 'EXEMPLE'];

  for (var line in lines) {
    await Future.delayed(Duration(milliseconds: 500));
    yield line;  // yield émet des données vers le Stream
  }
  // Stream se ferme automatiquement lorsque la fonction se termine
}

// Générateur asynchrone avec gestion des erreurs
Stream<int> generateNumbersWithError() async* {
  for (int i = 1; i <= 5; i++) {
    await Future.delayed(Duration(milliseconds: 300));

    if (i == 3) {
      throw Exception('Le nombre 3 a eu une erreur !');
    }
    yield i;
  }
}

Future<void> main() async {
  print('Lecture ligne par ligne :');
  await for (var line in readLinesAsync()) {
    print(' $line');
  }

  print('\n'Générateur avec des erreurs :');
  try {
    await for (var num in generateNumbersWithError()) {
      print(' Nombre : $num');
    }
  } catch (e) {
    print(' Erreur interceptée : $e');
  }
}
逐行读取:
  第一行
  第二行
  第三行
  EXAMPLE

带错误的生成器:
  数字: 1
  数字: 2
  捕获错误: Exception: 数字 3 出错了!

Flux à abonnement unique vs. flux de diffusion

Les flux Dart sont divisés en deux types : les flux à abonnement unique et les flux de diffusion.

Flux à abonnement unique

Il s'agit du type de flux par défaut.

Il ne peut être souscrit que par un seul écouteur, adapté aux scénarios où vous le consommez une seule fois du début à la fin.

Exemple

void main() {
  // Flux à abonnement unique (par défaut)
  var stream = Stream.fromIterable([1, 2, 3]);

  // Premier abonnement : OK
  stream.listen((data) => print('Abonné 1 : $data'));

  // Deuxième abonnement : Erreur ! Un flux à abonnement unique ne peut pas être abonné plusieurs fois
  // stream.listen((data) => print('Abonné 2 : $data')); // erreur d'exécution
}

Flux de diffusion

Les flux de diffusion permettent à plusieurs écouteurs de s'abonner simultanément, ce qui convient aux scénarios de diffusion d'événements.

Exemple

import 'dart:async';

void main() {
  // Créer un flux de diffusion
  var controller = StreamController<int>.broadcast();

  // Plusieurs abonnés peuvent écouter simultanément
  controller.stream.listen(
    (data) => print('EXEMPLE Abonné A : a reçu $data'),
  );

  controller.stream.listen(
    (data) => print('EXEMPLE Abonné B : a reçu $data'),
  );

  // Envoyer des données, les deux abonnés les recevront
  controller.add(1);
  controller.add(2);
  controller.add(3);

  // Un abonnement tardif peut encore recevoir les données suivantes (mais pas les données précédentes)
  Future.delayed(Duration(seconds: 1), () {
    controller.stream.listen(
      (data) => print('EXEMPLE Abonné tardif C : a reçu $data'),
    );
    controller.add(4);
    controller.close();
  });
}
EXAMPLE 订阅者A: 收到 1
EXAMPLE 订阅者B: 收到 1
EXAMPLE 订阅者A: 收到 2
EXAMPLE 订阅者B: 收到 2
EXAMPLE 订阅者A: 收到 3
EXAMPLE 订阅者B: 收到 3
EXAMPLE 订阅者A: 收到 4
EXAMPLE 订阅者B: 收到 4
EXAMPLE 迟到的订阅者C: 收到 4

Comparaison des deux types de Streams :

FonctionnalitésStream à abonnement uniqueFlux de diffusion
Nombre d'abonnésUn seulMultiple
Rejeu des donnéesConsommer depuis le débutNe reçoit des données qu'après l'abonnement
Scénarios typiquesLecture de fichiers, réponses HTTPClics sur des boutons, notifications d'état
Méthode de créationStreamController()StreamController.broadcast()

Un "abonné tardif" à un flux de diffusion ne peut recevoir des événements qu'après s'être abonné ; les événements précédents ont déjà été manqués. C'est la différence de comportement la plus importante entre les flux de diffusion et les flux à abonnement unique.


Méthodes courantes de transformation de Stream

Stream fournit une série de méthodes pour transformer et traiter des données, similaires aux méthodes fonctionnelles de List.

Exemple

void main() async {
  var numbers = Stream.fromIterable([1, 2, 3, 4, 5, 6]);

  // map : transformer chaque élément de données
  var doubled = numbers.map((n) => n * 2);
  print('Doubled:');
  await for (var n in doubled) {
    print('  $n');
  }

  // where : filtrer les données
  var source = Stream.fromIterable([10, 15, 20, 25, 30]);
  var even = source.where((n) => n % 2 == 0);
  print('Pair :');
  await for (var n in even) {
    print('  $n');
  }

  // take : prendre uniquement les N premiers éléments
  var infinite = Stream.periodic(
    Duration(milliseconds: 100),
    (i) => i + 1,
  );
  print('Prendre uniquement les 3 premiers :');
  await for (var n in infinite.take(3)) {
    print(' EXEMPLE : $n');
  }

  // skip : sauter les N premiers éléments
  var data = Stream.fromIterable([1, 2, 3, 4, 5]);
  print('Sauter les 2 premiers :');
  await for (var n in data.skip(2)) {
    print('  $n');
  }

  // distinct: supprimer les doublons
  var duplicates = Stream.fromIterable([1, 2, 2, 3, 3, 3]);
  print('Distinct:');
  await for (var n in duplicates.distinct()) {
    print('  $n');
  }
}
翻倍:
  2
  4
  6
  8
  10
  12
偶数:
  10
  20
  30
只取前 3 个:
  EXAMPLE: 1
  EXAMPLE: 2
  EXAMPLE: 3
跳过前 2 个:
  3
  4
  5
去重:
  1
  2
  3
autres extensions