Dart Stream (Flujo)

Stream (flujo) es el mecanismo en Dart para manejar secuencias continuas de eventos asíncronos.

Si Future es un resultado asíncrono de una sola vez, Stream es un flujo de datos asíncrono múltiple y continuo.

Este capítulo introduce el concepto de Stream, la escucha con await for, la creación con StreamController y la diferencia entre suscripción única y stream de difusión.


Stream y secuencias de eventos

Stream es como una cinta transportadora: los datos van llegando uno a uno con el paso del tiempo.

No necesitas esperar todos los datos de una vez, sino procesarlos a medida que llegan.

Casos de uso típicos de Stream:

EscenarioEjemplo
Eventos de entrada del usuarioClic de botón, movimiento del ratón, entrada de teclado
Lectura de archivosLeer archivos grandes línea por línea
Datos de redMensajes WebSocket, API en tiempo real
TemporizadorEvento de temporizador que se dispara cada segundo
Cambios de estadoFlujos de gestión de estado en Flutter

Ejemplo

Uso básico de Stream: escuchar con listen.

void main() {
  // Crea un Stream: emite un número cada 1 segundo
  var stream = Stream<int>.periodic(
    Duration(seconds: 1),
    (count) => count + 1,  // count comienza desde 0
  );

  print('Comenzando a escuchar el Stream...');

  // listen se suscribe al Stream
  var subscription = stream.listen(
    (data) {
      // Se llama cada vez que llegan nuevos datos
      print('EJEMPLO recibió datos: $data');
    },
    onError: (error) {
      // Se llama cuando el Stream produce un error
      print('Error: $error');
    },
    onDone: () {
      // Se llama cuando el Stream se cierra
      print('Stream cerrado');
    },
  );

  // Cancelar la suscripción después de 5 segundos
  Future.delayed(Duration(seconds: 5), () {
    subscription.cancel();
    print('Suscripción cancelada');
  });
}
开始监听 Stream...
EJEMPLO 收到数据: 1
EJEMPLO 收到数据: 2
EJEMPLO 收到数据: 3
EJEMPLO 收到数据: 4
EJEMPLO 收到数据: 5
已取消订阅

listen() devuelve un objeto StreamSubscription, que puedes usar para controlar la suscripción:

MétodoFunción
subscription.pause()Pausar la recepción de datos
subscription.resume()Reanudar la recepción de datos
subscription.cancel()Cancelar la suscripción
subscription.isPausedSi está en estado de pausa

Escucha con await for

Además del método de callback listen(), también puedes usar un bucle await for para consumir el Stream.

await for hace que la lógica de procesamiento del Stream sea tan clara como un bucle for normal.

Ejemplo

// Genera un flujo de datos finito
Stream<int> countStream(int max) async* {
  for (int i = 1; i <= max; i++) {
    await Future.delayed(Duration(milliseconds: 300));
    yield i;  // yield envía datos al Stream
  }
}

Future<void> main() async {
  print('Comenzando a consumir Stream con await for...');

  // await for: espera a que llegue cada dato y lo procesa uno por uno
  await for (var value in countStream(5)) {
    print('EJEMPLO contador: $value');
  }

  print('Stream consumido por completo');
}
开始用 await for 消费 Stream...
EJEMPLO 计数: 1
EJEMPLO 计数: 2
EJEMPLO 计数: 3
EJEMPLO 计数: 4
EJEMPLO 计数: 5
Stream 消费完毕

Características de await for:

  • Su sintaxis es similar a un bucle for normal, pero cada iteración espera a que llegue el siguiente dato
  • Cuando el Stream se cierra, el bucle termina automáticamente
  • Solo se puede usar en funciones async
  • Si necesitas salir a mitad de camino, usa break (igual que en un bucle for normal)

await for es adecuado para escenarios "donde se necesita procesar todos los datos en orden", como leer todas las líneas de un archivo. listen() es adecuado para escenarios "donde se necesita responder continuamente a eventos", como clics de botón. Ambos pueden sustituirse entre sí, pero cada uno tiene su área de especialización.


