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:
| Escenario | Ejemplo |
|---|---|
| Eventos de entrada del usuario | Clic de botón, movimiento del ratón, entrada de teclado |
| Lectura de archivos | Leer archivos grandes línea por línea |
| Datos de red | Mensajes WebSocket, API en tiempo real |
| Temporizador | Evento de temporizador que se dispara cada segundo |
| Cambios de estado | Flujos de gestión de estado en Flutter |
Ejemplo
Uso básico de Stream: escuchar con listen.
// 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étodo | Función |
|---|---|
| subscription.pause() | Pausar la recepción de datos |
| subscription.resume() | Reanudar la recepción de datos |
| subscription.cancel() | Cancelar la suscripción |
| subscription.isPaused | Si 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
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
// 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
// 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
// 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
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ística | Stream de suscripción única | Stream de difusión |
|---|---|---|
| Número de suscriptores | Solo uno | Pueden ser varios |
| Reproducción de datos | Consumir desde el principio | Solo recibe datos posteriores a la suscripción |
| Escenario típico | Lectura de archivos, respuestas HTTP | Clic de botón, notificaciones de estado |
| Método de creación | StreamController() | 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
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 3Otras extensiones