Crear un Stream con StreamController

StreamController es la herramienta para crear y controlar un Stream manualmente.

Puedes añadirle datos, errores o cerrarlo en cualquier momento.

Ejemplo

import 'dart:async';

// Usa StreamController para implementar un simple contador regresivo
class CountdownTimer {
  final StreamController<int> _controller = StreamController<int>();
  Timer? _timer;
  int _remaining = 0;

  // Expone el Stream para suscripción externa
  Stream<int> get tickStream => _controller.stream;

  // Inicia la cuenta regresiva
  void start(int seconds) {
    _remaining = seconds;

    // Envía el valor inicial inmediatamente
    _controller.add(_remaining);

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

      if (_remaining > 0) {
        _controller.add(_remaining);  // Envía datos
      } else {
        _controller.add(0);           // Envía el último 0
        _controller.close();          // Cierra el Stream
        timer.cancel();
      }
    });
  }

  // Cancela la cuenta regresiva
  void cancel() {
    _timer?.cancel();
    _controller.addError('Cuenta regresiva cancelada');  // Envía un error
    _controller.close();
  }

  // Libera recursos
  void dispose() {
    _controller.close();
  }
}

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

  // Se suscribe a los eventos de cuenta regresiva
  timer.tickStream.listen(
    (remaining) {
      print('EJEMPLO cuenta regresiva: $remaining segundos');
    },
    onError: (error) {
      print('Error: $error');
    },
    onDone: () {
      print('¡Cuenta regresiva terminada!');
    },
  );

  timer.start(5);

  // Espera a que termine la cuenta regresiva
  await Future.delayed(Duration(seconds: 6));
  timer.dispose();
}
EJEMPLO 倒计时: 5 秒
EJEMPLO 倒计时: 4 秒
EJEMPLO 倒计时: 3 秒
EJEMPLO 倒计时: 2 秒
EJEMPLO 倒计时: 1 秒
EJEMPLO 倒计时: 0 秒
倒计时结束!

Funciones generadoras async*

Si solo necesitas generar una secuencia de datos de forma simple, async* es más conveniente que StreamController.

Ejemplo

// async* marca esta función como una función generadora asíncrona
// El tipo de retorno debe ser Stream
Stream<String> readLinesAsync() async* {
  var lines = ['Primera línea', 'Segunda línea', 'Tercera línea', 'EJEMPLO'];

  for (var line in lines) {
    await Future.delayed(Duration(milliseconds: 500));
    yield line;  // yield envía datos al Stream
  }
  // Cuando la función termina, el Stream se cierra automáticamente
}

// Generador asíncrono con manejo de errores
Stream<int> generateNumbersWithError() async* {
  for (int i = 1; i <= 5; i++) {
    await Future.delayed(Duration(milliseconds: 300));

    if (i == 3) {
      throw Exception('¡El número 3 dio error!');
    }
    yield i;
  }
}

Future<void> main() async {
  print('Leyendo línea por línea:');
  await for (var line in readLinesAsync()) {
    print('  $line');
  }

  print('\nGenerador con errores:');
  try {
    await for (var num in generateNumbersWithError()) {
      print(' Número: $num');
    }
  } catch (e) {
    print(' Error capturado: $e');
  }
}
逐行读取:
  第一行
  第二行
  第三行
  EJEMPLO

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

Suscripción única vs. Stream de difusión

Los Streams en Dart se dividen en dos tipos: stream de suscripción única (Single-subscription) y stream de difusión (Broadcast).

Stream de suscripción única (Single-subscription Stream)

Este es el tipo de Stream predeterminado.

Solo puede ser suscrito por un único oyente, adecuado para escenarios de "consumir de principio a fin una sola vez".

Ejemplo

void main() {
  // Stream de suscripción única (predeterminado)
  var stream = Stream.fromIterable([1, 2, 3]);

  // Primera suscripción: OK
  stream.listen((data) => print('Suscriptor 1: $data'));

  // Segunda suscripción: ¡error! Un stream de suscripción única no puede tener múltiples suscripciones
  // stream.listen((data) => print('Suscriptor 2: $data')); // Error en tiempo de ejecución
}

Stream de difusión (Broadcast Stream)

Un stream de difusión permite que varios oyentes se suscriban simultáneamente, adecuado para escenarios de radiodifusión de eventos.

Ejemplo

import 'dart:async';

void main() {
  // Crea un stream de difusión
  var controller = StreamController<int>.broadcast();

  // Múltiples suscriptores pueden escuchar al mismo tiempo
  controller.stream.listen(
    (data) => print('EJEMPLO Suscriptor A: recibido $data'),
  );

  controller.stream.listen(
    (data) => print('EJEMPLO Suscriptor B: recibido $data'),
  );

  // Envía datos; ambos suscriptores los recibirán
  controller.add(1);
  controller.add(2);
  controller.add(3);

  // Una suscripción tardía también puede recibir datos posteriores (pero no los anteriores)
  Future.delayed(Duration(seconds: 1), () {
    controller.stream.listen(
      (data) => print('EJEMPLO Suscriptor C tardío: recibido $data'),
    );
    controller.add(4);
    controller.close();
  });
}
EJEMPLO 订阅者A: 收到 1
EJEMPLO 订阅者B: 收到 1
EJEMPLO 订阅者A: 收到 2
EJEMPLO 订阅者B: 收到 2
EJEMPLO 订阅者A: 收到 3
EJEMPLO 订阅者B: 收到 3
EJEMPLO 订阅者A: 收到 4
EJEMPLO 订阅者B: 收到 4
EJEMPLO 迟到的订阅者C: 收到 4

Comparación de los dos tipos de Stream:

CaracterísticaStream de suscripción únicaStream de difusión
Número de suscriptoresSolo unoPueden ser varios
Reproducción de datosConsumir desde el principioSolo recibe datos posteriores a la suscripción
Escenario típicoLectura de archivos, respuestas HTTPClic de botón, notificaciones de estado
Método de creaciónStreamController()StreamController.broadcast()

En un stream de difusión, los "suscriptores tardíos" solo pueden recibir eventos posteriores a su suscripción; los eventos anteriores ya se han perdido. Esta es la diferencia de comportamiento más importante entre un stream de difusión y un stream de suscripción única.


Métodos de transformación comunes en Stream

Stream proporciona una serie de métodos para transformar y procesar datos, similares a los métodos funcionales de List.

Ejemplo

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

  // map: transforma cada dato
  var doubled = numbers.map((n) => n * 2);
  print('Doblado:');
  await for (var n in doubled) {
    print('  $n');
  }

  // where: filtra datos
  var source = Stream.fromIterable([10, 15, 20, 25, 30]);
  var even = source.where((n) => n % 2 == 0);
  print('Pares:');
  await for (var n in even) {
    print('  $n');
  }

  // take: solo toma los primeros N
  var infinite = Stream.periodic(
    Duration(milliseconds: 100),
    (i) => i + 1,
  );
  print('Solo toma los primeros 3:');
  await for (var n in infinite.take(3)) {
    print('  EJEMPLO: $n');
  }

  // skip: omite los primeros N
  var data = Stream.fromIterable([1, 2, 3, 4, 5]);
  print('Omite los primeros 2:');
  await for (var n in data.skip(2)) {
    print('  $n');
  }

  // distinct: elimina duplicados
  var duplicates = Stream.fromIterable([1, 2, 2, 3, 3, 3]);
  print('Duplicados eliminados:');
  await for (var n in duplicates.distinct()) {
    print('  $n');
  }
}
翻倍:
  2
  4
  6
  8
  10
  12
偶数:
  10
  20
  30
只取前 3 个:
  EJEMPLO: 1
  EJEMPLO: 2
  EJEMPLO: 3
跳过前 2 个:
  3
  4
  5
去重:
  1
  2
  3
Otras extensiones